Tracking Stock Movements

Use the Stock Movements API to track:

  • Inbound receive process : your goods shipped to Zalando
  • Outbound return process: goods we return to you at your request
  • Liquidation Data: Your goods liquidated to Zalando offprice channel on your request

Note

The retention time for data in this service except received items ednpoint is 100 days. For received items endpoint it is full previous year + current year. After that, data may be deleted without notice.

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.

Inbound Receive Process

This call returns all items that have completed the receiving process at a Zalando Warehouse for a merchant within a specified time frame. Note that this operation does not include quarantined inventory.

GET /zfs/stock-movements/reports/received-items/{merchant-ID}?from=$FROM_DATE&to=$TO_DATE&zalando_advice_ids=$ZALANDO_ADVICE_IDS&cursor=$CURSOR&limit=$LIMIT

For example, the following call gets all items received at Zalando Warehouses between 9:00 am on Feb. 25, 2025 and 6:00 pm on Feb. 26, 2025:

GET /zfs/stock-movements/reports/received-items/{merchant-ID}?from=2025-02-25T09:00:00Z&to=2025-02-26T18:00:00Z

The same call using httpie:

http GET \
https://api-sandbox.merchants.zalando.com/zfs\
/stock-movements/reports/received-items/{merchant_ID}\
?from=2025-02-25T09:00:00Z&to=2025-02-26T18:00:00Z \
"Authorization:Bearer $YOUR_ACCESS_TOKEN"

There is a possibility to filter out received items by zalando_advice_ids. For example:

GET /zfs/stock-movements/reports/received-items/{merchant-ID}?from=2025-02-25T09:00:00Z&to=2025-02-26T18:00:00Z&zalando_advice_ids=99200001,99200002

More information about available query parameters can be found in the Open API reference.

Times must be specified using the RFC 3339 format.

Response: Successful

You will receive an HTTP 200 reply to a successful request. The following JSON reply example shows a response with the two received items:

{
  "received_items": [
    {
      "zalando_advice_id": "99200001",
      "ean": "0191476239145",
      "quality_label": "00014D02W8V",
      "merchant_article_id": "0123456789",
      "merchant_item_id": "012345678910",
      "merchant_b2b_reference": "reference",
      "location_id": "29809185-6a98-4691-a15b-e8d16839b6e8",
      "received_timestamp": "2025-02-25T17:32:28Z"
    },
    {
      "zalando_advice_id": "99200002",
      "ean": "0191476239146",
      "quality_label": "00014D02W8G",
      "merchant_article_id": "0123456789",
      "merchant_item_id": "",
      "merchant_b2b_reference": "reference",
      "location_id": "29809185-6a98-4691-a15b-e8d16839b6e8",
      "received_timestamp": "2025-02-26T17:32:28Z"
    }
  ],
  "next": ""
}

Outbound Return Process

The following call returns all items that have been shipped from Zalando Warehouses to you at your request for a specified merchant within a specified time range:

GET /zfs/stock-movements/returned-items/{merchant_ID}?from=$FROM_DATE&to=$TO_DATE

For example, the following call gets all returned items between 9:00 am on Feb. 25, 2020 and 6:00 pm on Feb. 26, 2020:

GET /zfs/stock-movements/returned-items/{merchant_ID}?from=2020-02-25T09:00:00Z&to=2020-02-26T18:00:00Z

The same call from httpie:

http GET \
https://api-sandbox.merchants.zalando.com/zfs\
/stock-movements/returned-items/{merchant_ID}\
?from=2020-02-25T09:00:00Z&to=2020-02-26T18:00:00Z \
"Authorization:Bearer $YOUR_ACCESS_TOKEN"

Times must be specified using the RFC 3339 format.

Response: Successful

You will receive an HTTP 200 reply to a successful request. The following JSON reply example shows a response with a single returned item:

{
  "returned_items": [
    {
      "merchant_b2b_reference": "reference",
      "ean": "0191476239145",
      "parent": null,
      "quality_label": "00014D02W8V",
      "location_id": "29809185-6a98-4691-a15b-e8d16839b6e8",
      "shipped_timestamp": "2017-07-21T17:32:28Z",
      "consumed_timestamp": "2017-07-21T17:32:28Z",
      "zalando_shipment_number": "1234567890123456",
      "sscc": "00040552761167371658",
      "destination": {
        "city": "string",
        "country_code": "string",
        "first_name": "string",
        "last_name": "string",
        "salutation": "string",
        "street": "string",
        "zip": "string"
      },
      "quality_category": "A",
      "defect_levels": {
        "level_1": "optional defect description",
        "level_2": "optional defect description"
      }
    }
  ]
}

Retrieving the Box id

The Box ID is no longer returned as the id of the parent attribute. Instead, it has been replaced by (SSCC), which provides a more accurate and unique identifier for each shipping unit.

The parent attribute will always be null for backward compatibility.

Best Practices for Inbound and Outbound Return Process

We recommend that you:

  • Use fetch intervals between 15 and 60 minutes long so you receive regular updates and your data sets are not too big.
  • Request overlapping time frames to be sure there are no gaps. If you do so, we recommend using the unique quality_label field as an item identifier to be sure that you do not consume any item more than once.

Liquidation Data

This call returns all items that have been liquidated for a merchant within a specified time frame.

GET /zfs/stock-movements/liquidated-items/{merchant_ID}?from=$FROM_DATE&to=$TO_DATE&purchase_order_number=$PURCHASE_ORDER_NUMBER
Note that>> * Purchase Order Number is optional. * In exceptional scenarios such as system lags or integration delays, there is a possibility that From & To dates may not fecth 100% items which were liquidated in that duration. In such cases, we request you to retry the report in next 48 hours.

GET /zfs/stock-movements/liquidated-items/{merchant_ID}?from=2020-02-25&to=2020-02-26

The same call using httpie:

http GET \
https://api-sandbox.merchants.zalando.com/zfs\
/stock-movements/liquidated-items/{merchant_ID}\
?from=2020-02-25&to=2020-02-26 \
"Authorization:Bearer $YOUR_ACCESS_TOKEN"

Response: Successful

You will receive an HTTP 200 reply to a successful request. The following JSON reply example shows a response with a single received item:

{
  "received_items": [
    {
      "merchant_id": "899561ce-e76e-11ea-b770-5ff9afbbecdd",
      "purchase_order_number": "PO123",
      "shipping_notice_number": "cd0424c2-e76e-11ea-b8d9-df7a5c43dac0",
      "ean": "0191476239145",
      "sku_simple": "TH341G023-K1100XL000",
      "quantity": "40",
      "stock_location_id": "fd10a17c-e76e-11ea-935d-53ca727cc5e7",
      "liquidation_date": "2020-02-19",
      "reporting_date": "2020-02-25"
    }
  ]
}

Error Handling

If you receive a non-200 error response, try re-fetching after two minutes or more.

Additional Resources

Contact Support