Unpublished offer report

The Offers API provides the following endpoints that assist you in retrieving a report that lists all the unpublished offers in your product catalog:

Request an unpublished offer report: Requests the creation of a report containing all unpublished offers known to bol.
Retrieve an unpublished offer report by report id : Retrieves the report after it’s creation is complete.

Understanding the process

While publishing offers to the bol platform, there is a probability that offers might not get published after validation. Some possible reasons can be:

Incomplete information
Insufficient stock
Suboptimal price level

To get an overview of all the offers that are currently not published in your catalog, you can use the endpoint Request an unpublished offer report. For each of the unpublished offers in the report, this endpoint provides you all the possible reasons stating why that specific offer is not visible in the webshop. You can use the insights from this report to find issues in your offer catalog and fix them accordingly.

Unpublished offer report flow

Follow the steps below to retrieve your unpublished offer report:

1. Requesting unpublished offer report

First you need to request the report through the Request an unpublished offer report endpoint which will begin the creation of the unpublished offer report. This report returned will be a CSV file type.

2. Retrieving process status

Use the processStatusId from the response to retrieve the actual process status of your request through the Get the status of an asynchronous process by process status id endpoint. This is due to the asynchronous nature of the process which means that the request will require more time to get processed.

For more information about Process Status endpoint, refer to Process Status documentation.

Once the operation of your request has been processed successfully, you will receive an entityId that is equal to the report-id.

If the process status returns PENDING, this means that the report has not finished being generated. It is recommended to poll the process status after a few seconds or to wait until the status has changed.

3. Retrieving unpublished offer report

Retrieve the unpublished offers report by providing the report-id as an input parameter to the Retrieve an unpublished offer report by report id.
The response will be the requested CSV file which will contain the details of all the unpublished offers. You can use our demo environment to view an example of the CSV file.

Requesting the unpublished offer report more than once within fifteen minutes of the first request will result in retrieving the same report. This means if you have updated your offers within fifteen minutes of requesting the first report, the updates might not reflect in the latest unpublished offer report file. Any updates made to an offer such as new offer, deleted offer, stock or price changes etc. are recognised as a change.

Use the Accept: application/vnd.retailer.v10+csv header for this request. The unpublished offer report expires 14 days after its date of creation.

Unpublished offer report format

The retrieved CSV file contains the following fields:

Table 1. Unpublished offers report field descriptions
Field name	Description
`offerId`	Specifies the internal `offerId` mapped for the offer, which is used as a identifier for update and delete requests.
`ean`	Specifies the EAN that was used by the partner to create the specific offer.
`notPublishableReason`	Specifies a general reason why the offer is currently not valid for publication in the webshop. After resolving this reason there may be further reasons which will become visible in future exports. Please be aware that this is a general reason which includes several closely related scenarios. Use `notPublishableReasonDescription` for more specific information. To inspect the specific reason detailing why an offer was unpublished, see Offer request error codes.
`notPublishableReasonDescription`	A specific description of the response provided in the `notPublishableReason` which will give further context and possible steps to resolve the `notPublishableReason`.

An example of the unpublished offer report in the CSV format is given below:

Example unpublished offers report output.

offerId,ean,notPublishableReason,notPublishableReasonDescription
3db25eb7-13ba-4ed5-a84f-89802fef930e,8711807016683,INSUFFICIENT_PERMISSIONS,Seller not permitted to sell product %s.
75705851-8644-49bc-ad69-326bd319b391,8711807016683,NOT_PUBLISHED_BY_SELLER,The seller is on holiday
bcc0e5c8-0f89-489b-9ea8-d035c61f033a,0634154562956,MISSING_RIGHTS_CATEGORY_BRAND,Additional sales rights are required.
bcc0e5c8-0f89-489b-9ea8-d035c61f033a,0634154562956,NOT_PUBLISHED_BY_SELLER,The seller is on holiday

In the above example, the notPublishableReason value specifies all the reasons why the offerId bcc0e5c8-0f89-489b-9ea8-d035c61f033a was unpublished. Further, the notPublishableReasonDescription value specifies which action needs to be taken to resolve the error.