Get Checkout Sessions

Retrieve a list of checkout sessions from your store.

Sessions of every status and every currency are returned by default, newest first. Narrow the list with the optional filters below. All filters combine with AND.

Request

GET /checkout-sessions

Query Parameters

Parameter	Type	Required	Default	Description
page	integer	No	1	Page number for pagination.
per_page	integer	No	10	Items per page (min: 1, max: 100).
sort	string	No	-created_at	Sort field: created_at. Prefix with - for descending.
status	string	No	none	One status: opened, errored, finalized, recovering, recovered, or help_requested.
created_from	string	No	none	Only sessions created on or after this date (inclusive), YYYY-MM-DD. No date window when omitted.
created_to	string	No	none	Only sessions created on or before this date (inclusive), YYYY-MM-DD. No date window when omitted.
customer	string	No	none	Filter by customer UUID.
product	string	No	none	Filter by product UUID. A UUID that does not belong to this store matches nothing.
query	string	No	none	Search term. Matched as an exact session email when it is a valid email address, otherwise as a partial match on the buyer name.
currency	string	No	none	Lowercase ISO-4217 code (e.g. usd). Omit it to return every currency. Each item still carries its own amount and currency.

Omitting a filter or passing it empty means no filter on that field. A present but unparseable value returns 400 (see Bad Request). That includes an unknown status, a malformed date, a non-UUID customer or product, a currency that is not a 3-letter code, an out-of-range per_page, or an unknown sort field. The query search term is free text and is always accepted.

Ordering: Sessions default to created_at descending (newest first) unless sort is supplied.

Counting matches: every response includes the filtered total in pagination.total. To get only a count, request per_page=1 with your filters and read pagination.total.

Example Request

curl -X GET "https://cart.easy.tools/api/v1/checkout-sessions?per_page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Success Response (200)

Returns a paginated list of checkout sessions. The example requests one item.

{
  "items": [
    {
      "id": "dc39545d-3cfa-45d6-82cd-1f227cae763a",
      "status": "opened",
      "amount": 3900,
      "currency": "usd",
      "quantity": 1,
      "product_name": "Starter Workshop",
      "customer_email": "buyer@example.com",
      "full_name": "Jane Doe",
      "created_at": "2026-09-09T10:07:20+02:00"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 3215,
    "per_page": 1,
    "total": 3215
  }
}

Response Fields

The list item is a subset of the Checkout Session object. amount is an integer in minor units (e.g. cents), or null.

Field	Type	Nullable	Description
id	string	No	Session UUID.
status	string	No	Session status (see Status).
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.
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).

To read recovery timestamps, terms, or the linked customer, product, and order, call Get Checkout Session with include.

Pagination Object

Field	Type	Description
current_page	integer	Current page number.
total_pages	integer	Total number of pages.
per_page	integer	Effective page size (echoes the per_page request parameter).
total	integer	Total number of sessions matching the applied filters, across all pages.

Error Responses

Bad Request (400)

Returned when a filter has a non-empty but unparseable value. The message names the offending field and the value received.

{
  "message": "Invalid value for 'status': 'opned'"
}

Unauthorized Error (401)

{
  "message": "Unauthenticated."
}

Forbidden Error (403)

Returned when your API key has not been granted access to the requested store.

{
  "message": "You do not have API access to the requested store."
}

Rate Limit Error (429 Too Many Requests)

Returned when you exceed the rate limit. The Retry-After response header gives the number of seconds to wait.

{
  "message": "Too many requests. Please retry after 60 seconds."
}