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

• urlnullable string

  The URL to the Checkout Session. 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

• consentnullable object

• consent_collectionnullable object

• createdtimestamp

• currency_conversionnullable object

• custom_fieldsarray of objects

• custom_textobject

• customer_creationnullable enum

• customer_detailsnullable object

• expires_attimestamp

• invoicenullable stringExpandable

• invoice_creationnullable object

• livemodeboolean

• localenullable enum

• payment_linknullable stringExpandable

• payment_method_collectionnullable enum

• payment_method_configuration_detailsnullable object

• payment_method_optionsnullable object

• payment_method_typesarray of strings

• phone_number_collectionnullable object

• recovered_fromnullable string

• redirect_on_completionnullable enum

• saved_payment_method_optionsnullable object

• setup_intentnullable stringExpandable

• shipping_address_collectionnullable object

• shipping_costnullable object

• shipping_detailsnullable object

• shipping_optionsarray of objects

• submit_typenullable enum

• subscriptionnullable stringExpandable

• tax_id_collectionnullable object

• total_detailsnullable object

• ui_modenullable enum

Creates a 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 unless setup mode

  A list of items the customer is purchasing. Use this parameter to pass one-time or recurring Prices.

  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 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. If you’d like to use information from the successful Checkout Session on your page, read the guide on customizing your success page.

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

• payment_intent_dataobject

• payment_method_collectionenum

• payment_method_configurationstring

• payment_method_dataobject

• payment_method_optionsobject

• payment_method_typesarray of enums

• 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

• ui_modeenum

Updates a Session object.

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.

Retrieves a 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