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
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
- Stock Movements API Reference: Information on scopes, rate limiting, and sandbox behavior, and an OpenAPI reference for the Item Quantities API.