Introducing our brand new Rules Engine —
Read the docs
LogoLogo
Core APIOther APIsChangelog
Getting started
Getting started
  • Welcome to Commerce Layer
    • Guided setup
    • Manual configuration
  • API specification
  • API credentials
  • Authentication
    • Client credentials
    • Password
    • Authorization code
    • Refresh token
    • JWT bearer
    • Revoking a token
  • Roles and permissions
  • Fetching resources
  • Fetching relationships
  • Including associations
  • Sparse fieldsets
  • Sorting results
  • Pagination
  • Filtering data
  • Creating resources
  • Updating resources
  • Tagging resources
  • Deleting resources
  • Importing resources
  • Exporting resources
  • Cleaning up resources
  • External resources
    • External order validation
    • External prices
    • External shipping costs
    • External payment gateways
    • External promotions
    • External tax calculators
  • Rate limits
  • Handling errors
  • Real-time webhooks
  • Callbacks security
On this page

Pagination

How paginated results work

PreviousSorting resultsNextFiltering data

Last updated 10 months ago

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

{
  "data": [...],
  "meta": {
    "record_count": 140,
    "page_count": 14
  },
  "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"
  }
}

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 instead, which are a best fit for that. Alternatively, you can also perform a using our (at the moment limited to , , and ).

Example

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'

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
  },
  "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
exports
Metrics API
search query
orders
carts
returns