Skip to main content

GET v3/stockLevels

GET 
/v3/stockLevels

List the stock levels of your products, with pagination.

Returns the various stockLevels of the product indicated by the id in the url. The GET v3/stockLevels endpoint will return up to 100 stockLevel resource at a time. Each stockLevel is related to a single product by its id and may contain multiple levels for each warehouse the product is located in.

Pagination​

The endpoint supports pagination to split the large collection of resources into smaller, more manageable chunks or pages. This helps to reduce the response size and to improve performance. The endpoint supports two forms of cursor-based pagination, both are explained below.

Iterating over all stock levels of all products​

By default the end-point will enable the user to iterate over all stock levels of all products in ascending order of id (product-id). To begin iterating start by making the following request: GET v3/stockLevels. It is possible to specify a page[size] to reduce the number of items returned from 100. To iterate, invoke the URL provided in the next parameter of the response. Each response will contain another next parameter pointing to the next 'page'. This process can be continued until the response either contains fewer stockLevel resources than requested using the page[size] parameter or there is no next paramter in the response to invoke.

Iterating over stock levels that changed on or after a certain point in time​

The end-point also supports iteration over the stock levels of products that have changed on or since a certain point in time. To start this iteration, invoke the endpoint using the filter filter[mutatedOn][gte]={timestamp}. The parameter page[size] can also be used in this case. For example GET v3/stockLevels?filter[mutatedOn][gte]=2023-07-28T11:25:00 will return the stockLevels of the first 100 skus that have changed since 11:25 on 2023-07-28. The response will also have a next parameter that will point to the next 'page' and by repeatedly invoking the next of each response will guarnatee that all stock levels changed since the prodivded timestamp are returned. The final response will contain fewer stockLevel resources than requested using the page[size] parameter or will have no next paramter to invoke at which point the product whose stock level was mutated latest has been returned. Note however that during this process, stock mutations may have occurred on products whose stock level was already returned in a previous response. The server will return these updated stock levels for those products again on more recent 'pages' (i.e. more towards the end of the iteration process) because these products now have a more recent mutatedOn value.

Filters​

The GET v3/stockLevels endpoint supports filtering on the following attributes: sku;\

Filtering on sku​

By specifying the product sku it is possible to look for stock of that product specifically. Be aware that the SKU's must be URL encoded to avoid being interpreted incorrecly. stockLevels for:

  • GET {host}/v3/stockLevels?filter[sku][in]=ABC,DEF will return the stockLevels for the products with sku ABC and DEF.
  • GET {host}/v3/stockLevels?filter[sku][in]=ABC%2CDEF will return the stockLevels for the product with sku ABC,DEF.

Filtering on mutatedOn​

By specifying a timestamp to the filter filter[mutatedOn][gte] it becomes possible to iterate over all stockLevels that have changed since that timestamp. (See the section above for a more detailed explanation of this process.) The filter on mutatedOn supports only the 'greater than or equal' comparitor: filter[mutatedOn][gte]={timestamp} and will cause the sorting of the response to adhere to sort=mutadedOn,id regardless what was provided or requested. The sort query paramter is implicitly set to mutatedOn,id when using this filter.

Note that the timestamp is considered to be in UTC

Ordering​

The endpoint has two orderings of the result sets, however this ordering cannot be specified by the user.

Limitations of GET v3/stockLevels​

  • At most 100 stockLevel resources are returned regardles of the value provided by the page[size] query parameter.
  • The id of the stockLevel is the same as the product.
  • Ordering of results:
    • By default or when using page[cursor], the ordering is set to sort=id. This is by id of the sku\\product and in ascending order to guarantee that each sku appears exactly once.
  • When using filter[mutatedOn][gte] the ordering is set to sort=mutatedOn,id. This ordering is fixed for this filter to guarantee that no stockLevels are omitted from the results when iterating over the set of stockLevels that changed since the provided timestamp.
  • filter[mutatedOn][gte] expectes a timestamp in UTC.
  • Users are rate-limited to 1000 requests per hour on this service.

Request​

Responses​

OK

Response Headers
    X-RateLimit-Limit

    The maximum number of requests per hour (see documentation for current limits)

    Example: 500