Orders API Overview

Use the Orders API for order fulfillment (Partner Fulfillment) or to get order processing status and information from Zalando (ZFS).

Note that the Orders API is optimized for getting and managing orders, and we do not recommend using it for other reasons.

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.

Orders API Scopes

Use of the Orders API requires the Orders API/orders scope. Read permissions are necessary for GET requests, and Write permissions are necessary for PATCH requests.

Many zDirect APIs require clients to have specific permissions or scopes for read or write access. You may assign scopes to your apps in the "Applications" section of the zDirect Portal.

For more information on configuring app scopes, see the Applications section of our zDirect Portal guide.

Rate Limiting

You may only make the following number of requests per minute:

Request req/min (sandbox) req/min (production) rate-limit quota
GET multiple orders 10 40 per Fashion Partner
GET multiple orders by order_number 100 400 per Fashion Partner
GET multiple items 40 2000 per Fashion Partner
GET multiple lines 40 2000 per Fashion Partner
PATCH requests 40 2000 per Fashion Partner
GET orders-deletion-requests 10 40 per Fashion Partner
All other Orders API requests 40 2000 per app

A higher rate limit is applied on requests to the "GET multiple orders" endpoint using order_number parameter. This exception is meant to support those partners that are migrating to the zDirect API integration and need to map existing order numbers to the new order identifiers (e.g order_id). We advise you NOT to rely on this rate limit for other use cases as it is only temporary. Instead, refer to the generic rate limit for "GET multiple orders".

For more information, see Rate Limiting.

Sandbox Behavior

Prior to going Live, you will have no orders to test. Sandbox Orders accommodate you in process of integrating to Zalando Direct APIs. It enables you to test your logic and practice the fulfillment process.

Note

Data quality on the Sandbox environment is not guaranteed. Please note that the Sandbox environment is meant for functional testing only, and data quality in the Sandbox environment differs from production.

What is a Sandbox Order

Sandbox orders simulate a successful customer order containing Partner item(s). In these orders, similar to "real orders", the following information is stored and configurable:

  1. Merchant ID: Specifies which Fashion Partner the order contains items from.
  2. Sales Channel: Describes which Sales Channel the order was placed in, such as Germany (DE), France (FR), etc.
  3. Fulfillment Type: Defines which fulfillment type the order will be processed under (either Zalando Fulfillment Services (ZFS), or the Merchant will fulfill the order).
  4. Merchant SKU: This field is also known as Merchant Product Simple ID or Partner Variant Size. It states what are the Merchant SKU(s), identifying the merchant's product identifier, in the order. Please note that this value, will be reflected as external_id in the GET /merchants/{merchant-id}/orders/{order-id}/items API.
  5. Order Status: Frames the status of the order, if it's in Initial, Approved or Fulfilled state.
  6. Order Line Status: Defines the status of the actual articles in the inventory. For example, are they shipped, reserved, etc.
  7. Customer Information: You can optionally specify the customer name and shipping information, and a price for each order line. It's not encouraged to use this info for your internal validations, data quality checks and processes, as they can be mocked in your systems.

Caution

Sandbox orders are free of charge, and do not affect your orders' volume and production data.

Note

Sandbox orders are only accessible on sandbox environment.

When to use Sandbox Orders

We all know importance of testing the technical setup before going Live. Therefore, start testing your integration to the Orders API from the initial development steps.

Also, to ensure a smooth and seamless customer experience, you should place sandbox orders every time you make changes to your order processing logic.

How to create and use Sandbox Orders

  1. To get started on testing the Orders API, prepare your sandbox environment following the Sandbox Testing guide.
  2. Go to the Sandbox Orders Section and create Sandbox Order(s) for the Fashion Partner you want to test the order processing. To know more about how to use the Sandbox Orders Creation Tool check out here.
  3. Pick the Order ID(s) from the tool and use them to exercise and test the fulfillment process.

What scenarios should be tested?

  • Fetching Orders: This is the initial and important step in your orders processing flow. Fetch the orders ready to export.

  • Exporting orders: You should be able to identify by the status of the orders, which of them are not exported yet and export them, which basically means using Orders API PATCH endpoint.

    In this step you let Zalando know that you have received the orders, and you acknowledge that they will be processed.

    • Shipping Orders: Test the fulfillment process by shipping the "articles" - known as order lines. We highly recommend testing the flow with providing Tracking and Return numbers.

Tip

You can consider shipping one of the exported orders. This especially helps you if the Fashion Partner is fulfilling the orders themselves.

  • Cancelling Orders: Perhaps to practice a common scenario, we encourage you to test that you cannot fulfill any of the items. You need to mark the order line(s) as canceled.
  • Returning Orders: As a final recommendation, make sure you have the logic for "customer returning an order".

Caution

If you patch a test order, you may then get the order to verify that the intended update was successful. Receiving an expected output from the API shows your integration is correct. Therefore you don't need to contact Zalando's Tech Support for any confirmation.

Note

The Orders API supports all get and patch requests in sandbox mode.

Additional Resources

Contact Support