Skip to content

Listing Checkouts ​

Find the checkouts a reader started with your publication, including the ones they never finished.

Overview ​

A checkout is created when a reader starts to buy. It is PENDING until they pay and COMPLETED once the purchase goes through. A reader who leaves in between leaves a PENDING checkout behind. Listing them lets you follow up with an offer or a reminder.

GET https://api2.sesamy.com/management/checkouts

The request needs the checkouts:read scope. It returns the checkouts of your own publication only, newest first.

Find a Reader's Incomplete Checkouts ​

Pass the reader's userId and status=PENDING:

bash
curl -G "https://api2.sesamy.com/management/checkouts" \
  --data-urlencode "userId=auth0|6123456789" \
  --data-urlencode "status=PENDING" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

User ids can contain a pipe, as in auth0|6123456789, so URL-encode the value. curl -G with --data-urlencode does it for you. Leave userId out to list the incomplete checkouts of every reader.

The response is a list of checkouts:

json
[
  {
    "id": "checkout_345",
    "status": "PENDING",
    "type": "RECURRING",
    "createdAt": "2026-10-20T10:00:00.000Z",
    "updatedAt": "2026-10-20T10:05:00.000Z",
    "currency": "SEK",
    "userId": "auth0|6123456789",
    "total": 14900,
    "items": [{ "sku": "sid:acme-plus-monthly", "title": "ACME Plus" }]
  }
]

total is in minor units, so 14900 is 149.00 SEK.

A PENDING checkout is not abandoned the moment it appears: the reader may still be paying. Treat it as abandoned only after a delay, for example an hour since updatedAt, so you do not nudge someone who is about to finish.

Check for an Active Contract First ​

A completed purchase always creates an active contract. Before you follow up on a PENDING checkout, check that the reader has no active contract, for example one from a later purchase. Look the reader up with GET /management/contracts?userId=... (see the contracts section of the Management API reference) and skip the follow-up if one of them is active.

Parameters ​

ParameterDescription
userId(Optional) Only the checkouts of this reader
status(Optional) PENDING, WAITING_PAYMENT_CONFIRMATION, COMPLETED or FAILED
q(Optional) A search query, up to 200 characters and 20 words. A longer one returns 400
limit(Optional) 1 to 100, default 20. A value outside the range returns 400
from(Optional) The offset of the first result, default 0

Pagination ​

Checkouts come back newest first. To get the next page, raise from by limit and keep the other parameters the same. A page with fewer results than limit is the last one. from plus limit cannot go past 10,000, and a request that does returns 400. Narrow the search with status, userId or q instead of paging that far.

bash
curl -G "https://api2.sesamy.com/management/checkouts" \
  --data-urlencode "userId=auth0|6123456789" \
  --data-urlencode "status=PENDING" \
  --data-urlencode "limit=20" \
  --data-urlencode "from=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Good to Know ​

  • A checkout only has a userId once the reader has logged in. A reader who left before logging in has no user on the checkout, so it cannot be found this way.
  • Old checkouts can disappear from the single lookup. A listed id can return 404 from GET /management/checkouts/{id} once the checkout is older than 7 days. Keep what you need from the list response.
  • The response carries personal data, such as the reader's email and name when they are known. Handle it as you would any reader data and keep it out of logs.

Business Customers ​

A company that buys seats for its staff holds a multi-seat contract. The seat holders get entitlements with origin type LICENSE, a role of owner or member, and the contractId of that contract. See Multi-Seat Contracts for how the seats work.

To find the company behind such an entitlement, fetch the contract with GET /management/contracts/{contractId}. The contract's userId is the company account. A separate payer is present only when the invoice goes to someone else.

Next Steps ​

Released under the MIT License.