Tracking Inventory

Use the Item Quantities API to track stock levels at Zalando warehouses.

You may use the Item Quantities API to:

  • Get quantities of items at Zalando Warehouses, and
  • Get a snapshot of stock levels for all EANs with non-zero stock from all locations. Data may be up to 24 hours old.

Inventory definitions

Offerable quantity: The quantity of items of a product on the shelf that are either available or reserved for fulfillment, per Zalando Warehouse. Once an item is picked from the shelf, it is no longer included in the offerable quantity amount.

Note that an item may be present in offerable stock, but still not sellable in a specific sales channel, because of the product's creation status. This may also apply to a specific country where customs data is missing, such as Switzerland.

Non-offerable quantity: The quantity of items of a product that are not on the shelf, per warehouse. This includes, for example, items that are in the process of delivery to customers (such as picking or packing), or items currently in transit to another Zalando Warehouse.

Authentication

The zDirect API requires OAuth 2.0 authentication for all API calls. Use the Authentication API to generate access tokens as described in the Authentication section.

Getting Item Quantities

You may get item quantities either for specified EANs or for a specified time range for a merchant.

Get Quantity for specific EANs

To request item quantities for specific EANs for a merchant:

GET /zfs/item-quantities/{merchant_ID}?eans=EAN1,EAN2...

Using httpie, this call would look like this:

http GET \
https://api-sandbox.merchants.zalando.com/zfs\
/item-quantities/{merchant_ID}?eans=EAN1,EAN2... \
"Authorization:Bearer $YOUR_ACCESS_TOKEN"

Get Quantity by Time Range

You may also request item quantities for all EANs whose stock levels have changed during the period between a specified time and the present, with a maximum length of 24 hours.

For example, if it is 18:30 pm on Feb 27, 2020, you may request stock levels for all EANs that have been updated within the last 24 hours with the following call:

GET /zfs/item-quantities/{merchant_ID}?from=2020-02-26T18:30:00Z

Times must be specified using the RFC 3339 format.

Response: Successful

You will receive an HTTP 200 reply to a successful request.

{
  "item_quantities": [
    {
      "ean": "string",
      "total_quantity": 3,
      "quantities_by_state": {
        "offerable": 1,
        "non_offerable": 2
      },
      "quantities_by_location": {
        "stock_location_id": "string",
        "quantities_by_state": {
          "offerable": 1,
          "non_offerable": 2
        }
      }
    }
  ]
}

Quantities by Location

For all calls, you may set the by_location parameter to true to include the location of each item with the returned data, as in this example:

GET zfs/item-quantities/{merchant_ID}?eans=$EAN&by_locations=true

You will receive an HTTP 200 reply to a successful request. The item location is returned in the quantities_by_location field as a Stock Location ID, as shown in this sample reply:

{
  "item_quantities": [
    {
      "ean": "0888462064101",
      "total_quantity": 12,
      "quantities_by_state": {
        "offerable": 10,
        "non_offerable": 2
      },
      "quantities_by_location": [
        {
          "stock_location_id": "1e57b2b6-907b-4676-8766-339a1d596e59",
          "quantities_by_state": {
            "offerable": 10,
            "non_offerable": 2
          }
        }
      ]
    }
  ]
}

If you have stock for an EAN in multiple locations, the request will return multiple quantities_by_location fields. Note that you may see multiple stock locations returned, but you will not see any stock location where the current quantity for the EAN is 0.

Getting Quantity Snapshots

Quantity snapshots provide a point-in-time itemization of all items in all locations for a merchant. The reported stock levels will be no more than 24 hours old.

Snapshots only include data for EANs that have a current quantity greater than zero. Note that if you request quantities by location, you may see multiple stock locations returned, but you will not see any stock location where the current quantity for the EAN is 0.

GET /zfs/item-quantity-snapshots/{merchant-id}
In order to resolve stock locations, Location API is used. Stock locations are divided into Fulfillment Center, Inbound Distribution Center(IDC) or Return Center. All results for locations that belongs to Return Center are being aggregated under one Return Center location with id 7d096a39-b730-4b9e-8bec-43cbf3348233.

Tip

The returned data may exceed several megabytes. You may wish to specify Accept-encoding: gzip in your request header.

The following httpie call will return a snapshot:

http GET \
https://api-sandbox.merchants.zalando.com/zfs\
/item-quantity-snapshots/{merchant-id} \
'Authorization:Bearer $YOUR_ACCESS_TOKEN'
To request a snapshot for a specific date, snapshot date parameter can be provided as below:

http GET \
https://api-sandbox.merchants.zalando.com/zfs\
/item-quantity-snapshots/{merchant-id}?snapshot_date=2023-03-03 \
'Authorization:Bearer $YOUR_ACCESS_TOKEN'
In this case instead of returning the latest snapshot, snapshot for the specified date would be returned. You will receive an HTTP 200 reply to a successful request. The JSON reply body will look like this example, but it may be much larger:

Response: Successful

{
  "item_quantity_snapshot": {
    "item_quantities": [
      {
        "ean": "string",
        "total_quantity": 12,
        "quantities_by_state": {
          "offerable": 4,
          "non_offerable": 8
        },
        "quantities_by_location": [
          {
            "stock_location_id": "afb34b1f-da40-4d13-b4e7-7cce9e8b9f87",
            "quantities_by_state": {
              "offerable": 4,
              "non_offerable": 8
            }
          }
        ]
      }
    ]
  },
  "created": "2017-07-21T17:32:28Z"
}

Error Codes

An unsuccessful query will return an HTTP 400 code with additional information.

For example, the following reply indicates that a bad EAN was provided:

{
  "status": 400,
  "detail": "Query parameter(eans): non valid ean format"
}

Creating a Real Time View Of Stocks

If you want to get latest stock quantities, you might use /zfs/item-quantities/ endpoint to get the latest quantities of all EANs.

But given that the endpoint could only accept 50 EANs per call, this approach might not be efficient with consumers who have big number of items. Also, you might get 429 errors due to exceeding the rate limit.

So there is a simplified way to achieve this using two steps process as follows:

1- Get current day snapshot using quantity snapshots endpoint:

This gives you the stock data as of start of the day

GET /zfs/item-quantity-snapshots/{merchant-id}

2- Get item quantities for all EANs whose stock levels have changed during the period between snapshot time and the present: Snapshot time can be taken from the snapshot response with the created timestamp. Use this in calling for getting all updated stock data

GET /zfs/item-quantities/{merchant-id}?from=<SNAPSHOT_TIME>

Notes:

  • Snapshots are created at midnight (CEST) every day, so SNAPSHOT_TIME should be time at midnight.
  • Snapshot time must be specified using the RFC 3339 format.

Additional Resources

Contact Support