Stripe: Create a Customer Session

← Customer sessions operations · Get started

Operation stripe.postcustomersessions

Provider route: POST /v1/customer_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["customerSessions"]["postCustomerSessions"]>[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.customerSessions.postCustomerSessions(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.customer_sessions.post_customer_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	Required within parent	Additional keys: not allowed
body.components	object	Required within parent	Configuration for each component. At least 1 component must be enabled.
body.components.active_entitlements	object	Optional
body.components.active_entitlements.enabled	boolean	Required within parent
body.components.buy_button	object	Optional
body.components.buy_button.enabled	boolean	Required within parent
body.components.customer_portal	object	Optional
body.components.customer_portal.enabled	boolean	Required within parent
body.components.customer_sheet	object	Optional
body.components.customer_sheet.enabled	boolean	Required within parent
body.components.customer_sheet.features	object	Optional
body.components.customer_sheet.features.payment_method_allow_redisplay_filters	array	Optional
body.components.customer_sheet.features.payment_method_allow_redisplay_filters[]	string	Each item	One of: always, limited, unspecified
body.components.customer_sheet.features.payment_method_remove	string	Optional	One of: disabled, enabled
body.components.mobile_payment_element	object	Optional
body.components.mobile_payment_element.enabled	boolean	Required within parent
body.components.mobile_payment_element.features	object	Optional
body.components.mobile_payment_element.features.payment_method_allow_redisplay_filters	array	Optional
body.components.mobile_payment_element.features.payment_method_allow_redisplay_filters[]	string	Each item	One of: always, limited, unspecified
body.components.mobile_payment_element.features.payment_method_redisplay	string	Optional	One of: disabled, enabled
body.components.mobile_payment_element.features.payment_method_remove	string	Optional	One of: disabled, enabled
body.components.mobile_payment_element.features.payment_method_save	string	Optional	One of: disabled, enabled
body.components.mobile_payment_element.features.payment_method_save_allow_redisplay_override	string	Optional	One of: always, limited, unspecified
body.components.payment_element	object	Optional
body.components.payment_element.enabled	boolean	Required within parent
body.components.payment_element.features	object	Optional
body.components.payment_element.features.payment_method_allow_redisplay_filters	array	Optional
body.components.payment_element.features.payment_method_allow_redisplay_filters[]	string	Each item	One of: always, limited, unspecified
body.components.payment_element.features.payment_method_redisplay	string	Optional	One of: disabled, enabled
body.components.payment_element.features.payment_method_redisplay_limit	integer	Optional
body.components.payment_element.features.payment_method_remove	string	Optional	One of: disabled, enabled
body.components.payment_element.features.payment_method_save	string	Optional	One of: disabled, enabled
body.components.payment_element.features.payment_method_save_usage	string	Optional	One of: off_session, on_session
body.components.pricing_table	object	Optional
body.components.pricing_table.enabled	boolean	Required within parent
body.customer	string	Optional	The ID of an existing customer for which to create the Customer Session. Maximum length: 5000
body.customer_account	string	Optional	The ID of an existing Account for which to create the Customer Session. Maximum length: 5000
body.expand	array	Optional	Specifies which fields in the response should be expanded.
body.expand[]	string	Each item	Maximum length: 5000

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 Customer Session — response body

Referenced models: Create a Customer Session — response body

Schemas

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

Create a Customer Session — response body

Field	Type	Presence	Description and constraints
$	object	Root	A Customer Session allows you to grant Stripe's frontend SDKs (like Stripe.js) client-side access control over a Customer. Related guides: [Customer Session with the Payment Element](/payments/accept-a-payment-deferred?platform=web&type=payment#save-payment-methods), [Customer Session with the Pricing Table](/payments/checkout/pricing-table#customer-session), [Customer Session with the Buy Button](/payment-links/buy-button#pass-an-existing-customer).
client_secret	string	Required within parent	The client secret of this Customer Session. Used on the client to set up secure access to the given `customer`. The client secret can be used to provide access to `customer` from your frontend. It should not be stored, logged, or exposed to anyone other than the relevant customer. Make sure that you have TLS enabled on any page that includes the client secret. Maximum length: 5000
components	Model	Optional	Expand Create a Customer Session — response body — components
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	JSON	Required within parent	The Customer the Customer Session was created for.
customer (anyOf 1)	string	Alternative	Maximum length: 5000
customer (anyOf 2)	Model	Alternative	Expand Create a customer — response body
customer_account	JSON	Optional
customer_account (anyOf 1)	string	Alternative	The Account that the Customer Session was created for. Maximum length: 5000
customer_account (anyOf 2)	null	Alternative
expires_at	JSON	Required within parent
expires_at (anyOf 1)	integer	Alternative	The timestamp at which this Customer Session will expire. Format: unix-time
expires_at (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
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`.
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: customer_session

Referenced models: Create a customer — response body, Create a Customer Session — response body — components

Create a Customer Session — response body — components

Field	Type	Presence	Description and constraints
$	object	Root	Configuration for the components supported by this Customer Session.
active_entitlements	Model	Required within parent	Expand Create a Customer Session — response body — components active entitlements
buy_button	Model	Required within parent	Expand Create a Customer Session — response body — components buy button
customer_portal	Model	Required within parent	Expand Create a Customer Session — response body — components customer portal
customer_sheet	Model	Required within parent	Expand Create a Customer Session — response body — components customer sheet
mobile_payment_element	Model	Required within parent	Expand Create a Customer Session — response body — components mobile payment element
payment_element	Model	Required within parent	Expand Create a Customer Session — response body — components payment element
pricing_table	Model	Required within parent	Expand Create a Customer Session — response body — components pricing table

Referenced models: Create a Customer Session — response body — components active entitlements, Create a Customer Session — response body — components buy button, Create a Customer Session — response body — components customer portal, Create a Customer Session — response body — components customer sheet, Create a Customer Session — response body — components mobile payment element, Create a Customer Session — response body — components payment element, Create a Customer Session — response body — components pricing table

Create a Location — response body — address

Field	Type	Presence	Description and constraints
$	object	Root
city	JSON	Optional
city (anyOf 1)	string	Alternative	City, district, suburb, town, or village. Maximum length: 5000
city (anyOf 2)	null	Alternative
country	JSON	Optional
country (anyOf 1)	string	Alternative	Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). Maximum length: 5000
country (anyOf 2)	null	Alternative
line1	JSON	Optional
line1 (anyOf 1)	string	Alternative	Address line 1, such as the street, PO Box, or company name. Maximum length: 5000
line1 (anyOf 2)	null	Alternative
line2	JSON	Optional
line2 (anyOf 1)	string	Alternative	Address line 2, such as the apartment, suite, unit, or building. Maximum length: 5000
line2 (anyOf 2)	null	Alternative
postal_code	JSON	Optional
postal_code (anyOf 1)	string	Alternative	ZIP or postal code. Maximum length: 5000
postal_code (anyOf 2)	null	Alternative
state	JSON	Optional
state (anyOf 1)	string	Alternative	State, county, province, or region ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)). Maximum length: 5000
state (anyOf 2)	null	Alternative

Retrieve a cash balance — response body

Field	Type	Presence	Description and constraints
$	object	Root	A customer's `Cash balance` represents real funds. Customers can add funds to their cash balance by sending a bank transfer. These funds can be used for payment and can eventually be paid out to your bank account.
available	JSON	Optional
available (anyOf 1)	object	Alternative	A hash of all cash balances available to this customer. You cannot delete a customer with any cash balances, even if the balance is 0. Amounts are represented in the [smallest currency unit](https://docs.stripe.com/currencies#zero-decimal). Additional keys: see wildcard field
available (anyOf 1).*	JSON	Additional keys
available (anyOf 1).* (anyOf 1)	integer	Alternative
available (anyOf 1).* (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
available (anyOf 2)	null	Alternative
customer	string	Required within parent	The ID of the customer whose cash balance this object represents. Maximum length: 5000
customer_account	JSON	Optional
customer_account (anyOf 1)	string	Alternative	The ID of an Account representing a customer whose cash balance this object represents. Maximum length: 5000
customer_account (anyOf 2)	null	Alternative
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`.
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: cash_balance
settings	Model	Required within parent	Expand Retrieve a cash balance — response body — settings

Referenced models: Retrieve a cash balance — response body — settings

Create a customer — response body — tax

Field	Type	Presence	Description and constraints
$	object	Root
automatic_tax	string	Required within parent	Surfaces if automatic tax computation is possible given the current customer location information. Known values: failed, not_collecting, supported, unrecognized_location
ip_address	JSON	Optional
ip_address (anyOf 1)	string	Alternative	A recent IP address of the customer used for tax reporting and tax location inference. Maximum length: 5000
ip_address (anyOf 2)	null	Alternative
location	JSON	Optional
location (anyOf 1)	JSON	Alternative	The identified tax location of the customer.
location (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create a customer — response body — tax / location / The identified tax location of the customer / source: billing address, ip address, payment method, shipping destination
location (anyOf 2)	null	Alternative
provider	string	Required within parent	The tax calculation provider used for location resolution. Defaults to `stripe` when not using a [third-party provider](/tax/third-party-apps). Known values: anrok, avalara, sphere, stripe

Referenced models: Create a customer — response body — tax / location / The identified tax location of the customer / source: billing address, ip address, payment method, shipping destination

Policy, approvals and errors

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