Attributes

• idstring

  Unique identifier for the object.

• automatic_taxobject

  Details on the state of automatic tax for the session, including the status of the latest tax calculation.

  Show child attributes

• client_reference_idnullable string

  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.

• currencynullable enum

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

• customernullable stringExpandable

  The ID of the customer for this Session. For Checkout Sessions in subscription mode or Checkout Sessions with customer_creation set as always in payment mode, Checkout will create a new customer object based on information provided during the payment flow unless an existing customer was provided when the Session was created.

• customer_emailnullable string

  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.

• line_itemsnullable objectExpandable

  The line items purchased by the customer.

  Show child attributes

• metadatanullable object

  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.

• modeenum

  The mode of the Checkout Session.

  Possible enum values

  payment Accept one-time payments for cards, iDEAL, and more.

  setup Save payment details to charge your customers later.

  subscription Use Stripe Billing to set up fixed-price subscriptions.

• payment_intentnullable stringExpandable

  The ID of the PaymentIntent for Checkout Sessions in payment mode. You can’t confirm or cancel the PaymentIntent for a Checkout Session. To cancel, expire the Checkout Session instead.

• payment_statusenum

  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.

  Possible enum values

  no_payment_required The payment is delayed to a future date, or the Checkout Session is in setup mode and doesn’t require a payment at this time.

  paid The payment funds are available in your account.

  unpaid The payment funds are not yet available in your account.

• return_urlnullable string

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

• statusnullable enum

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

  Possible enum values

  complete The checkout session is complete. Payment processing may still be in progress

  expired The checkout session has expired. No further processing will occur

  open The checkout session is still in progress. Payment processing has not started

• success_urlnullable string

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

• ui_modenullable enum

  The UI mode of the Session. Defaults to hosted.

  Possible enum values

  custom The Checkout Session will be displayed using embedded components on your website

  embedded The Checkout Session will be displayed as an embedded form on your website.

  hosted The Checkout Session will be displayed on a hosted page that customers will be redirected to.

• urlnullable string

  The URL to the Checkout Session. Applies to Checkout Sessions with ui_mode: hosted. 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.

More attributes

Expand all

• objectstring

• adaptive_pricingnullable object

• after_expirationnullable object

• allow_promotion_codesnullable boolean

• amount_subtotalnullable integer

• amount_totalnullable integer

• billing_address_collectionnullable enum

• cancel_urlnullable string

• client_secretnullable string

• collected_informationnullable object

• consentnullable object

• consent_collectionnullable object

• createdtimestamp

• currency_conversionnullable object

• custom_fieldsarray of objects

• custom_textobject

• customer_creationnullable enum

• customer_detailsnullable object

• discountsnullable array of objects

• expires_attimestamp

• invoicenullable stringExpandable

• invoice_creationnullable object

• livemodeboolean

• localenullable enum

• optional_itemsnullable array of objectsExpandable

• payment_linknullable stringExpandable

• payment_method_collectionnullable enum

• payment_method_configuration_detailsnullable object

• payment_method_optionsnullable object

• payment_method_typesarray of strings

• permissionsnullable object

• phone_number_collectionnullable object

• presentment_detailsnullable object

• recovered_fromnullable string

• redirect_on_completionnullable enum

• saved_payment_method_optionsnullable object

• setup_intentnullable stringExpandable

• shipping_address_collectionnullable object

• shipping_costnullable object

• shipping_optionsarray of objects

• submit_typenullable enum

• subscriptionnullable stringExpandable

• tax_id_collectionnullable object

• total_detailsnullable object

• wallet_optionsnullable object

Creates a Checkout Session object.

Parameters

• automatic_taxobject

  Settings for automatic tax lookup for this session and resulting payments, invoices, and subscriptions.

  Show child parameters

• client_reference_idstring

  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.

• customerstring

  ID of an existing Customer, if one exists. In payment mode, the customer’s most recently saved card payment method will be used to prefill the email, name, card details, and billing address on the Checkout page. In subscription mode, the customer’s default payment method will be used if it’s a card, otherwise the most recently saved card will be used. A valid billing address, billing name and billing email are required on the payment method for Checkout to prefill the customer’s card details.

  If the Customer already has a valid email set, the email will be prefilled and not editable in Checkout. If the Customer does not have a valid email, Checkout will set the email entered during the session on the Customer.

  If blank for Checkout Sessions in subscription mode or with customer_creation set as always in payment mode, Checkout will create a new Customer object based on information provided during the payment flow.

  You can set payment_intent_data.setup_future_usage to have Checkout automatically attach the payment method to the Customer you pass in for future reuse.

• customer_emailstring

  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 a session is complete, use the customer field.

• line_itemsarray of objectsRequired conditionally

  A list of items the customer is purchasing. Use this parameter to pass one-time or recurring Prices. The parameter is required for payment and subscription mode.

  For payment mode, there is a maximum of 100 line items, however it is recommended to consolidate line items if there are more than a few dozen.

  For subscription mode, there is a maximum of 20 line items with recurring Prices and 20 line items with one-time Prices. Line items with one-time Prices will be on the initial invoice only.

  Show child parameters

• metadataobject

  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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

• modeenumRequired

  The mode of the Checkout Session. Pass subscription if the Checkout Session includes at least one recurring item.

  Possible enum values

  payment Accept one-time payments for cards, iDEAL, and more.

  setup Save payment details to charge your customers later.

  subscription Use Stripe Billing to set up fixed-price subscriptions.

• return_urlstringRequired conditionally

  The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method’s app or site. This parameter is required if ui_mode is embedded or custom and redirect-based payment methods are enabled on the session.

• success_urlstringRequired conditionally

  The URL to which Stripe should send customers when payment or setup is complete. This parameter is not allowed if ui_mode is embedded or custom. If you’d like to use information from the successful Checkout Session on your page, read the guide on customizing your success page.

• ui_modeenum

  The UI mode of the Session. Defaults to hosted.

  Possible enum values

  custom The Checkout Session will be displayed using embedded components on your website

  embedded The Checkout Session will be displayed as an embedded form on your website.

  hosted The Checkout Session will be displayed on a hosted page that customers will be redirected to.

More parameters

Expand all

• adaptive_pricingobject

• after_expirationobject

• allow_promotion_codesboolean

• billing_address_collectionenum

• cancel_urlstring

• consent_collectionobject

• currencyenumRequired conditionally

• custom_fieldsarray of objects

• custom_textobject

• customer_creationenum

• customer_updateobject

• discountsarray of objects

• expires_attimestamp

• invoice_creationobject

• localeenum

• optional_itemsarray of objects

• payment_intent_dataobject

• payment_method_collectionenum

• payment_method_configurationstring

• payment_method_dataobject

• payment_method_optionsobject

• payment_method_typesarray of enums

• permissionsobject

• phone_number_collectionobject

• redirect_on_completionenum

• saved_payment_method_optionsobject

• setup_intent_dataobject

• shipping_address_collectionobject

• shipping_optionsarray of objects

• submit_typeenum

• subscription_dataobject

• tax_id_collectionobject

• wallet_optionsobject

Updates a Checkout Session object.

Related guide: Dynamically update Checkout

Parameters

• metadataobject

  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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

More parameters

Expand all

• collected_informationobject

• shipping_optionsarray of objects

Retrieves a Checkout Session object.

Parameters

No parameters.

When retrieving a Checkout Session, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.

Parameters

No parameters.

More parameters

Expand all

• ending_beforestring

• limitinteger

• starting_afterstring