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

Order Id Availability

The field order_id is only available for movements recorded since June 1st 2025. Data requested prior to this date will return null for this field.

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.

⚠️ Possible issues and Error Handling

All non-200 error responses follow the standard format below:

{
  "detail": "<error details as string>",
  "status": <response status code as number>,
  "title": "<error title as string>",
  "type": "<a link to the rfc, i.e. https://tools.ietf.org/html/rfc7231#section-6.5.1 for 400>"
}

400 Bad Request: Regular Bad Request

Description: This is a standard HTTP 400 response for invalid request input, such as submitting a from parameter that is chronologically after to, or providing other malformed parameters.
Recommended Action: No retry. The request parameters must be corrected before attempting again.

400 Bad Request: Requested data is archived

Description: This error occurs when the requested date range is too far in the past (typically exceeding two years) and the data has been archived.
Detail Example: The data before YYYY-MM-DD has been archived and is no longer available for reporting.
Recommended Action: No retry. Adjust your request to query data only after the date specified in the detail message.

403 Forbidden: Merchant is not ICT enabled

Description: The merchant identifier provided is not, or was not, enabled for the ICT service during the requested period.
Detail Examples:

  • Merchant has never been enabled.
  • Merchant is ICT enabled only since 2025-10-11 (requested from 2025-10-10)
  • Merchant was ICT enabled up to 2025-10-15 (requested to 2025-10-17)

Recommended Action: No retry. The request is fundamentally invalid for this merchant or time range.

503 Service Unavailable: Data are missing for some dates in the request. Missing dates are listed in the detail property. Try again later

Description: Data is currently missing or incomplete for specific dates due to a temporary processing issue on the server.
Detail Example: A comma-separated string of missing dates, e.g., "2025-11-01,2025-11-02".
Recommended Action: Retry later. This issue is typically transient. Try re-fetching in a few hours.

Any other non-200 errors

Description: For any other non-200 error response not explicitly listed above.
Recommended Action: Retry later. Try re-fetching after two minutes or more.

Additional Resources

Contact Support