Exporting Orders

Once we set the Order Status to approved, you must declare to Zalando that you are taking responsibility for the order by exporting it. This step is required for orders having the order type PartnerFulfilled.

To export an order, assign it a merchant_order_id. When you assign a Merchant Order ID to an order, we will set the value of exported to true.

You may also update the Merchant Order ID while the Order Status is still initial(before approval). Zalando expects to receive a Merchant Order ID at the latest within 3 hours after an order was approved. For more information, see Best practices for Exporting Orders below.

We recommend using a value from your order tracking system for the Merchant Order ID, but you may use any value you wish, as long as it is alphanumeric. It does not have to be unique.

Endpoint to export orders

Use the following endpoint to add the merchant_order_id:

PATCH merchants/{merchant_ID}/orders/{order_ID}
You need to provide a JSON payload containing the merchant_order_id similar to the below example:

{
  "data":{
    "type":"Order",
    "id":"$YOUR_ORDER_ID",
    "attributes":{
      "merchant_order_id":"$YOUR_MERCHANT_ORDER_ID"
    }
  }
}

The above endpoint is an HTTP PATCH method to update the order, which updates only part of a data set. You therefore do not need to provide any more information about the order. Only the merchant_order_id value will be modified.

This example httpie call takes the local file confirm-order-export.json as input for the PATCH request:

http PATCH \
https://api-sandbox.merchants.zalando.com\
/merchants/{merchant_ID}/orders/{order_ID} \
Accept:application/vnd.api+json \
Content-Type:application/vnd.api+json \
"Authorization:Bearer $YOUR_ACCESS_TOKEN" \
< confirm-order-export.json

Note

  1. Exporting orders is only supported for non-ZFS orders. ZFS orders are read-only and hence do not require this step.
  2. Value provided for merchant_order_id field should be alphanumeric and non-empty.

Response Codes

HTTP Code Description
204 Order was successfully patched.
400 Error in JSON payload.
403 You do not have authority to patch this order.

For a full list of response codes, see the Orders API OpenAPI Reference.

Best practices for exporting Orders

We recommend the below steps in order to ensure you have visibility over the orders pending for export by you. You can do so by following the below steps:

1. Fetching the orders for export

Fetch the orders pending for export. The simplest query params would be 

GET /merchants/{merchant_id}/orders?sales_channel_id={sales_channel_id}&exported=false&page[size]=1000&include=order_items,order_lines

Note

  • Replace the merchant_id and sales_channel_id with yours.
  • We recommend that you call this endpoint frequently starting with once every 5 minutes depending on the rate with which you receive orders.
  • Keeping the page[size] to a higher value would save you from calling all the pages. Let's say if you receive 50 orders every minute and you are calling the endpoint every 5 minutes, we recommend keeping the page[size] to 500 so that you cover more.

2. Saving the orders in your system

Save the orders in your system with each order having an export status whether it’s exported or not.

3. Exporting the orders

For the recently saved orders which are not exported(use the status from previous step), send the merchant_order_id to mark the orders as exported in our system. Use the steps in PATCH endpoint to do so as shown earlier.

Note

Please ensure to consider orders exported only when you get the 204 status code for the PATCH endpoint API call.

For all other error status codes, you should not mark the orders as exported in your system and should attempt to retry. In case of any issues, please contact the support.

Contact Support