Article Availability

Overview

The Article Availability API (this feature was previously known as Offer Blocking API) and Manage Availability feature in zDirect can be used to pause and resume articles. When your article is paused, your corresponding product will not be sold on Zalando.

At the moment it is possible to pause an article via API for:

  • A particular product of a merchant sold in a sales channel

For example, it's possible to pause an article for EAN $EAN_1 in sales channel $SALES_CHANNEL_1.

It is also possible to pause an article using exactly the same criteria, but for another reason. The combination of criteria and reason uniquely identifies a pause blocker.

As long as there is at least one matching pause blocker for a product, this product will not be offered to Zalando customers.

It is possible to pause an article using CSV file upload for up to 10,000 articles per file via zDirect UI. The blockers can be created using EAN, Zalando Simple SKU or Zalando Config SKU for selected or All sales channels.

With the Manage Availability feature, partners can easily pause any of their articles in zDirect to stop offering them to customers temporarily. The articles will remain in the Article listing and partners can resume them at any time. zDirect Manage Availability provides similar capabilities as the Article Availability API. Both solutions work in parallel, i.e. articles paused via UI can be resumed via the API and vice versa. The blocker_id to resume articles with the API is available in the Article Availability API GET endpoint.

Please note, it is also possible to pause the articles that have not yet been onboarded using API. The API will accept such requests, and the article will be paused automatically once it has been onboarded successfully. When pausing an article via the UI, the article must be onboarded first.

Furthermore, the Zalando Operations Teams also have the ability to block merchant's products. Such pause blockers can not be deleted by merchants themselves. These Zalando blockers will not be visible when querying pause blockers using Article Availability API, but products blocked by them will have a corresponding status reported by Product Status Report API.

Article Availability API specification

PABLO and PAUSE Codes

PABLO (PArtner BLOcker) and PAUSE codes are used to indicate the reason for the pausing request. A complete table of the codes may be found in the below table. When creating a pause blocker, please provide the most appropriate PAUSE/PABLO codes as the reason for your request. While the UI offers only the new PAUSE reasons, the Article Availability API still supports, in addition, the old PABLO reasons. Please note that it is planned to deprecate the PABLO reasons.

Code Description
PABLO_01 Generic issue
PABLO_02 Price issue
PABLO_03 Stock issue
PABLO_04 Product launch (e.g. for steering before go live)
PAUSE_01 End of season/removal from assortment
PAUSE_02 High return rate
PAUSE_03 Stock issue Low sales performance
PAUSE_04 Quality issues
PAUSE_05 Legal issues
PAUSE_06 Other reasons

Creating a Pause Blocker

Up to five pause blockers can be submitted per request. Please see the API overview for rate limiting information and the API specification for detailed information about the request and response bodies.

Request Body

Use the following template as a guide for constructing the request body of your call:

{
 "items": [
   {
     "reason": "PAUSE_06",
     "description": "A generic issue.",
     "criteria": {
       "sales_channel_id": "$SALES_CHANNEL_1",
       "ean": "$EAN_1"
     }
   },
   {
     "reason": "PABLO_02",
     "description": "A pricing issue.",
     "criteria": {
       "sales_channel_id": "$SALES_CHANNEL_2",
       "ean": "$EAN_2"
     }
   }
 ]
}

Submit the Request

Use the following endpoint to create pause blockers:

POST /merchants/{merchant_id}/offer-blockers

In this example, the httpie call takes the local file create-offer-blockers.json as an input for the POST request:

http POST \
https://api-sandbox.merchants.zalando.com\
/merchants/{merchant_id}/offer-blockers \
"Authorization:Bearer $YOUR_ACCESS_TOKEN" \
< create-offer-blockers.json

Response

After successful execution of the POST request, you will receive a response containing the HTTP 207 response code. This multi-status response provides a status and an optional description value for every pause blocker specified in the request. Pause blockers that were successfully created will be enriched with an id field. This blocker id is important as it needs to be used in a delete request in case the blocker should be removed again.

NOTE: The id found in the response must be used to delete a blocker !

Here is an example response:

{
 "results": [
   {
     "item": {
       "id": "0bd0d96e-6a89-4a33-b77e-a8e6c61f5a78",
       "reason": "PAUSE_06",
       "description": "A generic issue.",
       "criteria": {
         "sales_channel_id": "$SALES_CHANNEL_1",
         "ean": "$EAN_1"
       }
     },
     "result": {
       "status": "ACCEPTED"
     }
   },
   {
     "item": {
       "id": "51a0c2f1-41ac-4390-973c-47b4f2f6e50f",
       "reason": "PABLO_01",
       "description": "A generic issue.",
       "criteria": {
         "sales_channel_id": "$SALES_CHANNEL_2",
         "ean": "$EAN_2"
       }
     },
     "result": {
       "status": "ACCEPTED"
     }
   },
   {
     "item": {
       "reason": "PABLO_02",
       "description": "A pricing issue.",
       "criteria": {
         "sales_channel_id": "$SALES_CHANNEL_2",
         "ean": "$EAN_3"
       }
     },
     "result": {
       "status": "REJECTED",
       "description": "Validation failed: sales channel $SALES_CHANNEL2 is not active."
     }
   }
 ]
}

Deleting a Pause Blocker

Request Body

Use the following template as a guide for constructing the request body of your call. You have to use the same blocker id's as they were returned from the create request:

{
 "items": [
  "0bd0d96e-6a89-4a33-b77e-a8e6c61f5a78",
  "51a0c2f1-41ac-4390-973c-47b4f2f6e50f"
 ]
}

Submit the Request

Use the following endpoint to delete Pause Blockers:

DELETE /merchants/{merchant_id}/offer-blockers

In this example, the httpie call takes the local file delete-offer-blockers.json as an input for the DELETE request:

http DELETE \
https://api-sandbox.merchants.zalando.com\
/merchants/{merchant_id}/offer-blockers \
"Authorization:Bearer $YOUR_ACCESS_TOKEN" \
< delete-offer-blockers.json

Response

After successful execution of the POST, you will receive a response containing an HTTP 207 response code. This multi-status response provides a status and an optional description value for every pause blocker in the request.

Here is an example response:

{
 "results": [
   {
     "item": "0bd0d96e-6a89-4a33-b77e-a8e6c61f5a78",
     "result": {
       "status": "DELETED"
     }
   },
   {
     "item": "51a0c2f1-41ac-4390-973c-47b4f2f6e50f",
     "result": {
       "status": "DELETED"
     }
   }
 ]
}

Querying Pause Blockers

Query pause blockers created within a specific time frame

In some cases it is convenient to list only pause blockers created within a specific time frame. For example if you have a periodic synchronization job.

GET /merchants/{merchant_id}/offer-blockers?updated_since=2021-06-29T00:00:00Z&updated_until=2021-06-30T00:00:00Z

Query pause blockers using a criteria

Pause blockers can be queried using any combination of the following fields:

  • updated_since
  • updated_until
  • sales_channel_id
  • ean

Each field is optional and can be used only once per search query. When multiple fields are specified they are combined into a single criteria using logical AND.

For every field in the query an exact match is performed. Partial or regex values are not supported.

If the number of matching blockers exceeds 100 or the specified page size, only the first page of results will be contained in the response. The response will also contain a cursor that can be used as a query parameter in a new request to get the next page of results.

Contact Support