Open the Stripe billing portal
Returns a short-lived URL you can redirect the browser to for managing payment methods, downloading invoices, and editing billing details on Stripe's hosted portal. Plan subscribe, upgrade, and cancel flows are not exposed in the portal; those stay in the API and dashboard.
return_url is required and must use HTTPS in production. It must match
the scheme and host of an entry on the configured return-URL allow-list
(paths and queries are not part of the match, so deep links within a
permitted origin work). A value that is not allow-listed returns
422 VALIDATION_FAILED with details.return_url.
The response carries portal_url (the short-lived hosted URL) and
expires_at (a conservative client-side hint; re-request rather than
reusing a stale URL). When your organization has never subscribed or
topped up, the call returns 409 NO_STRIPE_CUSTOMER with a hint to
subscribe first. If the portal is temporarily unavailable, the call
returns 502 BILLING_PORTAL_UNAVAILABLE.
Requires the billing:write scope.
Authenticate by sending your API key as a bearer token:
Authorization: Bearer am_live_.... Every request is automatically
scoped to the organization that owns the key and to the scopes granted
to that key.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/billing/portal" \ -H "Content-Type: application/json" \ -d '{ "return_url": "https://app.example.com/settings/billing" }'{
"success": true,
"data": {
"portal_url": "https://billing.stripe.com/p/session/bps_test_a1b2c3d4",
"expires_at": "2026-05-22T12:30:00Z"
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "missing required scope",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "NO_STRIPE_CUSTOMER",
"message": "organization has no stripe customer; subscribe first",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "VALIDATION_FAILED",
"message": "validation failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM",
"details": {
"to": "must be E.164",
"body": "must be 1..1600 chars"
}
}
}{
"success": false,
"error": {
"code": "BILLING_PORTAL_UNAVAILABLE",
"message": "billing portal session could not be created",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}