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.
- 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_
set ascreation always
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 objectExpandable The line items purchased by the customer.
- 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 valuespayment
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
, orno_
. You can use this value to decide when to fulfill your customer’s order.payment_ required Possible enum valuesno_
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_
. The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method’s app or site.mode: embedded - statusnullable enum
The status of the Checkout Session, one of
open
,complete
, orexpired
.Possible enum valuescomplete
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.
This value is only present when the session is active.stripe. com.
More attributes
- objectstring
- 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
{ "id": "cs_test_a11YYufWQzNY63zpQ6QSNRQhkUpVph4WRmzW0zWJO2znZKdVujZ0N0S22u", "object": "checkout.session", "after_expiration": null, "allow_promotion_codes": null, "amount_subtotal": 2198, "amount_total": 2198, "automatic_tax": { "enabled": false, "liability": null, "status": null }, "billing_address_collection": null, "cancel_url": null, "client_reference_id": null, "consent": null, "consent_collection": null, "created": 1679600215, "currency": "usd", "custom_fields": [], "custom_text": { "shipping_address": null, "submit": null }, "customer": null, "customer_creation": "if_required", "customer_details": null, "customer_email": null, "expires_at": 1679686615, "invoice": null, "invoice_creation": { "enabled": false, "invoice_data": { "account_tax_ids": null, "custom_fields": null, "description": null, "footer": null, "issuer": null, "metadata": {}, "rendering_options": null } }, "livemode": false, "locale": null, "metadata": {}, "mode": "payment", "payment_intent": null, "payment_link": null, "payment_method_collection": "always", "payment_method_options": {}, "payment_method_types": [ "card" ], "payment_status": "unpaid", "phone_number_collection": { "enabled": false }, "recovered_from": null, "setup_intent": null, "shipping_address_collection": null, "shipping_cost": null, "shipping_details": null, "shipping_options": [], "status": "open", "submit_type": null, "subscription": null, "success_url": "https://example.com/success", "total_details": { "amount_discount": 0, "amount_shipping": 0, "amount_tax": 0 }, "url": "https://checkout.stripe.com/c/pay/cs_test_a11YYufWQzNY63zpQ6QSNRQhkUpVph4WRmzW0zWJO2znZKdVujZ0N0S22u#fidkdWxOYHwnPyd1blpxYHZxWjA0SDdPUW5JbmFMck1wMmx9N2BLZjFEfGRUNWhqTmJ%2FM2F8bUA2SDRySkFdUV81T1BSV0YxcWJcTUJcYW5rSzN3dzBLPUE0TzRKTTxzNFBjPWZEX1NKSkxpNTVjRjN8VHE0YicpJ2N3amhWYHdzYHcnP3F3cGApJ2lkfGpwcVF8dWAnPyd2bGtiaWBabHFgaCcpJ2BrZGdpYFVpZGZgbWppYWB3dic%2FcXdwYHgl"}
Creates a Session object.
Parameters
- automatic_
taxobject Settings for automatic tax lookup for this session and resulting payments, invoices, and subscriptions.
- 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_
set ascreation always
inpayment
mode, Checkout will create a new Customer object based on information provided during the payment flow.You can set
payment_
to have Checkout automatically attach the payment method to the Customer you pass in for future reuse.intent_ data. setup_ future_ usage - 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. - 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 valuespayment
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
- 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
Returns
Returns a Session object.
{ "id": "cs_test_a11YYufWQzNY63zpQ6QSNRQhkUpVph4WRmzW0zWJO2znZKdVujZ0N0S22u", "object": "checkout.session", "after_expiration": null, "allow_promotion_codes": null, "amount_subtotal": 2198, "amount_total": 2198, "automatic_tax": { "enabled": false, "liability": null, "status": null }, "billing_address_collection": null, "cancel_url": null, "client_reference_id": null, "consent": null, "consent_collection": null, "created": 1679600215, "currency": "usd", "custom_fields": [], "custom_text": { "shipping_address": null, "submit": null }, "customer": null, "customer_creation": "if_required", "customer_details": null, "customer_email": null, "expires_at": 1679686615, "invoice": null, "invoice_creation": { "enabled": false, "invoice_data": { "account_tax_ids": null, "custom_fields": null, "description": null, "footer": null, "issuer": null, "metadata": {}, "rendering_options": null } }, "livemode": false, "locale": null, "metadata": {}, "mode": "payment", "payment_intent": null, "payment_link": null, "payment_method_collection": "always", "payment_method_options": {}, "payment_method_types": [ "card" ], "payment_status": "unpaid", "phone_number_collection": { "enabled": false }, "recovered_from": null, "setup_intent": null, "shipping_address_collection": null, "shipping_cost": null, "shipping_details": null, "shipping_options": [], "status": "open", "submit_type": null, "subscription": null, "success_url": "https://example.com/success", "total_details": { "amount_discount": 0, "amount_shipping": 0, "amount_tax": 0 }, "url": "https://checkout.stripe.com/c/pay/cs_test_a11YYufWQzNY63zpQ6QSNRQhkUpVph4WRmzW0zWJO2znZKdVujZ0N0S22u#fidkdWxOYHwnPyd1blpxYHZxWjA0SDdPUW5JbmFMck1wMmx9N2BLZjFEfGRUNWhqTmJ%2FM2F8bUA2SDRySkFdUV81T1BSV0YxcWJcTUJcYW5rSzN3dzBLPUE0TzRKTTxzNFBjPWZEX1NKSkxpNTVjRjN8VHE0YicpJ2N3amhWYHdzYHcnP3F3cGApJ2lkfGpwcVF8dWAnPyd2bGtiaWBabHFgaCcpJ2BrZGdpYFVpZGZgbWppYWB3dic%2FcXdwYHgl"}
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
.
Returns
Returns a Session object.
{ "id": "cs_test_a11YYufWQzNY63zpQ6QSNRQhkUpVph4WRmzW0zWJO2znZKdVujZ0N0S22u", "object": "checkout.session", "after_expiration": null, "allow_promotion_codes": null, "amount_subtotal": 2198, "amount_total": 2198, "automatic_tax": { "enabled": false, "liability": null, "status": null }, "billing_address_collection": null, "cancel_url": null, "client_reference_id": null, "consent": null, "consent_collection": null, "created": 1679600215, "currency": "usd", "custom_fields": [], "custom_text": { "shipping_address": null, "submit": null }, "customer": null, "customer_creation": "if_required", "customer_details": null, "customer_email": null, "expires_at": 1679686615, "invoice": null, "invoice_creation": { "enabled": false, "invoice_data": { "account_tax_ids": null, "custom_fields": null, "description": null, "footer": null, "issuer": null, "metadata": {}, "rendering_options": null } }, "livemode": false, "locale": null, "metadata": { "order_id": "6735" }, "mode": "payment", "payment_intent": null, "payment_link": null, "payment_method_collection": "always", "payment_method_options": {}, "payment_method_types": [ "card" ], "payment_status": "unpaid", "phone_number_collection": { "enabled": false }, "recovered_from": null, "setup_intent": null, "shipping_address_collection": null, "shipping_cost": null, "shipping_details": null, "shipping_options": [], "status": "open", "submit_type": null, "subscription": null, "success_url": "https://example.com/success", "total_details": { "amount_discount": 0, "amount_shipping": 0, "amount_tax": 0 }, "url": "https://checkout.stripe.com/c/pay/cs_test_a11YYufWQzNY63zpQ6QSNRQhkUpVph4WRmzW0zWJO2znZKdVujZ0N0S22u#fidkdWxOYHwnPyd1blpxYHZxWjA0SDdPUW5JbmFMck1wMmx9N2BLZjFEfGRUNWhqTmJ%2FM2F8bUA2SDRySkFdUV81T1BSV0YxcWJcTUJcYW5rSzN3dzBLPUE0TzRKTTxzNFBjPWZEX1NKSkxpNTVjRjN8VHE0YicpJ2N3amhWYHdzYHcnP3F3cGApJ2lkfGpwcVF8dWAnPyd2bGtiaWBabHFgaCcpJ2BrZGdpYFVpZGZgbWppYWB3dic%2FcXdwYHgl"}
Retrieves a Session object.
Parameters
No parameters.
Returns
Returns a Session object.
{ "id": "cs_test_a11YYufWQzNY63zpQ6QSNRQhkUpVph4WRmzW0zWJO2znZKdVujZ0N0S22u", "object": "checkout.session", "after_expiration": null, "allow_promotion_codes": null, "amount_subtotal": 2198, "amount_total": 2198, "automatic_tax": { "enabled": false, "liability": null, "status": null }, "billing_address_collection": null, "cancel_url": null, "client_reference_id": null, "consent": null, "consent_collection": null, "created": 1679600215, "currency": "usd", "custom_fields": [], "custom_text": { "shipping_address": null, "submit": null }, "customer": null, "customer_creation": "if_required", "customer_details": null, "customer_email": null, "expires_at": 1679686615, "invoice": null, "invoice_creation": { "enabled": false, "invoice_data": { "account_tax_ids": null, "custom_fields": null, "description": null, "footer": null, "issuer": null, "metadata": {}, "rendering_options": null } }, "livemode": false, "locale": null, "metadata": {}, "mode": "payment", "payment_intent": null, "payment_link": null, "payment_method_collection": "always", "payment_method_options": {}, "payment_method_types": [ "card" ], "payment_status": "unpaid", "phone_number_collection": { "enabled": false }, "recovered_from": null, "setup_intent": null, "shipping_address_collection": null, "shipping_cost": null, "shipping_details": null, "shipping_options": [], "status": "open", "submit_type": null, "subscription": null, "success_url": "https://example.com/success", "total_details": { "amount_discount": 0, "amount_shipping": 0, "amount_tax": 0 }, "url": "https://checkout.stripe.com/c/pay/cs_test_a11YYufWQzNY63zpQ6QSNRQhkUpVph4WRmzW0zWJO2znZKdVujZ0N0S22u#fidkdWxOYHwnPyd1blpxYHZxWjA0SDdPUW5JbmFMck1wMmx9N2BLZjFEfGRUNWhqTmJ%2FM2F8bUA2SDRySkFdUV81T1BSV0YxcWJcTUJcYW5rSzN3dzBLPUE0TzRKTTxzNFBjPWZEX1NKSkxpNTVjRjN8VHE0YicpJ2N3amhWYHdzYHcnP3F3cGApJ2lkfGpwcVF8dWAnPyd2bGtiaWBabHFgaCcpJ2BrZGdpYFVpZGZgbWppYWB3dic%2FcXdwYHgl"}
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 dictionary with a data
property that contains an array of up to limit
Checkout Session line items, starting after Line Item starting_
. Each entry in the array is a separate Line Item object. If no more line items are available, the resulting array will be empty.
{ "object": "list", "data": [ { "id": "li_1N4BEoLkdIwHu7ixWtXug1yk", "object": "item", "amount_discount": 0, "amount_subtotal": 2198, "amount_tax": 0, "amount_total": 2198, "currency": "usd", "description": "T-shirt", "price": { "id": "price_1N4AEsLkdIwHu7ix7Ssho8Cl", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1683237782, "currency": "usd", "custom_unit_amount": null, "livemode": false, "lookup_key": null, "metadata": {}, "nickname": null, "product": "prod_NppuJWzzNnD5Ut", "recurring": null, "tax_behavior": "unspecified", "tiers_mode": null, "transform_quantity": null, "type": "one_time", "unit_amount": 1099, "unit_amount_decimal": "1099" }, "quantity": 2 } ], "has_more": false, "url": "/v1/checkout/sessions/cs_test_a1enSAC01IA3Ps2vL32mNoWKMCNmmfUGTeEeHXI5tLCvyFNGsdG2UNA7mr/line_items"}