Pagination
Every list endpoint pages the same way, as Stripe does.
A list answers with object, data and has_more.
The objects in data are shown cut down here. A real list holds the full objects.
The order is fixed: customers by code, locations and printers by customer, location and creation, and jobs newest first.
Walk a list
An id that is not an object of that list, one that belongs to another organization, or a made-up one gives 400 with invalid_cursor.
Searches can answer a short page
A search by client_reference_id reads only so many rows in one request. It may answer fewer than limit objects, even none, with has_more set to true and a next_cursor. This is for a value that very many objects carry, most of all when the search is narrowed with customer, location or printer.
An empty page with has_more: true is not the end, and it is not “nothing found”. Send the next_cursor as starting_after (or as ending_before, if you page backwards) and ask again, until has_more is false. Only then does every object that carries the value come exactly once.
next_cursoris an id of the kind of the list. It is not always the id of an object indata, and it is accepted as a cursor like any other id of the kind.- A page that fills has no
next_cursor: continue from its last object, as above. has_morecan betruewhen nothing follows. The request that ends the walk then answers an empty page.- A list that is not a search has no
next_cursor. - Version 0.2.1 of the SDKs does not declare
next_cursorin its types, but both return it on the page they give you:(page as { next_cursor?: string }).next_cursorin TypeScript, andpage.next_cursorin Python (it is also inpage.model_extra). Read it there until the types have it.
Prefer a list by location, GET /v1/locations/{location}/printers, or by customer, GET /v1/customers/{customer}/printers, to a list of all the printers of the organization. The organization-wide list, GET /v1/printers, is slower and has no status filter. The lists by location and by customer take status= to filter by the printer’s status.