Sessions
A Checkout Session represents your customer’s session as they pay for one-time purchases or subscriptions through Checkout or Payment Links. We recommend creating a new Session each time your customer attempts to pay.
Once payment is successful, the Checkout Session will contain a reference to the Customer, and either the successful PaymentIntent or an active Subscription.
You can create a Checkout Session on your server and redirect to its URL to begin Checkout.
Related guide: Checkout quickstart
The Session object
Attributes
- idstring
Unique identifier for the object.
- 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 withcustomer_creation
set asalways
inpayment
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 associative arrayExpandable The line items purchased by the customer.
- metadatanullable associative array
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.
- payment_
intentnullable stringExpandable The ID of the PaymentIntent for Checkout Sessions in
payment
mode. - payment_
statusenum The payment status of the Checkout Session, one of
paid
,unpaid
, orno_payment_required
. You can use this value to decide when to fulfill your customer’s order. - 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
, orexpired
. - 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
- objectstring
- after_
expirationnullable associative array - allow_
promotion_ codesnullable boolean - amount_
subtotalnullable integer - amount_
totalnullable integer - automatic_
taxassociative array - billing_
address_ collectionnullable enum - cancel_
urlnullable string - client_
secretnullable string - consentnullable associative array
- consent_
collectionnullable associative array - createdtimestamp
- currency_
conversionnullable associative array - custom_
fieldsarray of associative arrays - custom_
textassociative array - customer_
creationnullable enum - customer_
detailsnullable associative array - expires_
attimestamp - invoicenullable stringExpandable
- invoice_
creationnullable associative array - livemodeboolean
- localenullable enum
- payment_
linknullable stringExpandable - payment_
method_ collectionnullable enum - payment_
method_ configuration_ detailsnullable associative array - payment_
method_ optionsnullable associative array - payment_
method_ typesarray of strings - phone_
number_ collectionnullable associative array - recovered_
fromnullable string - redirect_
on_ completionnullable enum - saved_
payment_ method_ optionsnullable associative array - setup_
intentnullable stringExpandable - shipping_
address_ collectionnullable associative array - shipping_
costnullable associative array - shipping_
detailsnullable associative array - shipping_
optionsarray of associative arrays - submit_
typenullable enum - subscriptionnullable stringExpandable
- tax_
id_ collectionnullable associative array - total_
detailsnullable associative array - ui_
modenullable enum
Create a Session
Creates a Session object.
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. Insubscription
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 withcustomer_creation
set asalways
inpayment
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 associative arraysRequired 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. - metadataassociative array
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. - 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
- after_
expirationassociative array - allow_
promotion_ codesboolean - automatic_
taxassociative array - billing_
address_ collectionenum - cancel_
urlstring - consent_
collectionassociative array - currencyenumRequired conditionally
- custom_
fieldsarray of associative arrays - custom_
textassociative array - customer_
creationenum - customer_
updateassociative array - discountsarray of associative arrays
- expires_
attimestamp - invoice_
creationassociative array - localeenum
- payment_
intent_ dataassociative array - payment_
method_ collectionenum - payment_
method_ configurationstring - payment_
method_ dataassociative array - payment_
method_ optionsassociative array - payment_
method_ typesarray of enums - phone_
number_ collectionassociative array - redirect_
on_ completionenum - saved_
payment_ method_ optionsassociative array - setup_
intent_ dataassociative array - shipping_
address_ collectionassociative array - shipping_
optionsarray of associative arrays - submit_
typeenum - subscription_
dataassociative array - tax_
id_ collectionassociative array - ui_
modeenum
Returns
Returns a Session object.
Retrieve a Session
Retrieves a Session object.
Parameters
No parameters.
Returns
Returns a Session object.
Retrieve a Checkout Session's line items
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
- ending_
beforestring - limitinteger
- starting_
afterstring
Returns
A associative array with a data
property that contains an array of up to limit
Checkout Session line items, starting after Line Item starting_after
. Each entry in the array is a separate Line Item object. If no more line items are available, the resulting array will be empty.