Create a Portal Session
POST/portal/sessions
Validates the application return_url before invoking the selected payment provider. A provider may require an existing Customer already owned by the Billing Account and may manage the final return behavior itself. Unsupported Portal capability fails with BILLING.PAYMENT_PROVIDER_CAPABILITY_UNSUPPORTED before Customer creation, provider I/O, or local state mutation. A provider that requires an existing owned Customer returns BILLING.PAYMENT_PROVIDER_CUSTOMER_REQUIRED when that binding has not been learned. Before provider I/O, the service verifies that every locally active owned Subscription belongs to the selected Customer; a missing or different Subscription Customer fails closed with BILLING.PAYMENT_PROVIDER_CUSTOMER_CONFLICT rather than opening an incomplete Portal. Customer ownership is never inferred from email. Returned URLs are short-lived and must not be cached.
Request
Responses
- 201
- 400
- 401
- 403
- 404
- 409
- 429
- 500
Created
Response Headers
Portal URL for redirection
Bad Request
Unauthorized
Forbidden (realm/account mismatch, billing account not derived from your session/principal, or insufficient role)
Not Found
Conflict (idempotency body mismatch, duplicate adjustment, or an unsupported provider capability). Unsupported mutations return BILLING.PAYMENT_PROVIDER_CAPABILITY_UNSUPPORTED before Customer creation, provider I/O, or local state mutation. Concurrent use of the same Idempotency-Key returns WRITE.IDEMPOTENCY_IN_PROGRESS; different keys are independent requests whose final ordering is owned by the PSP. A subscription Checkout with mixed group, currency, or recurrence facts is rejected before Customer lookup or provider I/O. Missing or inconsistent selected Customer bindings return BILLING.PAYMENT_PROVIDER_CUSTOMER_REQUIRED or BILLING.PAYMENT_PROVIDER_CUSTOMER_CONFLICT without silently replacing the binding.
Rate limited
Response Headers
Seconds to wait before retry.
Internal Server Error