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 objectIncludable

  The line items purchased by the customer.

  Show child attributes

• metadatanullable map

  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 Checkout Session is in setup mode and doesn’t require a payment at this time, or the Session uses a billing cycle anchor with no proration and payment will be collected at the anchor date.

  paid The payment funds are available in your account. For subscriptions with a free trial, this indicates that the $0 trial invoice has been successfully processed.

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

• return_urlnullable string

  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.

• 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_page.

  Possible enum values

  elements The Checkout Session is displayed using Checkout elements on your website.

  embedded_page The Checkout Session is displayed as an embedded form on your website.

  form The Checkout Session is displayed using the Checkout form on your website.

  hosted_page The Checkout Session is displayed on a hosted page that customers get redirected to.

• urlnullable string

  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.

More attributes

Expand all

• objectstring, value is "checkout.session"

• adaptive_pricingnullable object

• after_expirationnullable object

• allow_promotion_codesnullable boolean

• allowed_payment_method_typesnullable array of strings

• amount_subtotalnullable integer

• amount_totalnullable integer

• billing_address_collectionnullable enum

• branding_settingsnullable object

• 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_accountnullable string

• customer_creationnullable enum

• customer_detailsnullable object

• discountsnullable array of objects

• excluded_payment_method_typesnullable array of strings

• expires_attimestamp

• integration_identifiernullable string

• invoicenullable stringExpandable

• invoice_creationnullable object

• livemodeboolean

• localenullable enum

• managed_paymentsnullable object

• name_collectionnullable object

• optional_itemsnullable array of objectsIncludable

• origin_contextnullable enum

• 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.

  The maximum length is 200 characters.

• 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.

  The maximum length is 800 characters.

• 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

• metadatamap

  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_page or elements 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_page or elements. 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_page.

  Possible enum values

  elements The Checkout Session is displayed using Checkout elements on your website.

  embedded_page The Checkout Session is displayed as an embedded form on your website.

  form The Checkout Session is displayed using the Checkout form on your website.

  hosted_page The Checkout Session is displayed on a hosted page that customers get redirected to.

More parameters

Expand all

• adaptive_pricingobject

• after_expirationobject

• allow_promotion_codesboolean

• allowed_payment_method_typesarray of enums

• billing_address_collectionenum

• branding_settingsobject

• cancel_urlstring

• consent_collectionobject

• currencyenumRequired conditionally

• custom_fieldsarray of objects

• custom_textobject

• customer_accountstring

• customer_creationenum

• customer_updateobject

• discountsarray of objects

• excluded_payment_method_typesarray of enums

• expires_attimestamp

• integration_identifierstring

• invoice_creationobject

• localeenum

• managed_paymentsobject

• name_collectionobject

• optional_itemsarray of objects

• origin_contextenum

• payment_intent_dataobject

• payment_method_collectionenum

• payment_method_configurationstring

• payment_method_dataobject

• payment_method_optionsobject

• 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 a Checkout Session

Parameters

• line_itemsarray of objects

  A list of items the customer is purchasing.

  When updating line items, you must retransmit the entire array of line items.

  To retain an existing line item, specify its id.

  To update an existing line item, specify its id along with the new values of the fields to update.

  To add a new line item, specify one of price or price_data and quantity.

  To remove an existing line item, omit the line item’s ID from the retransmitted array.

  To reorder a line item, specify it at the desired position in the retransmitted array.

  Show child parameters

• metadatamap

  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

• payment_intent_dataobject

• shipping_optionsarray of objects