Create a Checkout Session

allow_promotion_codesboolean nullable

Enables user redeemable promotion codes.

amount_subtotalinteger nullable

Total of all items before discounts or taxes are applied.

amount_totalinteger nullable

Total of all items after discounts and taxes are applied.

billing_address_collection'auto' | 'required' nullable

Describes whether Checkout should collect the customer's billing address. Defaults to auto.

cancel_urlstring nullable

If set, Checkout displays a back button and customers will be directed to this URL if they decide to cancel payment and return to your website.

client_reference_idstring nullable

A unique string to reference the Checkout Session. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the Session with your internal systems.

client_secretstring nullable

The client secret of your Checkout Session. Applies to Checkout Sessions with ui_mode: embedded_page or ui_mode: elements. For ui_mode: embedded_page, the client secret is to be used when initializing Stripe.js embedded checkout. For ui_mode: elements, use the client secret with initCheckout on your front end.

createdinteger required

Time at which the object was created. Measured in seconds since the Unix epoch.

currencystring currency nullable

Three-letter ISO currency code, in lowercase. Must be a supported currency.

customer_accountstring nullable

The ID of the account for this Session.

customer_creation'always' | 'if_required' nullable

Configure whether a Checkout Session creates a Customer when the Checkout Session completes.

customer_emailstring nullable

If provided, this value will be used when the Customer object is created. If not provided, customers will be asked to enter their email address. Use this parameter to prefill customer data if you already have an email on file. To access information about the customer once the payment flow is complete, use the customer attribute.

excluded_payment_method_typesstring[]

A list of the types of payment methods (e.g., card) that should be excluded from this Checkout Session. This should only be used when payment methods for this Checkout Session are managed through the Stripe Dashboard.

expires_atinteger required

The timestamp at which the Checkout Session will expire.

idstring required

Unique identifier for the object.

integration_identifierstring nullable

The integration identifier for this Checkout Session. Multiple Checkout Sessions can have the same integration identifier.

livemodeboolean required

If the object exists in live mode, the value is true. If the object exists in test mode, the value is false.

locale'auto' | 'bg' | 'cs' | 'da' | 'de' | 'el' | 'en' | 'en-GB' | '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' nullable

The IETF language tag of the locale Checkout is displayed in. If blank or auto, the browser's locale is used.

metadataobject nullable

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

mode'payment' | 'setup' | 'subscription' required

The mode of the Checkout Session.

object'checkout.session' required

String representing the object's type. Objects of the same type share the same value.

origin_context'mobile_app' | 'web' nullable

Where the user is coming from. This informs the optimizations that are applied to the session.

payment_method_collection'always' | 'if_required' nullable

Configure whether a Checkout Session should collect a payment method. Defaults to always.

payment_method_typesstring[] required

A list of the types of payment methods (e.g. card) this Checkout Session is allowed to accept.

payment_status'no_payment_required' | 'paid' | 'unpaid' required

The payment status of the Checkout Session, one of paid, unpaid, or no_payment_required. You can use this value to decide when to fulfill your customer's order.

recovered_fromstring nullable

The ID of the original expired Checkout Session that triggered the recovery flow.

redirect_on_completion'always' | 'if_required' | 'never'

This parameter applies to ui_mode: embedded_page. Learn more about the redirect behavior of embedded sessions. Defaults to always.

return_urlstring

Applies to Checkout Sessions with ui_mode: embedded_page or ui_mode: elements. The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method's app or site.

status'complete' | 'expired' | 'open' nullable

The status of the Checkout Session, one of open, complete, or expired.

submit_type'auto' | 'book' | 'donate' | 'pay' | 'subscribe' nullable

Describes the type of transaction being performed by Checkout in order to customize relevant text on the page, such as the submit button. submit_type can only be specified on Checkout Sessions in payment mode. If blank or auto, pay is used.

success_urlstring nullable

The URL the customer will be directed to after the payment or subscription creation is successful.

ui_mode'elements' | 'embedded_page' | 'hosted_page' nullable

The UI mode of the Session. Defaults to hosted_page.

urlstring nullable

The URL to the Checkout Session. Applies to Checkout Sessions with ui_mode: hosted_page. Redirect customers to this URL to take them to Checkout. If you’re using Custom Domains, the URL will use your subdomain. Otherwise, it’ll use checkout.stripe.com. This value is only present when the session is active.

v52

Response