Pagination and errors

Pagination

List endpoints share one paging model.

page_start is a page number and it starts at 1. It is not a record offset. Sending page_start=0 returns the first page.

page_size is the number of records per page. When you leave it out you get 10, which is smaller than most integrations want. Set it explicitly.

On the stores list, page_size=-1 returns every matching record in a single page. Any other negative value is rejected.

Every paged response wraps its records in the same envelope:

{
  "total_count": 1284,
  "page_start": 3,
  "page_size": 100,
  "previous_page": 2,
  "next_page": 4,
  "list": [ ... ]
}

next_page is null on the last page, which is the cleanest way to know when to stop. The SDKs use this envelope to page for you, so you rarely need to read it directly.

Paging a changing dataset

Page numbers move when records are inserted while you are reading. For a stable walk through the stock movement log, page by from_id instead. See Keeping stock in sync.

Errors

A failed request normally returns a 4xx status with this body:

{
  "error": "input_error",
  "error_description": "Store No '999' does not exist."
}

error is a short stable code you can branch on. error_description is a human-readable message and may be translated, so do not match on its text.