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 is 100 days. 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 receive 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/received-items/{merchant_ID}?from=$FROM_DATE&to=$TO_DATE

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

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

The same call using httpie:

http GET \
https://api-sandbox.merchants.zalando.com/zfs\
/stock-movements/received-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 received item:

{
  "received_items": [
    {
      "zalando_advice_id": 99200001,
      "merchant_b2b_reference": "reference",
      "ean": "0191476239145",
      "parent": {
        "id": "string"
      },
      "quality_label": "00014D02W8V",
      "location_id": "29809185-6a98-4691-a15b-e8d16839b6e8",
      "received_timestamp": "2017-07-21T17:32:28Z",
      "consumed_timestamp": "2017-07-21T17:32:28Z",
      "tour_number": "20181031-0015-SWI1-EF"
    }
  ]
}

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": {
        "id": "3"
      },
      "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",
      "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 (Collo number)

In the example payload above the Box id is being returned as an id of the parent attribute and is equal to "3". For old items the Box id is "null".

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