Updating Stock Levels (Partner Fulfillment)

Overview

The Stocks API may be used to update the stock of a merchant’s articles on a sales-channel level. To use this API a valid authentication token must be provided, please see the Authentication section for more information.

Merchants are expected to submit stock updates whenever:

  • An order is received by the merchant.

  • An order is cancelled (except for out of stock cancellations).

  • The merchant’s stock levels change.

It is also expected that when submitting a stock update for an article, a merchant will update the stock level in all sales channels.

Failure to update the stock levels in these scenarios may result in orders being placed for articles that are out of stock.

Stocks API specification

Caveats

Any stock updates received for EANs that have not yet been onboarded by the merchant will be held until they have been successfully onboarded, at which point the update will be released and the stock updated.

Submitting a stock update

The API currently consists of a single endpoint, which is used to update stock levels:

POST /merchants/{merchant_id}/stocks
In the body, the criteria for the update are specified. It is possible to update more than one article/sales-channel in a single request. Take this example request:

{
  "items": [
    {
      "sales_channel_id": "091dcbdd-7839-4f39-aa05-324eb4599df0",
      "ean": "4063614512884",
      "quantity": 5
    }
  ]
}
An array of items must be specified, with each item containing the target sales channel id, the EAN of the article whose stock is to be updated and the desired quantity.

Upon submission of the request, the API will provide a response containing an array of items, one for each update, containing the content of the update, in addition to indicating the status of the received update.

{
  "items": [
    {
      "item": {
        "sales_channel_id": "091dcbdd-7839-4f39-aa05-324eb4599df0",
        "ean": "4063614512884",
        "quantity": 5
      },
      "result": {
        "status": "ACCEPTED",
        "code": "0"
      }
    }
  ]
}

Full example

In this shell example, the cURL tool is used to make a HTTP request to the Zalando sandbox API.

REQUEST_BODY='
  {
    "items": [
      {
        "sales_channel_id": "091dcbdd-7839-4f39-aa05-324eb4599df0",
        "ean": "4063614512884",
        "quantity": 5
      }
    ]
  }
'

# Replace value with your API token.
API_TOKEN='abc123'


curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$REQUEST_BODY" \
  "https://api-sandbox.merchants.zalando.com/merchants/{merchant_id}/stocks"

Failure scenarios

If an update fails, the API will respond with an error code and corresponding error message, for example, if we try to set a negative stock level we will receive this response:

{
  "items": [
    {
      "item": {
        "sales_channel_id": "091dcbdd-7839-4f39-aa05-324eb4599df0",
        "ean": "4063614512884",
        "quantity": -2
      },
      "result": {
        "status": "REJECTED",
        "code": "101",
        "description": "Quantity is negative: -2."
      }
    }
  ]
}

A complete list of result statuses and corresponding error codes may be found in the API specification.

HTTP Status codes

Code Description
207 The batch of stock updates was successfully processed. Please consult the API response for information regarding the status of each update.
400 The request was ill-formatted.
404 The specified merchant id was not found.
429 You are rate limited. Please wait and try again.
Contact Support