Pagination

Pagination is essential for working with larger data sets, where it is not feasible to fetch all data in a single call.

All top-level API resources, which return a list of items, always return pagination information in the response. Whether pagination on the request is also supported can be found on each endpoint. If you go over the available items with your pagination, the APIs will return empty responses.

The Storefront API offers three ways to perform pagination:

The /v1/products endpoint is limited to a maximum result window of 500,000 items. For that reason and for improved performance, use product-ID-based pagination to extract large product sets.

Page-based Pagination

All endpoints use the page-based pagination by default, if you don't specify otherwise in the request.

Parameter Details

Parameter	Details
`page`	The page you want to retrieve items for. Type: Integer Default: 1
`perPage`	How many items you want to retrieve per page. This parameter should stay the same between requests to avoid duplicates or missing items. When requesting products, use a `perPage` value of at most 250, or at most 100 when including siblings. Type: Integer Default: 100

page

The page you want to retrieve items for.

Type: Integer
Default: 1

perPage

How many items you want to retrieve per page.

This parameter should stay the same between requests to avoid duplicates or missing items.

When requesting products, use a perPage value of at most 250, or at most 100 when including siblings.

Type: Integer
Default: 100

Response Field	Details
`current`	The current amount of items returned to you. In most cases, this will be equal to the `perPage` parameter unless we don't have more items to be returned. For example, if you request the last page and we only have 10 products left to be returned, then the value will be 10. Type: Integer
`total`	The total amount of items which can be retrieved. Type: Integer
`perPage`	The `perPage` parameter which was provided in the request. Type: Integer
`page`	The `page` parameter which was passed in the request. Type: Integer
`first`	The first page which will always be 1. Type: Integer
`prev`	The previous page that you can request. If you are on the first page, the value will be 1. Type: Integer
`next`	The next page to be requested. If you are on the last page, this will be the same value as the 'page' response field. Type: Integer
`last`	The last page that you can request. Type: Integer

Offset-based Pagination

Offset-based pagination allows you to be more flexible with your requests, as the amount of items you retrieve per call can be varied.

The offset parameter should match the number of items retrieved in previous requests. You can adjust the limit parameter as needed while iterating through the data.

Parameter	Details
`limit`	The `limit` parameter specifies the maximum number of results to be returned. Type: Integer Default: 100
`offset`	The `offset` parameter specifies the position from which to start returning items. It should represent the total number of items retrieved in previous requests. Example: When retrieving products in chunks of 50, increment the offset by 50 after each iteration. Type: Integer Default: 0

Response Field	Details
`total`	The total number of items for this resource. Once your `offset` parameter is bigger than the total amount of items, you have reached the end of your data. Type: Integer

Product-ID-based Pagination

Product-ID-based pagination is only available on the /v1/products endpoint. Use it whenever you want to iterate over large amounts of products, for example for an export or a script that processes all products of a shop.

Instead of requesting pages, you use the product ID of the last item you received as a cursor for the next request. This is far more performant than page-based or offset-based pagination for large data sets, and it is not affected by the maximum result window of 500,000 items the /v1/products endpoint is otherwise limited by.

Parameter Details

Parameter	Details
`minProductId`	Only products with an ID greater than or equal to this value are returned. Type: Integer Default: none
`perPage`	How many items you want to retrieve per page. This parameter should stay the same between requests to avoid duplicates or missing items. When requesting products, use a `perPage` value of at most 250, or at most 100 when including siblings. Type: Integer Default: 100

minProductId

Only products with an ID greater than or equal to this value are returned.

Type: Integer
Default: none

perPage

How many items you want to retrieve per page.

This parameter should stay the same between requests to avoid duplicates or missing items.

When requesting products, use a perPage value of at most 250, or at most 100 when including siblings.

Type: Integer
Default: 100

To iterate over all products:

Start with an initial request using minProductId=0.
Take the ID of the last product in the response and use that ID + 1 as the minProductId of the next request.
Repeat until a request returns an empty list of products. You have now retrieved all available products of the shop.