Pagination Conventions

4 min

Pagination

All the APIs paginate with cursors, except for the PMS lists of the Accounting API.

Arguments	first, after, last, before
Total count	totalCount
How to read the next page	Send pageInfo.endCursor as after
When to stop	pageInfo.hasNextPage is false
List field	items (and edges)

query GetCustomersPage($first: Int, $after: String) {
  customers {
    customer(first: $first, after: $after) {
      totalCount
      pageInfo {
        hasNextPage
        endCursor
      }
      items {
        publicKey
        firstName
        lastName
      }
    }
  }
}

{
  "first": 30,
  "after": "<endCursor of the previous page>"
}

Fields that return a connection accept the cursor arguments. These are customer, products, streets, country, companies, orders, promotion, deliveryStreets and driverUsers.

Plain lists, such as customerCategories, locations or currencies, aren't paged. They return all items.

💡 TIP Use totalCount to show progress to your users (for example "30 of 309") instead of reading all pages first.

ℹ️ INFO orders also needs order keys or a period of at most 1 year.

Accounting API: PMS lists

The PMS lists use page paging, not cursors. They take a numeric cursor and a pageSize, and return cursor, pageSize, totalRecords and items.

documents.productPhysicalStocks and the reference lists (miscellaneous.organizations, locations, warehouses, payments, currencies) aren't paged. They return all items.