Cross-Border Movements

The Cross-Border Movements API provides information about cross-border movements of stock within the Zalando logistics network to users of Zalando's International Warehousing.

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.

Details

The Cross-Border Movements API provides data on cross-border movements of items between Zalando logistics facilities to users of International Warehousing. If you have enabled International Warehousing, and if an item is moved from a Zalando logistics facility in one country to a Zalando logistics facility in another country, that movement will be captured in the reports that can be fetched from this endpoint.

Each day, a report is generated that captures all of your cross-border movements recorded on the previous day; when you call the cross-border movements endpoint, you are fetching the data contained in these reports. This API endpoint allows you to request data for a specified date range. The date range refers to the report_date in the response, which describes when the transaction was recorded as a cross-border movement. The reports contain one line per moved item and the response is paginated.

/zfs/cross-border-movements/{merchant-id}?from=$FROM_DATE&to=$TO_DATE

For example, to get all relevant cross border movements that were reported in March 2025:

/zfs/cross-border-movements/{merchant-id}?from=2025-03-01&to=2025-03-31

The same call from httpie:

http GET \
https://api-sandbox.merchants.zalando.com/zfs\
/cross-border-movements/{merchant-id}\
?from=2025-03-01&to=2025-03-31 \
"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 Cross Border Movements report with only one item and a cursor to the next page:

{
  "merchant_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX",
  "items": [
    {
      "movement_id": "00000000-0000-0000-0000-000000000000",
      "report_date": "2024-11-20",
      "transaction_date": "2024-11-20",
      "product_sku": "XXXXXXXXX-XXXXXXXXX",
      "ean": "000000000000",
      "merchant_sku": "XXXXXXX",
      "movement_type": "relocation_inbound",
      "source_stock_location": {
        "location_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX",
        "name": "Szczecin",
        "country_code": "PL",
        "inbound_active": true,
        "outbound_active": true
      },
      "destination_stock_location": {
        "location_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX",
        "name": "Mönchengladbach",
        "country_code": "DE",
        "inbound_active": true,
        "outbound_active": true
      },
      "order_id": "YYYYYYYY"
    }
  ],
  "next": "eyJtb3ZlbWVudF9pZCI6IjAwMDAwMWUzLWE0M2ItNGM0Ni1hZTk5LWRmNDgyZmVmMTY5ZSJ9",
  "query": {
    "from": "2024-11-20",
    "to": "2024-11-20"
  }
}

Movement Types

  • Relocation Inbound
    Movements from a ZEOS facility in one country to a ZEOS facility in another. This can happen for a variety of reasons, including: stock replenishment to optimise article availability, fulfilment of customer orders that require package consolidation in a single location before shipment to customers, and merchant requests to move items to a particular location for pickup.

  • Customer Return Inbound
    An item returned by a customer that arrived at a ZEOS facility in a different country than the ZEOS facility from which the item was shipped to the customer. The source country of the movement will be the country from which it was shipped to the customer.

  • External Treatment Inbound
    An item that underwent external treatment (for example, refurbishment) and arrived at a ZEOS facility in a different country than the last ZEOS facility where it was located.

  • Reconciliation Inbound
    An item that was unexpectedly received in a ZEOS facility in a different country than its last known location in the ZEOS network. This can happen due to operational errors, for example, missed scan on outbound from the previous location.

Error Handling

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

Additional Resources

Contact Support