Skip to main content

GET v3/stockmutations

GET 
/v3/stockMutations

List stock mutations, oldest first, with filters and pagination.

This endpoint allows you to retrieve a list of up to 100 stock mutations at a time, sorted in ascending order by the createdOn attribute. However, this endpoint will only return stock mutations that are less than 7 days old¹. Note that any stock mutations related to shipments or damaged eturns cannot be accessed through this endpoint. Instead, mutations related to shipments must be inferred from the GET v3/shipments endpoint.

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 both cursor-based and number-based techniques for pagination, but it is recommended to use cursor-based as this is more performant and reliable due to page-shifting.

Filters​

The GET v3/stockmutations endpoint supports filtering on the following attributes: createdOn, type and synced. Each of these are explained below. Filters can be used in combination with eachother and with pagination as to allow full access to the desired subset of stockmutations.

Filtering on createdOn​

The results returned by this service can be filtered based on the creation date of the stockmutation. To do so make use of the filter[createdOn] parameter in the following manner:

  • GET {host}/v3/stockmutations?filter[createdOn][lt]={date} will return stockmutations that have been created before the provided date. Stockmutations that have been created on that date are not included in the results.
  • GET {host}/v3/stockmutations?filter[createdOn][gt]={date} will return stockmutations that have been created after the provided date. Stockmutations that were created on that date are not included in the results.
  • GET {host}/v3/stockmutations?filter[createdOn][gt]={date_1}&filter[createdOn][lt]={date_2} will return stockmutations that have created between dates {date_1} and {date_1}. Stockmutations that were created on either date are not included in the results.

Filtering on type​

The endpoint allows filtering on one or more stockmutationType values. To filter on stockmutationType use the filter[type] query parameter as follows:

  • GET {host}/v3/stockmutations?filter[type][in]=RETURN will return all stockmutations that relate to a RETURN.
  • GET {host}/v3/stockmutations?filter[type][in]=RETURN,PRODUCTION will return all stockmutations that belong to RETURN or PRODUCTION.

Filtering on synced (obsolete)​

To support legacy stockmutation synchronization, the endpoint allows users to request unsynced or synced stockmutations. Internally a stockmutation is marked as unsynced whenever it is created. To fetch the stockmutations that require synchronization invoke the endpoint as follows:

  • GET {host}/v3/stockmutations?filter[synced]=false will return all stockmutations that have changed since last time these were 'synchronized'. To mark them as synced use the old v2 endpoint.

Example invocations​

  • GET {host}/v3/stockmutations Returns the 100 oldest stockmutations up to 7 days back. Note that the service has a limit of 7 days. This invokation is equivalent to GET {host}/v3/stockmutations?page[size]=100&page[cursor]=0 and GET {host}/v3/stockmutations?page[size]=100&page[number]=1
  • GET {host}/v3/stockmutations?filter[createdOn][gt]=2023-01-01 Returns up to 100 stockmutations that were created after 2023-01-01. The stockmutations returned are never older than 7 days, regardless of the date provided in the request.
  • GET {host}/v3/stockmutations?filter[type][in]=INBOUND,PRODUCTION Returns only stockmutations that are related to inbounds or productions
  • GET {host}/v3/stockmutations?filter[synced]=false Returns all stockmutations that haven't been synchronized. This corresponds to the old way of synchronizing information. Note that this feature will be removed when stockmutation WebHooks become available.

Limitations of the GET v3/stockmutations​

  • No stockmutation older than 7 days¹ are returned.
  • At most 100 stockmutation resources are returned per request, regardless of the value provided in the page[size] query parameter.
  • Ordering is by id of the stockmutation in ascending order.
  • Users are rate-limited to 1000 requests per hour on this service.

Request​

Responses​

OK