Stripe: Create a portal session

← Billing portal operations · Get started

Operation stripe.postbillingportalsessions

Provider route: POST /v1/billing_portal/sessions. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { StripeIntegration } from "@alter-ai/stripe";

async function execute(input: Parameters<StripeIntegration["billingPortal"]["postBillingPortalSessions"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.billingPortal.postBillingPortalSessions(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_stripe import StripeIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.billing_portal.post_billing_portal_sessions(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
headers	object	Optional	Additional keys: not allowed
headers.Idempotency-Key	string	Optional	Minimum length: 1 Maximum length: 255
body	object	Optional	Additional keys: not allowed
body.configuration	string	Optional	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. Maximum length: 5000
body.customer	string	Optional	The ID of an existing customer. Maximum length: 5000
body.customer_account	string	Optional	The ID of an existing account. Maximum length: 5000
body.expand	array	Optional	Specifies which fields in the response should be expanded.
body.expand[]	string	Each item	Maximum length: 5000
body.flow_data	object	Optional	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.
body.flow_data.after_completion	object	Optional
body.flow_data.after_completion.hosted_confirmation	object	Optional
body.flow_data.after_completion.hosted_confirmation.custom_message	string	Optional	Maximum length: 500
body.flow_data.after_completion.redirect	object	Optional
body.flow_data.after_completion.redirect.return_url	string	Required within parent
body.flow_data.after_completion.type	string	Required within parent	One of: hosted_confirmation, portal_homepage, redirect
body.flow_data.subscription_cancel	object	Optional
body.flow_data.subscription_cancel.retention	object	Optional
body.flow_data.subscription_cancel.retention.coupon_offer	object	Required within parent
body.flow_data.subscription_cancel.retention.coupon_offer.coupon	string	Required within parent	Maximum length: 5000
body.flow_data.subscription_cancel.retention.type	string	Required within parent	One of: coupon_offer
body.flow_data.subscription_cancel.subscription	string	Required within parent	Maximum length: 5000
body.flow_data.subscription_update	object	Optional
body.flow_data.subscription_update.subscription	string	Required within parent	Maximum length: 5000
body.flow_data.subscription_update_confirm	object	Optional
body.flow_data.subscription_update_confirm.discounts	array	Optional
body.flow_data.subscription_update_confirm.discounts[]	object	Each item
body.flow_data.subscription_update_confirm.discounts[].coupon	string	Optional	Maximum length: 5000
body.flow_data.subscription_update_confirm.discounts[].promotion_code	string	Optional	Maximum length: 5000
body.flow_data.subscription_update_confirm.items	array	Required within parent
body.flow_data.subscription_update_confirm.items[]	object	Each item
body.flow_data.subscription_update_confirm.items[].id	string	Required within parent	Maximum length: 5000
body.flow_data.subscription_update_confirm.items[].price	string	Optional	Maximum length: 5000
body.flow_data.subscription_update_confirm.items[].quantity	integer	Optional
body.flow_data.subscription_update_confirm.subscription	string	Required within parent	Maximum length: 5000
body.flow_data.type	string	Required within parent	One of: customer_update, payment_method_update, subscription_cancel, subscription_update, subscription_update_confirm
body.locale	string	Optional	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. One of: auto, bg, cs, da, de, el, en, en-AU, en-CA, en-GB, en-IE, en-IN, en-NZ, en-SG, es, es-419, et, fi, fil, fr, fr-CA, hr, hu, id, it, ja, ko, lt, lv, ms, mt, nb, nl, pl, pt, pt-BR, ro, ru, sk, sl, sv, th, tr, vi, zh, zh-HK, zh-TW
body.on_behalf_of	string	Optional	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.
body.return_url	string	Optional	The default URL to redirect customers to when they click on the portal’s link to return to your website.

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Create a portal session — response body

Referenced models: Create a portal session — response body

Schemas

27 more schemas are linked from the tables above, on the schema pages.

Create a portal session — response body

Field	Type	Presence	Description and constraints
$	object	Root	The Billing customer portal is a Stripe-hosted UI for subscription and billing management. A portal configuration describes the functionality and features that you want to provide to your customers through the portal. A portal session describes the instantiation of the customer portal for a particular customer. By visiting the session's URL, the customer can manage their subscriptions and billing details. For security reasons, sessions are short-lived and will expire if the customer does not visit the URL. Create sessions on-demand when customers intend to manage their subscriptions and billing details. Related guide: [Customer management](/customer-management)
configuration	JSON	Required within parent	The configuration used by this session, describing the features available.
configuration (anyOf 1)	string	Alternative	Maximum length: 5000
configuration (anyOf 2)	Model	Alternative	Expand Create a portal configuration — response body
created	JSON	Required within parent
created (anyOf 1)	integer	Alternative	Time at which the object was created. Measured in seconds since the Unix epoch. Format: unix-time
created (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
customer	string	Required within parent	The ID of the customer for this session. Maximum length: 5000
customer_account	JSON	Optional
customer_account (anyOf 1)	string	Alternative	The ID of the account for this session. Maximum length: 5000
customer_account (anyOf 2)	null	Alternative
flow	JSON	Optional
flow (anyOf 1)	JSON	Alternative	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.
flow (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create a portal session — response body — flow value after completion, customer update, subscription cancel, subscription update, subscription update confirm, type
flow (anyOf 2)	null	Alternative
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
livemode	boolean	Required within parent	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
locale	JSON	Optional
locale (anyOf 1)	string	Alternative	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. Known values: auto, bg, cs, da, de, el, en, en-AU, en-CA, en-GB, en-IE, en-IN, en-NZ, en-SG, es, es-419, et, fi, fil, fr, fr-CA, hr, hu, id, it, ja, ko, lt, lv, ms, mt, nb, nl, pl, pt, pt-BR, ro, ru, sk, sl, sv, th, tr, vi, zh, zh-HK, zh-TW
locale (anyOf 2)	null	Alternative
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: billing_portal.session
on_behalf_of	JSON	Optional
on_behalf_of (anyOf 1)	string	Alternative	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. Maximum length: 5000
on_behalf_of (anyOf 2)	null	Alternative
return_url	JSON	Optional
return_url (anyOf 1)	string	Alternative	The URL to redirect customers to when they click on the portal's link to return to your website. Maximum length: 5000
return_url (anyOf 2)	null	Alternative
url	string	Required within parent	The short-lived URL of the session that gives customers access to the customer portal. Maximum length: 5000

Referenced models: Create a portal configuration — response body, Create a portal session — response body — flow value after completion, customer update, subscription cancel, subscription update, subscription update confirm, type

Create a portal configuration — response body

Field	Type	Presence	Description and constraints
$	object	Root	A portal configuration describes the functionality and behavior you embed in a portal session. Related guide: [Configure the customer portal](/customer-management/configure-portal).
active	boolean	Required within parent	Whether the configuration is active and can be used to create portal sessions.
application	JSON	Optional
application (anyOf 1)	JSON	Alternative	ID of the Connect Application that created the configuration.
application (anyOf 1) (anyOf 1)	string	Alternative	Maximum length: 5000
application (anyOf 1) (anyOf 2)	Model	Alternative	Expand PostApplicationFeesIdRefund — response body — application / object: application
application (anyOf 1) (anyOf 3)	Model	Alternative	Expand Accept a quote — response body — application / value / deleted: True, object: application
application (anyOf 2)	null	Alternative
business_profile	Model	Required within parent	Expand Create a portal configuration — response body — business profile
created	JSON	Required within parent
created (anyOf 1)	integer	Alternative	Time at which the object was created. Measured in seconds since the Unix epoch. Format: unix-time
created (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
default_return_url	JSON	Optional
default_return_url (anyOf 1)	string	Alternative	The default URL to redirect customers to when they click on the portal's link to return to your website. This can be [overridden](https://docs.stripe.com/api/customer_portal/sessions/create#create_portal_session-return_url) when creating the session. Maximum length: 5000
default_return_url (anyOf 2)	null	Alternative
features	Model	Required within parent	Expand Create a portal configuration — response body — features
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
is_default	boolean	Required within parent	Whether the configuration is the default. If `true`, this configuration can be managed in the Dashboard and portal sessions will use this configuration unless it is overriden when creating the session.
livemode	boolean	Required within parent	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
login_page	Model	Required within parent	Expand Create a portal configuration — response body — login page
metadata	JSON	Optional
metadata (anyOf 1)	object	Alternative	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Additional keys: see wildcard field
metadata (anyOf 1).*	string	Additional keys	Maximum length: 500
metadata (anyOf 2)	null	Alternative
name	JSON	Optional
name (anyOf 1)	string	Alternative	The name of the configuration. Maximum length: 5000
name (anyOf 2)	null	Alternative
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: billing_portal.configuration
updated	JSON	Required within parent
updated (anyOf 1)	integer	Alternative	Time at which the object was last updated. Measured in seconds since the Unix epoch. Format: unix-time
updated (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Referenced models: PostApplicationFeesIdRefund — response body — application / object: application, Accept a quote — response body — application / value / deleted: True, object: application, Create a portal configuration — response body — business profile, Create a portal configuration — response body — features, Create a portal configuration — response body — login page

PostApplicationFeesIdRefund — response body — application / object: application

Field	Type	Presence	Description and constraints
$	object	Root
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
name	JSON	Optional
name (anyOf 1)	string	Alternative	The name of the application. Maximum length: 5000
name (anyOf 2)	null	Alternative
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: application

Accept a quote — response body — application / value / deleted: True, object: application

Field	Type	Presence	Description and constraints
$	object	Root
deleted	boolean	Required within parent	Always true for a deleted object Known values: True
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
name	JSON	Optional
name (anyOf 1)	string	Alternative	The name of the application. Maximum length: 5000
name (anyOf 2)	null	Alternative
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: application

Policy, approvals and errors

SDK function policy ID: stripe.postbillingportalsessions. Catalog operation: PostBillingPortalSessions. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Stripe-Version": "2026-09-30.endive"}

Official provider source