POST /billing/plan
Console: choose Free on the plan step. Paid plans go through POST /billing/checkout. Idempotent; owner only.
Parameters
Idempotency-Keyheader · string · optional — Makes this call safe to retry. Send the same key with the same body and the original response is replayed instead of the work happening twice. Keys are 1-256 characters and are remembered for 7 days. While the first attempt is still running, a second call with that key returns 409 idempotency_in_flight (Resend calls this concurrent_idempotent_requests); the same key with a different body returns 409 idempotency_payload_mismatch (Resend: invalid_idempotent_request). Resend-Idempotency-Key is accepted as the same header.Resend-Idempotency-Keyheader · string · optional — Alias of Idempotency-Key. Idempotency-Key wins if both are sent.
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
| tier | string | yes |
Responses
201— Success400— Validation error401— Missing API key403— Forbidden404— Not found409— Conflict429— Rate limited500— Internal server error
Response headers
ratelimit-limit— Messages this API key may spend in one 60-second window.ratelimit-remaining— Messages left in the current window.ratelimit-reset— Seconds until the current window resets and the budget refills.
201 body
| Field | Type | Required | Notes |
|---|---|---|---|
| billing_configured | boolean | yes | |
| billing_term | "month" | "year" | null | yes | |
| entitlements | object | yes | |
| entitlements.included_emails_per_month | integer | yes | |
| entitlements.max_domains | integer | null | yes | |
| entitlements.max_seats | integer | yes | |
| entitlements.overage_minor_per_1000_emails | integer | null | yes | |
| entitlements.retention_days | integer | yes | |
| entitlements.tier | "free" | "starter" | "pro" | "scale" | yes | |
| needs_plan_selection | boolean | yes | |
| plan_status | "none" | "trialing" | "active" | "past_due" | "canceled" | yes | |
| plans | array<object> | yes | |
| plans[].featured | boolean | yes | |
| plans[].included_emails_per_month | integer | yes | |
| plans[].max_domains | integer | null | yes | |
| plans[].max_seats | integer | yes | |
| plans[].name | string | yes | |
| plans[].prices | object | yes | |
| plans[].retention_days | integer | yes | |
| plans[].tier | "starter" | "pro" | "scale" | yes | |
| plans[].volume_rungs | array<object> | yes | |
| purchasable | array<object> | yes | |
| purchasable[].included_emails_per_month | integer | yes | |
| purchasable[].monthly_price_minor | integer | yes | |
| purchasable[].tier | "starter" | "pro" | "scale" | yes | |
| subscription | object | null | yes | |
| terms_on_sale | array<"month" | "year"> | yes | |
| tier | "free" | "starter" | "pro" | "scale" | yes | |
| viewer | object | yes | |
| viewer.can_purchase | boolean | yes | |
| viewer.role | "owner" | "admin" | "viewer" | null | yes |
Errors
Codes in the catalogue that answer with one of this operation’s error statuses. Every one of them carries a fix.
- validation_error 400
- invalid_idempotency_key 400
- invalid_cursor 400
- domain_already_exists 409
- domain_verified_elsewhere 409
- domain_not_verified 403
- onboarding_recipient_not_a_member 403
- onboarding_daily_cap_reached 429
- onboarding_sender_unavailable 403
- return_path_subdomain_in_use 409
- account_suspended 403
- account_sandboxed 403
- trust_throttled 429
- missing_api_key 401
- session_required 401
- human_action_required 403
- csrf_origin_rejected 403
- mfa_required 401
- charge_not_this_account 403
- plan_not_purchasable 400
- overage_not_on_plan 409
- term_not_on_sale 409
- subscription_active 409
- billing_customer_missing 404
- stripe_signature_invalid 400
- invalid_api_key 403
- restricted_api_key 403
- insufficient_role 403
- invite_email_mismatch 403
- already_in_account 409
- domain_scope_violation 403
- not_found 404
- session_expired 404
- idempotency_in_flight 409
- idempotency_payload_mismatch 409
- rate_ceiling_exceeded 429
- daily_quota_exceeded 429
- monthly_quota_exceeded 429
- rate_limit_exceeded 429
- approval_required 403
- trust_paused 403
- kill_switch_active 403
- internal_server_error 500
- support_ticket_not_found 404
- support_closed 409
- support_reopen_expired 409
- support_merge_conflict 409
- support_upload_rejected 400
- support_rate_limited 429