Skip to main content

Stock Level Synchronization

Paxon is leading for the stock of your products. The stock in the warehouses changes when inbounds are received, orders are shipped, returns are processed, and stock is corrected. Use GET v3/stockLevels to keep the stock in your application, such as a webshop or ERP, up to date.

The endpoint returns a stockLevel for each product, with its stock levels per warehouse. The Stock Levels article explains what each level means. The products themselves must be known to Paxon first; see Product Synchronization.

All examples below leave out the Authorization header, which is required on every request. See Authenticating.

Iterating over stock levels​

The endpoint uses cursor-based pagination and returns at most 100 stock levels per page. It can iterate in two ways:

  • All stock levels, ordered by product id. Use this for the initial synchronization, or an occasional full check.
  • Stock levels changed on or after a point in time, ordered by the time of the change. Use this for the regular synchronization.

In both cases, request the next link of each response to get the following page, and repeat this until a page contains fewer stock levels than the page[size], or has no next link. Use the links as they are, and don't build the cursor yourself:

let url = `${host}/v3/stockLevels?page[size]=100`;
while (url) {
  const page = await get(url);
  for (const stockLevel of page.data) {
    // Update the stock of the product in your application
  }
  url = page.data.length < 100 ? null : page.links?.next;
}

Initial synchronization​

Retrieve the stock levels of all products, starting with the first page:

GET {host}/v3/stockLevels?page[size]=100 HTTP/1.1
Accept: application/json

The response contains the stock levels and a next link to the following page:

{
  "data": [
    {
      "id": 540935,
      "type": "stockLevel",
      "attributes": {
        "sku": "VDB-400",
        "levels": [
          {
            "warehouse": "NR",
            "physical": 120,
            "economic": 95,
            "available": 88,
            "free": 88
          }
        ]
      }
    }
  ],
  "links": {
    "self": "https://shopapi.activeants.nl/v3/stockLevels?page[size]=100",
    "next": "https://shopapi.activeants.nl/v3/stockLevels?page[cursor]=540936&page[size]=100"
  }
}

The example is shortened; each level has more stock levels, described in GET v3/stockLevels.

To use a stock level:

  • The id of a stockLevel is the id of its product, and sku is the SKU of the product.
  • Use the level set in the stockLevelType of the product: economic for ECONOMIC, or available for AVAILABLE.
  • When your products are stored in more than one warehouse, levels contains an entry per warehouse.

Regular synchronization​

After the initial synchronization, only retrieve the stock levels that changed since your previous run, using filter[mutatedOn][gte]:

GET {host}/v3/stockLevels?filter[mutatedOn][gte]=2026-10-29T08:00:00&page[size]=100 HTTP/1.1
Accept: application/json

Follow the next links until a page contains fewer stock levels than the page[size], or has no next link. Then you've received every stock level that changed since the timestamp.

Keep the following in mind:

  • The timestamp is in UTC.
  • Note the time just before you start a run, and use it as the timestamp of the next run. Changes made during a run are then picked up by the next one.
  • A product whose stock changes again during a run can be returned more than once. The last one returned is the most recent, so simply overwrite the stock in your application.
  • Run the synchronization at an interval instead of continuously.

Stock of specific products​

To get the current stock levels of specific products, for example to check a product before it's ordered, filter on sku. The filter accepts several comma-separated SKUs, each of which must be URL encoded:

GET {host}/v3/stockLevels?filter[sku][in]=VDB-400,TSH-000-S HTTP/1.1
Accept: application/json

Rate limits​

The endpoint is rate limited, and exceeding the limit results in 429 Too Many Requests. The current limit is listed with the endpoint: GET v3/stockLevels. To stay within the limit:

  • Use filter[mutatedOn][gte] for the regular synchronization, instead of retrieving all stock levels every time.
  • Use the maximum page[size] of 100, so you need fewer requests.
  • Retrieve the stock of specific products in batches with filter[sku][in], instead of one request per product.