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:
{
"object": "list",
"data": [ { "id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8", "object": "customer" } ],
"has_more": true,
"next_cursor": "6Yb0mT9wQ3F7ImlkIjo1MTF9"
}limitsets the page size: 1 to 100, 25 when left out. Another value answers422.- Pass
next_cursorascursorto get the next page. Whenhas_moreisfalse,next_cursorisnulland 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
422with its name infields. A filter is never ignored:?search=martinon a list that takesqis 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
cursoranswers400with the typeinvalid_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"]const customers = [];
let cursor = null;
do {
const query = new URLSearchParams({ limit: '100', ...(cursor ? { cursor } : {}) });
const page = await (await fetch(`${BASE}/customers?${query}`, { headers })).json();
customers.push(...page.data);
cursor = page.has_more ? page.next_cursor : null;
} while (cursor);$customers = [];
$cursor = null;
do {
$page = json_decode($client->get('customers', ['query' => array_filter(['limit' => 100, 'cursor' => $cursor])])->getBody(), true);
$customers = array_merge($customers, $page['data']);
$cursor = $page['has_more'] ? $page['next_cursor'] : null;
} while ($cursor);