Checkout Sessions

The Checkout Sessions API lets you read checkout sessions from your store: carts a buyer started, including ones that never became an order.

Overview

The Checkout Sessions API provides endpoints to:

• List checkout sessions
• Retrieve checkout session details

Checkout creates and updates sessions. These endpoints only read them.

GET /statistics?type=checkout_sessions is a separate count. It does not return these session objects.

Endpoints

Method	Path	Description
GET	/checkout-sessions	Paginated list. See Get Checkout Sessions.
GET	/checkout-sessions/{id}	One session. See Get Checkout Session.

{id} is the session id (a UUID).

Status

status is one of six slugs. Omitting the list filter returns every status.

Status	Meaning
opened	The buyer started checkout and has not finished.
errored	Checkout recorded an error.
finalized	The buyer completed checkout.
recovering	The buyer opened checkout through a recovery link. Sending a recovery email does not change the status on its own. The send times are the recovery_link_sent_at fields on the detail read.
recovered	The session was completed after the buyer came back through a recovery link, or support marked it recovered. Support can mark a session recovered after it was already finalized. recovered_by says who is credited with the recovery.
help_requested	The buyer asked for help.

opened and errored can still be recovered. finalized and recovered are complete.

Currency

currency on the list is optional. Omit it to return sessions in every currency. Each item still includes its own amount and currency. Either can be null: amount when the cart has no price yet, currency on older sessions that stored none.

amount is an integer in minor units (e.g. cents). 4900 with currency usd is 49.00 USD.

To keep one currency, pass a lowercase ISO-4217 code, for example usd.

There is no default date window. Omit created_from and created_to to skip a date filter. See Get Checkout Sessions.

Checkout Session Object

The list returns a subset of this object. Get Checkout Sessions documents that subset. Get Checkout Session returns the full object. customer, product, and order are always present on the detail read and are null until requested with include.

Field	Type	Nullable	Description
id	string	No	Session UUID.
status	string	No	One of the status slugs.
amount	integer	Yes	Cart total in minor units (e.g. cents). Null when the cart has no price yet.
currency	string	Yes	Lowercase ISO-4217 code (e.g. usd). Null on older sessions that stored none.
quantity	integer	No	Quantity in the cart.
product_name	string	Yes	Product name. Null when the product no longer exists.
customer_email	string	Yes	Email stored on the session. Null when the cart has no email yet. Independent of the customer include.
full_name	string	Yes	Buyer name. Null when the cart has no name yet.
created_at	string	No	When the session was created (ISO 8601).
updated_at	string	No	When the session was last updated (ISO 8601). Not limited to buyer edits. Detail only.
terms_accepted	boolean	No	Whether the buyer accepted the terms. Detail only.
recovered_by	string	Yes	Who is credited with recovering the session: email when the buyer came back through a recovery email link, support when support marked it recovered. Null when no recovery is credited. Recorded independently of status, so it can be set on a session that is not recovered and null on one that is. Detail only.
recovery_link_sent_at	string	Yes	When the first recovery email was sent (ISO 8601). Null when none was sent. Detail only.
second_recovery_link_sent_at	string	Yes	When the second recovery email was sent (ISO 8601). Null when it was not sent. Detail only.
customer	object	Yes	Linked customer. Null unless customer is included, when the session has no linked customer, or when that customer is not linked to this store. customer_email can still be set. Detail only.
product	object	Yes	Product. Null unless product is included, and null when the product no longer exists. Detail only.
order	object	Yes	Order created from this session. Null unless order is included, and null when the session has no order. Detail only.

Customer Object

Returned only when include contains customer and a customer linked to this store exists.

Field	Type	Nullable	Description
id	string	No	Customer UUID.
email	string	Yes	Customer email.
name	string	Yes	Customer name.

Product Object

Returned only when include contains product and the product still exists. id is the product UUID.

Field	Type	Nullable	Description
id	string	No	Product UUID.
name	string	No	Product name.

Order Object

Returned only when include contains order and the session has an order. status uses the same slugs as Get Orders. amount is an integer in minor units (e.g. cents).

Field	Type	Nullable	Description
id	string	No	Order UUID. Pass it to Get Order.
status	string	No	Order status: created, awaiting_payment, processing, completed, canceled, or refunded.
amount	integer	No	Order total in minor units (e.g. cents).
currency	string	No	Lowercase ISO-4217 code (e.g. usd).
created_at	string	No	When the order was created (ISO 8601).