Stripe: Create a portal configuration

Stripe billingPortal.postBillingPortalConfigurations: arguments, response, policy and SDK examples.

← Billing portal operations · Get started

Operation stripe.postbillingportalconfigurations

Provider route: POST /v1/billing_portal/configurations. 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"]["postBillingPortalConfigurations"]>[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.postBillingPortalConfigurations(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_configurations(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	Required within parent	Additional keys: not allowed
`body.business_profile`	object	Optional	The business information shown to customers in the portal.
`body.business_profile.headline`	JSON	Optional
`body.business_profile.headline (anyOf 1)`	string	Alternative	Maximum length: 60
`body.business_profile.headline (anyOf 2)`	string	Alternative	One of:
`body.business_profile.privacy_policy_url`	string	Optional
`body.business_profile.terms_of_service_url`	string	Optional
`body.default_return_url`	JSON	Optional	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.
`body.default_return_url (anyOf 1)`	string	Alternative
`body.default_return_url (anyOf 2)`	string	Alternative	One of:
`body.expand`	array	Optional	Specifies which fields in the response should be expanded.
`body.expand[]`	string	Each item	Maximum length: 5000
`body.features`	object	Required within parent	Information about the features available in the portal.
`body.features.customer_update`	object	Optional
`body.features.customer_update.allowed_updates`	JSON	Optional
`body.features.customer_update.allowed_updates (anyOf 1)`	array	Alternative
`body.features.customer_update.allowed_updates (anyOf 1)[]`	string	Each item	One of: address, email, name, phone, shipping, tax_id
`body.features.customer_update.allowed_updates (anyOf 2)`	string	Alternative	One of:
`body.features.customer_update.enabled`	boolean	Required within parent
`body.features.invoice_history`	object	Optional
`body.features.invoice_history.enabled`	boolean	Required within parent
`body.features.payment_method_update`	object	Optional
`body.features.payment_method_update.enabled`	boolean	Required within parent
`body.features.payment_method_update.payment_method_configuration`	JSON	Optional
`body.features.payment_method_update.payment_method_configuration (anyOf 1)`	string	Alternative	Maximum length: 5000
`body.features.payment_method_update.payment_method_configuration (anyOf 2)`	string	Alternative	One of:
`body.features.subscription_cancel`	object	Optional
`body.features.subscription_cancel.cancellation_reason`	object	Optional
`body.features.subscription_cancel.cancellation_reason.enabled`	boolean	Required within parent
`body.features.subscription_cancel.cancellation_reason.feedback_options`	JSON	Optional
`body.features.subscription_cancel.cancellation_reason.feedback_options (anyOf 1)`	array	Alternative
`body.features.subscription_cancel.cancellation_reason.feedback_options (anyOf 1)[]`	string	Each item	Maximum length: 5000
`body.features.subscription_cancel.cancellation_reason.feedback_options (anyOf 2)`	string	Alternative	One of:
`body.features.subscription_cancel.cancellation_reason.options`	JSON	Required within parent
`body.features.subscription_cancel.cancellation_reason.options (anyOf 1)`	array	Alternative
`body.features.subscription_cancel.cancellation_reason.options (anyOf 1)[]`	string	Each item	One of: customer_service, low_quality, missing_features, other, switched_service, too_complex, too_expensive, unused
`body.features.subscription_cancel.cancellation_reason.options (anyOf 2)`	string	Alternative	One of:
`body.features.subscription_cancel.enabled`	boolean	Required within parent
`body.features.subscription_cancel.mode`	string	Optional	One of: at_period_end, immediately
`body.features.subscription_cancel.proration_behavior`	string	Optional	One of: always_invoice, create_prorations, none
`body.features.subscription_update`	object	Optional
`body.features.subscription_update.billing_cycle_anchor`	string	Optional	One of: now, unchanged
`body.features.subscription_update.default_allowed_updates`	JSON	Optional
`body.features.subscription_update.default_allowed_updates (anyOf 1)`	array	Alternative
`body.features.subscription_update.default_allowed_updates (anyOf 1)[]`	string	Each item	One of: price, promotion_code, quantity
`body.features.subscription_update.default_allowed_updates (anyOf 2)`	string	Alternative	One of:
`body.features.subscription_update.enabled`	boolean	Required within parent
`body.features.subscription_update.products`	JSON	Optional
`body.features.subscription_update.products (anyOf 1)`	array	Alternative
`body.features.subscription_update.products (anyOf 1)[]`	object	Each item
`body.features.subscription_update.products (anyOf 1)[].adjustable_quantity`	object	Optional
`body.features.subscription_update.products (anyOf 1)[].adjustable_quantity.enabled`	boolean	Required within parent
`body.features.subscription_update.products (anyOf 1)[].adjustable_quantity.maximum`	integer	Optional
`body.features.subscription_update.products (anyOf 1)[].adjustable_quantity.minimum`	integer	Optional
`body.features.subscription_update.products (anyOf 1)[].prices`	array	Required within parent
`body.features.subscription_update.products (anyOf 1)[].prices[]`	string	Each item	Maximum length: 5000
`body.features.subscription_update.products (anyOf 1)[].product`	string	Required within parent	Maximum length: 5000
`body.features.subscription_update.products (anyOf 2)`	string	Alternative	One of:
`body.features.subscription_update.proration_behavior`	string	Optional	One of: always_invoice, create_prorations, none
`body.features.subscription_update.schedule_at_period_end`	object	Optional
`body.features.subscription_update.schedule_at_period_end.conditions`	array	Optional
`body.features.subscription_update.schedule_at_period_end.conditions[]`	object	Each item
`body.features.subscription_update.schedule_at_period_end.conditions[].type`	string	Required within parent	One of: decreasing_item_amount, shortening_interval
`body.features.subscription_update.trial_update_behavior`	string	Optional	One of: continue_trial, end_trial
`body.login_page`	object	Optional	The hosted login page for this configuration. Learn more about the portal login page in our [integration docs](https://stripe.com/docs/billing/subscriptions/integrating-customer-portal#share).
`body.login_page.enabled`	boolean	Required within parent
`body.metadata`	object	Optional	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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. Additional keys: see wildcard field
`body.metadata.*`	string	Additional keys
`body.name`	JSON	Optional	The name of the configuration.
`body.name (anyOf 1)`	string	Alternative	Maximum length: 256
`body.name (anyOf 2)`	string	Alternative	One of:

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 configuration — response body

Referenced models: Create a portal configuration — response body

Schemas

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

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

Create a portal configuration — response body — business profile

Field	Type	Presence	Description and constraints
`$`	object	Root
`headline`	JSON	Optional
`headline (anyOf 1)`	string	Alternative	The messaging shown to customers in the portal. Maximum length: 5000
`headline (anyOf 2)`	null	Alternative
`privacy_policy_url`	JSON	Optional
`privacy_policy_url (anyOf 1)`	string	Alternative	A link to the business’s publicly available privacy policy. Maximum length: 5000
`privacy_policy_url (anyOf 2)`	null	Alternative
`terms_of_service_url`	JSON	Optional
`terms_of_service_url (anyOf 1)`	string	Alternative	A link to the business’s publicly available terms of service. Maximum length: 5000
`terms_of_service_url (anyOf 2)`	null	Alternative

Create a portal configuration — response body — features

Field	Type	Presence	Description and constraints
`$`	object	Root
`customer_update`	Model	Required within parent	Expand Create a portal configuration — response body — features customer update
`invoice_history`	Model	Required within parent	Expand Create a portal configuration — response body — features invoice history
`payment_method_update`	Model	Required within parent	Expand Create a portal configuration — response body — features payment method update
`subscription_cancel`	Model	Required within parent	Expand Create a portal configuration — response body — features subscription cancel
`subscription_update`	Model	Required within parent	Expand Create a portal configuration — response body — features subscription update

Referenced models: Create a portal configuration — response body — features customer update, Create a portal configuration — response body — features invoice history, Create a portal configuration — response body — features payment method update, Create a portal configuration — response body — features subscription cancel, Create a portal configuration — response body — features subscription update

Create a portal configuration — response body — login page

Field	Type	Presence	Description and constraints
`$`	object	Root
`enabled`	boolean	Required within parent	If `true`, a shareable `url` will be generated that will take your customers to a hosted login page for the customer portal. If `false`, the previously generated `url`, if any, will be deactivated.
`url`	JSON	Optional
`url (anyOf 1)`	string	Alternative	A shareable URL to the hosted portal login page. Your customers will be able to log in with their [email](https://docs.stripe.com/api/customers/object#customer_object-email) and receive a link to their customer portal. Maximum length: 5000
`url (anyOf 2)`	null	Alternative

Create a portal configuration — response body — features customer update

Field	Type	Presence	Description and constraints
`$`	object	Root
`allowed_updates`	array	Required within parent	The types of customer updates that are supported. When empty, customers are not updateable.
`allowed_updates[]`	string	Each item	Known values: address, email, name, phone, shipping, tax_id
`enabled`	boolean	Required within parent	Whether the feature is enabled.

Policy, approvals and errors

SDK function policy ID: stripe.postbillingportalconfigurations. Catalog operation: PostBillingPortalConfigurations. 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

Report an issue with this page