Getting Orders

Orders must be retrieved by partners. We do not currently support push notification.

We generally recommend scheduling several GET requests per day to keep up to date with incoming orders. Use the combination of scheduling and request parameters that works best with your process. For more information, see Best Practices for Getting Orders below.

On this page, we will review a few basic use cases. For a complete reference of all endpoints and parameters for getting orders, see the Orders API Reference and in our API Reference.

Note

The retention period for orders data is 1 year. All the orders older than this period are not accessible via the order API endpoints.

Getting all Unexported Orders

Use the following call to get all orders:

GET /merchants/{merchant_id}/orders

To get unexported orders only (non-ZFS):

GET /merchants/{merchant_id}/orders?exported=false

This httpie call gets all unexported orders (non-ZFS):

http https://api-sandbox.merchants.zalando.com\
/merchants/{merchant_ID}/orders \
exported=false \
Accept:application/vnd.api+json \
"Authorization:Bearer $YOUR_ACCESS_TOKEN"

Note

The argument Accept:application/vnd.api+json specifies the the MIME type.

Note

The flag exported=false/true is not supported for fetching ZFS orders and might produce unexpected results.

For an illustration of a typical JSON reply, see the Detailed Example in "Understanding Orders".

Getting a Specific Order

To retrieve a single specific order, add the order ID to the endpoint:

GET /merchants/{merchant_id}/orders/{order_id}

A sample httpie call:

http https://api-sandbox.merchants.zalando.com\
/merchants/{merchant_ID}/orders/{order_id} \
Accept:application/vnd.api+json \
"Authorization:Bearer $YOUR_ACCESS_TOKEN"

Getting a Specific Order with Additional Details

By default, only Order tier data will be returned when you get an order. To get additional information, use the include parameter.

For example, to get the order_item and order_line details:

GET /merchants/{merchant_id}/orders/{order_id}?include=order_items,order_lines

The following sample shows how to use httpie to make this call:

http https://api-sandbox.merchants.zalando.com\
/merchants/{merchant_id}/orders/{order_id} \
include=order_items,order_lines \
Accept:application/vnd.api+json \
"Authorization:Bearer $YOUR_ACCESS_TOKEN"

For an illustration of a typical JSON reply, see the Detailed Example in "Understanding Orders".

Best Practices for Getting Orders

We recommend getting orders several times per day so that you can keep up-to-date with them.

We also recommend building in redundant checks to make sure that no orders are missed. Under unusual circumstances, if a customer places an order while you are actively being served orders in multiple pages, you may not receive some of the orders in your returned data.

By default, we return 50 orders per page. To minimize the risk of missed orders, you may wish to increase the page[size] setting to a large value relative to the average number of orders you receive. For example, if you receive an average of 100 orders per hour, you may wish to get new orders every hour with the page size set to 300.

For more information on how to set page size, see the page size section of "Getting Orders" in our API Reference.

We recommend periodically running redundant checks for any missed orders. For example, you may wish to make a call every 15 minutes for all orders created in the last two hours, and then verify that every order ID has been registered in your system. You may additionally want to perform a check for the previous 24 hours once a day.

Additional Resources

Contact Support