Blocking Offers

Overview

The Offers Blocking API can be used to block and unblock offers. When your offer is blocked, your corresponding product will not be sold on Zalando.

At the moment it is possible to create an offer blocker for:

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

For example, it’s possible to create an offer blocker for EAN $EAN_1 in sales channel $SALES_CHANNEL_1.

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

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

Furthermore, the Zalando Operations Teams also have the ability to create offer blockers for a merchant’s products. Such offer blockers can not be deleted by merchants themselves. These offer blockers will not be visible when querying offer blockers using Offer Blocking API, but products blocked by them will have a corresponding status reported by Product Status Report API.

Please note, it is also possible to create offer blockers for articles that have not yet been onboarded. The API will accept such requests, and the blocker will be created for you automatically once the article has been onboarded successfully.

Offer Blocking API specification

  • Offer Blocking API reference: Information on scopes, rate limiting, and sandbox behavior.

  • OpenAPI reference for the Offer Blocking API.

PABLO Codes

PABLO (PArtner BLOcker) codes are used to indicate the reason for the blocking request. A complete table of PABLO codes may be found in the below table. When creating an offer blocker, please provide the most appropriate PABLO codes as the reason for your request.

PABLO 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)

Creating an Offer Blocker

Up to five offer 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": "PABLO_01",
     "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 offer 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 offer blocker specified in the request. Offer 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": "PABLO_01",
       "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 an Offer 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 Offer 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 offer 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 Offer Blockers

Query offer blockers created within a specific time frame

In some cases it is convenient to list only offer 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 offer blockers using a criteria

Offer 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