Initial Order Processing

When an order is first created, we set the order status to initial while payment is authorized as shown in this example:

{
    "data": {
        "type": "Order",
        "id": "56be4b6d-f2de-4f57-b97b-6e1a5409623e",
        "attributes": {
            ...
            "status": "initial",

You may reserve stock for order articles, but otherwise, do not begin fulfilling an order unless it has a status of approved. Until then, the order may be canceled if the customer payment does not go through. Depending on the payment option the customer used, an order may remain in the initial state for several days.

If payment fails for an order, we will set the status of all Order Lines to canceled and set the Order Status to fulfilled.

For more information on Export Status and Order Status, see Order Status.

Reserving Stock for Ordered Items

Once you have gotten an order, we recommend placing the ordered articles on reserve until the Order Status is set to approved and you begin fulfillment in order to fulfill orders on a first-come, first-serve basis.

There are four parts to putting items on reserve:

  1. Reserve the items in your inventory system and/or warehouse.
  2. Use the Stocks API to lower the available stock of the item as described in Manage Stock.
  3. Use the Orders API to update the Order Line status of each item to reserved.
  4. Check back for the order status to be updated to approved or canceled.

Note

You may set the Order Line status to reserved before exporting the order, but no other fulfillment steps are allowed while the order is in the initial state and has not been exported.

To set the status of an Order Line to reserved, create a JSON payload similar to this example:

{
  "data":{
    "id":"$ORDER_LINE_ID",
    "type":"OrderLine",
    "attributes":{
      "status":"reserved"
    }
  }
}

Use the following request to update the specified Order Line:

PATCH /merchants/{merchant_ID}/orders/{order_ID}/items/{order_item_ID}/lines/{order_line_ID}

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

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

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.

Checking Back on Order Status

After an order is created with the status initial, we will set its status to approved when payment is successful. In this case, you may begin fulfillment.

If the payment fails, we will set the Oder Status to fulfilled and the Order Line Status for each item to canceled. If this happens and you have reserved any stock, you must use the Stocks API to return any reserved stock to your available inventory.

Note

You will not be notified when the Order Status changes, so it is important to re-request any order for which you have reserved stock, so you will know if it is canceled.

Contact Support