The Checkout Session object

Attributes

id string Unique identifier for the object.
automatic _ tax object Details on the state of automatic tax for the session, including the status of the latest tax calculation.
client _ reference _ id nullable 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.
currency nullable enum Three-letter ISO currency code, in lowercase. Must be a supported currency.
customer nullable string Expandable 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 _ email nullable 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 _ items nullable object Includable The line items purchased by the customer.
metadata nullable 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.
mode enum 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 _ intent nullable string Expandable 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 _ status enum 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 _ url nullable 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.
status nullable 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 _ url nullable string The URL the customer will be directed to after the payment or subscription creation is successful.
ui _ mode nullable 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.
url nullable 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

object string, value is "checkout.session"
adaptive _ pricing nullable object
after _ expiration nullable object
allow _ promotion _ codes nullable boolean
allowed _ payment _ method _ types nullable array of strings Preview feature
amount _ subtotal nullable integer
amount _ total nullable integer
billing _ address _ collection nullable enum
branding _ settings nullable object
cancel _ url nullable string
client _ secret nullable string
collected _ information nullable object
consent nullable object
consent _ collection nullable object
created timestamp
currency _ conversion nullable object
custom _ fields array of objects
custom _ text object
customer _ account nullable string
customer _ creation nullable enum
customer _ details nullable object
discounts nullable array of objects
excluded _ payment _ method _ types nullable array of strings
expires _ at timestamp
integration _ identifier nullable string
invoice nullable string Expandable
invoice _ creation nullable object
livemode boolean
locale nullable enum
managed _ payments nullable object
name _ collection nullable object
optional _ items nullable array of objects Includable
origin _ context nullable enum
payment _ link nullable string Expandable
payment _ method _ collection nullable enum
payment _ method _ configuration _ details nullable object
payment _ method _ options nullable object
payment _ method _ types array of strings
permissions nullable object
phone _ number _ collection nullable object
presentment _ details nullable object
recovered _ from nullable string
redirect _ on _ completion nullable enum
saved _ payment _ method _ options nullable object
setup _ intent nullable string Expandable
shipping _ address _ collection nullable object
shipping _ cost nullable object
shipping _ options array of objects
submit _ type nullable enum
subscription nullable string Expandable
tax _ id _ collection nullable object
total _ details nullable object
wallet _ options nullable object

Create a Checkout Session

POST / v1 / checkout / sessions

Creates a Checkout Session object.

Parameters

automatic _ tax object Settings for automatic tax lookup for this session and resulting payments, invoices, and subscriptions.
client _ reference _ id 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. The maximum length is 200 characters.
customer string 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 _ email 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 a session is complete, use the customer field. The maximum length is 800 characters.
line _ items array of objects Required 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.
metadata 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.
mode enum Required 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 _ url string Required 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 _ url string Required 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 _ mode 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.

More parameters

adaptive _ pricing object
after _ expiration object
allow _ promotion _ codes boolean
allowed _ payment _ method _ types array of enums Preview feature
billing _ address _ collection enum
branding _ settings object
cancel _ url string
consent _ collection object
currency enum Required conditionally
custom _ fields array of objects
custom _ text object
customer _ account string
customer _ creation enum
customer _ update object
discounts array of objects
excluded _ payment _ method _ types array of enums
expires _ at timestamp
integration _ identifier string
invoice _ creation object
locale enum
managed _ payments object
name _ collection object
optional _ items array of objects
origin _ context enum
payment _ intent _ data object
payment _ method _ collection enum
payment _ method _ configuration string
payment _ method _ data object
payment _ method _ options object
permissions object
phone _ number _ collection object
redirect _ on _ completion enum
saved _ payment _ method _ options object
setup _ intent _ data object
shipping _ address _ collection object
shipping _ options array of objects
submit _ type enum
subscription _ data object
tax _ id _ collection object
wallet _ options object

Returns

Returns a Checkout Session object.

Response

Update a Checkout Session

POST / v1 / checkout / sessions /:id

Updates a Checkout Session object.

Parameters

line _ items array 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.
metadata 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. 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

collected _ information object
shipping _ options array of objects

Returns

Returns a Checkout Session object.

Response