Creates a Session object.
Parameters
- automatic_
taxdictionary 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 dictionariesRequired 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. - metadatadictionary
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
- adaptive_
pricingdictionary - after_
expirationdictionary - allow_
promotion_ codesboolean - billing_
address_ collectionenum - cancel_
urlstring - consent_
collectiondictionary - currencyenumRequired conditionally
- custom_
fieldsarray of dictionaries - custom_
textdictionary - customer_
creationenum - customer_
updatedictionary - discountsarray of dictionaries
- expires_
attimestamp - invoice_
creationdictionary - localeenum
- payment_
intent_ datadictionary - payment_
method_ collectionenum - payment_
method_ configurationstring - payment_
method_ datadictionary - payment_
method_ optionsdictionary - payment_
method_ typesarray of enums - phone_
number_ collectiondictionary - redirect_
on_ completionenum - saved_
payment_ method_ optionsdictionary - setup_
intent_ datadictionary - shipping_
address_ collectiondictionary - shipping_
optionsarray of dictionaries - submit_
typeenum - subscription_
datadictionary - tax_
id_ collectiondictionary - 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
- metadatadictionary
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"}
Returns a list of Checkout Sessions.
Parameters
- payment_
intentstring Only return the Checkout Session for the PaymentIntent specified.
- subscriptionstring
Only return the Checkout Session for the subscription specified.
More parameters
- createddictionary
- customerstring
- customer_
detailsdictionary - ending_
beforestring - limitinteger
- payment_
linkstring - starting_
afterstring - statusenum
Returns
A dictionary with a data
property that contains an array of up to limit
Checkout Sessions, starting after Checkout Session starting_
. Each entry in the array is a separate Checkout Session object. If no more Checkout Sessions are available, the resulting array will be empty.
{ "object": "list", "url": "/v1/checkout/sessions", "has_more": false, "data": [ { "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" } ]}