Pagination
Paginaiton 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 returns pagination information as well 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 to ways to perform pagination:
Page-based Pagination
The page-based pagination is used by default if you won't specify otherwise in the request for all endpoints.
| 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 duplicate or missing items. Type: Integer |
| 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.
|
| 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.
|
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 just needs to match how many items you previously retrieved and then you can change the limit parameter while iterating through your data.
| Parameter | Details |
|---|---|
| limit | The limit parameter specifies the maximum number of results to be returned. Type: Integer Default: 100 |
| offset | The offset parameter defines from which item position we should return items. This should be the total number of items you previously retrieved. Example: When requesting all of your products in chunks of 50, on every iteration you should increment your offset by 50 until you reach the end. 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 |
