Pagination

How paginated results work

When you fetch a collection of resources, you get paginated results. The response contains the record count and the page count, number, and size in the meta attribute and the URLs of the other pages in the links attribute.

{
  "data": [...],
  "meta": {
    "record_count": 140,
    "page_count": 14,
    "page_number": 1,
    "page_size": 10,
    "...": "..."
  },
  "links": {
    "first": "https://yourdomain.commercelayer.io/api/skus?page[number]=1&page[size]=10",
    "next": "https://yourdomain.commercelayer.io/api/skus?page[number]=2&page[size]=10",
    "last": "https://yourdomain.commercelayer.io/api/skus?page[number]=14&page[size]=10"
  }
}

On some high-volume collections (e.g. orders, SKUs, prices, customers, line items, stock items, gift cards, and order subscriptions), record_count and page_count become approximate once the result set is estimated to exceed 10,000 records. When this happens, the document-level meta includes a record_count_estimated attribute set to true — if it's absent, the counts are exact. Page contents stay exact either way.

The default page number is 1 (consequently, the link to the prev page is missing), and the default page size is 10. The maximum page size allowed is 25, but we recommend using a lower value unless strictly necessary. If you need to modify these default settings, use the page query parameter in your request.

If you need to gather information about large sets of resources for analytics/reporting purposes, please avoid making multiple paginated requests to the related resource endpoint. Use exports instead, which are a best fit for that. Alternatively, you can also perform a search query using our Metrics API (at the moment limited to orders, carts, and returns).

Example

Request

The following request fetches the SKUs, setting the page number to 3 and the page size to 5:

curl -g -X GET \
  'https://yourdomain.commercelayer.io/api/skus?page[size]=5&page[number]=3' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'

Response

On success, the API responds with a 200 OK status code, returning the five resource objects listed on the third page (from the 6th object to the 10th), together with the record and page counts and the links to the first, prev, next, and last page.

{
  "data": [
    {
      "id": "xYZkjABcde",
      "type": "skus",
      "links": {...},
      "attributes": {...},
      "relationships": {...},
      "meta": {...}
    },
                  {
      "id": "yzkWXfgHQS",
      "type": "skus",
      "links": {...},
      "attributes": {...},
      "relationships": {...},
      "meta": {...}   
    },
    {
      "id": "aBmNkPQRst",
      "type": "skus",
      "links": {...},
      "attributes": {...},
      "relationships": {...},
      "meta": {...}
    },
    {
      "id": "WAspXYhfCV",
      "type": "skus",
      "links": {...},
      "attributes": {...},
      "relationships": {...},
      "meta": {...}
    },
    {
      "id": "QWERtyUpBa",
      "type": "skus",
      "links": {...},
      "attributes": {...},
      "relationships": {...},
      "meta": {...}
    }       
  ],
  "meta": {
    "record_count": 140,
    "page_count": 28,
    "page_number": 3,
    "page_size": 5,
    "mode": "test",
    "organization_id": "QKpXnYvZeB",
    "trace_id": "8c5f3a9e1d7b4c2f8a6e0d5b9c3f7a1e4d8b6c0f2a5e9d3b7c1f5a8e2d6b4c9f"
  },
  "links": {
    "first": "https://yourdomain.commercelayer.io/api/skus?page[number]=1&page[size]=5",
    "prev": "https://yourdomain.commercelayer.io/api/skus?page[number]=2&page[size]=5",
    "next": "https://yourdomain.commercelayer.io/api/skus?page[number]=4&page[size]=5",
    "last": "https://yourdomain.commercelayer.io/api/skus?page[number]=28&page[size]=5"
  }
}

The example query parameters above use unencoded [ and ] characters simply for readability. In practice, these characters must be percent-encoded, per the requirements in RFC 3986.

Event stores use a slightly different pagination method based on a cursor instead of the page number (learn more here).