Sample - Stripe API
POST/v1/billing_portal/sessions

Create a portal session

Creates a customer portal session for an existing customer or account. Supply customer or customer_account, optionally select a configuration, and use flow_data to direct the customer through a specific portal flow; the response includes a short-lived portal URL.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

8 body fields

Optional customer portal session settings.

configurationstringoptional
The ID of an existing [configuration](https://docs.stripe.com/api/customer_portal/configurations) to use for this session, describing its functionality and features. If not specified, the session uses the default configuration.
customerstringoptional
The ID of an existing customer.
customer_accountstringoptional
The ID of an existing account.
expandarray<string>optional
Specifies which fields in the response should be expanded.
flow_dataobjectoptional
Information about a specific flow for the customer to go through. See the [docs](https://docs.stripe.com/customer-management/portal-deep-links) to learn more about using customer portal deep links and flows.
localestringoptional
The IETF language tag of the locale customer portal is displayed in. If blank or auto, the customer’s `preferred_locales` or browser’s locale is used.
Allowed:autobgcsdadeelenen-AUen-CAen-GBen-IEen-IN
on_behalf_ofstringoptional
The `on_behalf_of` account to use for this session. When specified, only subscriptions and invoices with this `on_behalf_of` account appear in the portal. For more information, see the [docs](https://docs.stripe.com/connect/separate-charges-and-transfers#settlement-merchant). Use the [Accounts API](https://docs.stripe.com/api/accounts/object#account_object-settings-branding) to modify the `on_behalf_of` account's branding settings, which the portal displays.
return_urlstringoptional
The default URL to redirect customers to when they click on the portal's link to return to your website.

2 status codes
200Returns the created customer portal session, including its identifier, configuration, customer or account, creation time, and short-lived access URL.
configurationstringrequired
The configuration used by this session, describing the features available.
createdintegerrequired
Time at which the object was created. Measured in seconds since the Unix epoch.
customerstringrequired
The ID of the customer for this session.
customer_accountstringoptional
The ID of the account for this session.
flowobjectoptional
Information about a specific flow for the customer to go through. See the [docs](https://docs.stripe.com/customer-management/portal-deep-links) to learn more about using customer portal deep links and flows.
idstringrequired
Unique identifier for the object.
livemodebooleanrequired
If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
localestringoptional
The IETF language tag of the locale Customer Portal is displayed in. If blank or auto, the customer’s `preferred_locales` or browser’s locale is used.
Allowed:autobgcsdadeelenen-AUen-CAen-GBen-IEen-IN
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:billing_portal.session
on_behalf_ofstringoptional
The account for which the session was created on behalf of. When specified, only subscriptions and invoices with this `on_behalf_of` account appear in the portal. For more information, see the [docs](https://docs.stripe.com/connect/separate-charges-and-transfers#settlement-merchant). Use the [Accounts API](https://docs.stripe.com/api/accounts/object#account_object-settings-branding) to modify the `on_behalf_of` account's branding settings, which the portal displays.
return_urlstringoptional
The URL to redirect customers to when they click on the portal's link to return to your website.
urlstringrequired
The short-lived URL of the session that gives customers access to the customer portal.
defaultReturns an error object containing details about the failed request.
errorobjectrequired

Error handling

customer and customer_account must identify existing resources when supplied. flow_data.type must be one of customer_update, payment_method_update, subscription_cancel, subscription_update, or subscription_update_confirm, and locale must use one of the supported IETF language tags.