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

Retrieve a Checkout Session

GET / v1 / checkout / sessions /:id

Retrieves a Checkout Session object.

Parameters

No parameters.

Returns

Returns a Checkout Session object.

Response