Conventions

Pagination

Lists come a page at a time, newest first, with a cursor to the next page.

The shape of a list

Every list answers with the same shape:

JSON
{
  "object": "list",
  "data": [ { "id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8", "object": "customer" } ],
  "has_more": true,
  "next_cursor": "6Yb0mT9wQ3F7ImlkIjo1MTF9"
}
  • limit sets the page size: 1 to 100, 25 when left out. Another value answers 422.
  • Pass next_cursor as cursor to get the next page. When has_more is false, next_cursor is null and you have it all.
  • Filters (status, q, updated_since, …) apply to every page: send them again with the cursor.
  • A query parameter the list does not take answers 422 with its name in fields. A filter is never ignored: ?search=martin on a list that takes q is an error, not the whole list.
  • A cursor is an opaque string: do not make one, change one or read anything from it. It is signed, and it belongs to the list, the partner and the mode (live or sandbox) it came from. Anything else in cursor answers 400 with the type invalid_cursor: a string you made yourself, a cursor that was cut short, or the cursor of another list.
  • There is no total count and no way to jump to a page.

Order

Lists are newest first, by when the object was created, and cannot be sorted another way. Something created while you page appears at the top, not in the middle, so a cursor never skips or repeats an object.

Three lists are ordered differently:

List Order
List events Newest first; oldest first with after or order=asc, to read on from where you stopped
List support threads By their last message, newest first
List messages Always oldest first, as a conversation reads. It has no cursor: page with after or before and a message's ID, 50 at a time unless limit says otherwise

Lists that are never paged

A few short lists come whole. They have the same shape, with has_more always false, and take no limit or cursor: Find look-alike customers, Redeliver failed deliveries, List the last 12 months, List support tags, List a thread's drafts and Find similar escalations. The reference says so on each.

Reading a whole list

customers, cursor = [], None
while True:
    params = {"limit": 100, **({"cursor": cursor} if cursor else {})}
    page = requests.get(f"{BASE}/customers", headers=HEADERS, params=params).json()
    customers += page["data"]
    if not page["has_more"]:
        break
    cursor = page["next_cursor"]