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": 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