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 /item-quantity-snapshots/{merchant-id}

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'

Response: Successful

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:

{
  "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"
}

Additional Resources

Contact Support