Create Checkout Session
Create a new checkout session with line items.
Works for both User and API Key authentication. Account access is automatically validated via endpoint dependency.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Headers
Request
Customer identifier. The customer must belong to this account (404 otherwise). Attaching a customer exposes that customer’s saved payment methods and credit balance to whoever holds this checkout session’s token, so attach only a customer you have identified and authenticated yourself (for example a signed-in shopper), never one matched from details the shopper typed in.
A saved payment method to suggest first for a one-click checkout. This is a prefill hint, NOT a binding — the customer can pick a different card, and the confirm request is authoritative for what is charged. Requires payment mode and a customer_id, and the payment method must belong to that customer and this account.
Whether the saved-card one-click re-collects the card security code (CVC) at confirm for THIS session. Omitted defaults to false (pure one-click, no CVC). Set true for best approval rates, and required when the session routes to Adyen (Adyen 422 14_029 on a stored-card charge with no CVC).
Number of hours until the checkout session expires. When omitted, the account’s configured checkout session expiration (checkout_settings.session_expiration_minutes) is used.
Whether the invoice created from this session applies the customer’s credit balance. Set false to leave the credit untouched for a later purchase (for example when a promo code should not stack with a referral credit). The customer then pays the full amount after coupons. Only credit is skipped: a negative balance (an amount the customer owes) is handled exactly as on a default session. Applies to this session’s invoice only; subscription renewals, and the first paid invoice after a free trial, still apply the balance. Cannot be changed after the session is created: an update that sends it returns 422.
Free trial length in days for the subscription this session creates. Omit it to use the trial set on the recurring price (the shortest one when several prices carry a trial); a basket that also holds a one-time price takes no trial by default, because the trial would zero that line too. Send 0 to start the subscription without a trial even when the price has one. A value above 0 requires at least one recurring price and is rejected in ‘setup’ mode. During the trial the first invoice is $0: the card is saved and charged when the trial ends.
Settings for card checkout behavior (parallel setup, 3DS mode). Defaults apply if not provided.
ID of a processor route to use for card checkout (overrides account default). A processor route contains an ordered list of processors tried sequentially as a fallback chain. Pass a single route ID — to use multiple processors, define them within the route itself.
Define processors directly on this session instead of referencing a predefined route. The processors are tried in order as a fallback chain. Mutually exclusive with processor_route_id — set one or the other, not both. Use this for one-off routing configurations; use processor_route_id for reusable routes shared across sessions.
Custom field values to set on this checkout session. Keys must match defined field keys for the checkout_session entity type. Set a key to null to delete that field’s value.
List of fallback tiers for cascade pricing (max 10 tiers). Each tier contains line items and optional processor route.
Preferences for payment method setup. Valid in both ‘payment’ and ‘setup’ modes. Contains per-processor setup configuration under ‘processors’ key.
Statement descriptor suffix for this checkout session. Overrides the default descriptor for the charge made from this session, and is copied onto any subscription created from it so renewals inherit it. A suffix longer than the account prefix allows is trimmed to fit (the trimmed value is what this endpoint returns); an invalid suffix is rejected with 422.
FULL statement descriptor override map, keyed by processor id (proc_…). When a charge runs on a keyed processor, its value is sent as the whole descriptor and takes precedence over the processor’s own statement descriptor and statement descriptor prefix. Two shapes are accepted. Flat: {“proc_…”: “DESCRIPTOR”} applies to every charge. By charge type: {“one_time”: {“proc_…”: ”…”}, “trial_conversion”: {…}, “recurring”: {…}} picks the descriptor by the kind of charge: one_time is a checkout charge that starts no subscription; trial_conversion is the first paid renewal of a subscription that had a trial, including its retries; recurring is every other subscription charge, including the first charge of a subscription with no trial. When the charge’s type has no entry for the processor, a trial_conversion charge uses the recurring entry, then the processor’s own statement descriptor; a one_time charge uses the processor’s own statement descriptor, else the prefix (the processor’s statement descriptor prefix, else the account prefix) plus the checkout’s suffix, and never the recurring entry. The two shapes cannot be mixed, and only one_time, trial_conversion and recurring are valid charge types (422 otherwise). Supported processors: Adyen, Checkout.com, Authorize.net, Airwallex and NMI. Stripe, PayPal, Braintree and other processors are not allowed as keys (422). Caveats: Authorize.net applies it only on TSYS/EVO-backed accounts; Airwallex applies it only after dynamic descriptors are enabled on the Airwallex account; NMI applies it only when custom descriptors are allowed on the processor. Example: {“proc_…”: “ACME EVENT 4412”}. The map is copied onto any subscription created from this session. Keys must resolve to supported processors in the account (422 otherwise).
Response
Card tokenization mode: ‘direct’ (KMS encryption) or ‘vgs’ (VGS Collect + proxy)
Whether invoices created from this session apply the customer’s credit balance. False leaves the credit untouched for a later purchase; a negative balance (an amount the customer owes) is handled as on a default session.
Free trial length in days applied to the subscription this session creates: the value sent on create, else the trial of the recurring prices when every line is recurring. Null when there is no trial.
Settings for card checkout behavior (parallel setup, 3DS mode)
Cascade pricing status (None if no cascade configured)
Full cascade tier details including processor routes (None if no cascade configured)
ID of the processor route used for card checkout. A processor route contains an ordered list of processors tried sequentially as a fallback chain. This is a single route ID, not an array — to use multiple processors, define them within the route itself.
Inline route defined directly on this session. Null if a predefined processor_route_id is used instead, or if no route is configured.
Custom field values. Only included when expand=custom_fields is specified.
FULL statement descriptor override map, keyed by processor id (proc_…). When a charge runs on a keyed processor, its value is sent as the whole descriptor and takes precedence over the processor’s own statement descriptor and statement descriptor prefix. Two shapes are accepted. Flat: {“proc_…”: “DESCRIPTOR”} applies to every charge. By charge type: {“one_time”: {“proc_…”: ”…”}, “trial_conversion”: {…}, “recurring”: {…}} picks the descriptor by the kind of charge: one_time is a checkout charge that starts no subscription; trial_conversion is the first paid renewal of a subscription that had a trial, including its retries; recurring is every other subscription charge, including the first charge of a subscription with no trial. When the charge’s type has no entry for the processor, a trial_conversion charge uses the recurring entry, then the processor’s own statement descriptor; a one_time charge uses the processor’s own statement descriptor, else the prefix (the processor’s statement descriptor prefix, else the account prefix) plus the checkout’s suffix, and never the recurring entry. The two shapes cannot be mixed, and only one_time, trial_conversion and recurring are valid charge types (422 otherwise). Supported processors: Adyen, Checkout.com, Authorize.net, Airwallex and NMI. Stripe, PayPal, Braintree and other processors are not allowed as keys (422). Caveats: Authorize.net applies it only on TSYS/EVO-backed accounts; Airwallex applies it only after dynamic descriptors are enabled on the Airwallex account; NMI applies it only when custom descriptors are allowed on the processor. Copied onto any subscription created from this session. Null when not set.