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
  • Intra Community Movements (ICM): Cross Border Movements data of ZFS products, used for Intrastat declarations
  • 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.

Intra Community Movements Report

ZFS may move inventory between Zalando warehouses due to relocation or replenishment of stock. You can track this stock movement using the Intra-Community Movements Report and file Intrastat declarations when necessary. Only partners who have agreed to fulfill orders from the whole supply network must file such declarations.

Shipped items are grouped by the day that they arrived at their destination.

To get all ZFS items that crossed borders and arrived at their destination, Which are reported within a specific date range for a merchant.

from & to query parameters refer to the reported date. This is the date when the movement was reported in the system. Transaction Date: Denotes the date when the item was inbounded at the designated destination.

/zfs/stock-movements/intra-community-movements/{merchant-id}?from=$FROM_DATE&to=$TO_DATE

For example, to get all relevant cross border movements that were reported in April 2020:

/zfs/stock-movements/intra-community-movements/{merchant-id}?from=2020-04-01&to=2020-04-30

The same call from httpie:

http GET \
https://api-sandbox.merchants.zalando.com/zfs\
/stock-movements/intra-community-movements/{merchant-id}\
?from=2020-04-01&to=2020-04-30 \
"Authorization:Bearer $YOUR_ACCESS_TOKEN"

Response: Successful

You will receive an HTTP 200 reply to a successful request. The following JSON reply example shows an Intra Community Movements report with only one item:

{
  "merchant_id": "246aabbc -beeb-45a7-99a3-6a8270887a74",
  "reports": [
    {
      "transaction_date": "2020-04-01",
      "movements": [
        {
          "product_sku": "AAA22O08A-A1100AS000",
          "ean": "2001231121234",
          "quantity": 1,
          "destination_stock_location": {
              "location_id": "b1aa94aa-104a-457a-a17a-a52aaa88aa3a",
              "name": "Gardno",
              "country_code": "PL"
          },
          "source_stock_location": {
              "location_id": "32aaa430-a835-44aa-947a-4a1aaaa1a615",
              "name": "Erfurt",
              "country_code": "DE"
          },
          "order_number": "20200401-erfurt-gardno",
          "movement_type": "customer_order_relocation"
        }
      ]
    }
  ]
}

Movement Types

  • Return Center Inbound
    Customer Returns via Return Centers which end in a location country different than origin.

  • Customer Return Inbound
    Customer Returns which arrive directly in a Warehouse location country different than origin.

  • Manual Relocation
    Movements cross border from Warehouse to Warehouse triggered manually.

  • Automatic Relocation
    Movements from Warehouse to Warehouse cross border triggered by algorithms to optimize availability in all markets.

  • Customer Order Relocation
    These are Movements which happen as part of customer order fulfillment. This movement type will also emit a correction once the item is finally shipped to the customer.

  • Customer Order Relocation Corrections
    Corrections are reported the same way like movements but with negative quantities. Please note that corrections can happen days later after the movement.
    No correction is reported when the customer order is cancelled and not fulfilled to the customer, but the item nevertheless was moved cross border and becomes available to the next customer.

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