Unpublished offers report (BETA)

Access to the unpublished offers report is limited as it is a temporary solution which will be replaced in the near future. We reserve the right to remove it from the retailer API without the regular deprecation period.

Unpublished offers report API

Request unpublished offers report: requests the creation of a report containing all unpublished offers known to bol.com.
Retrieve unpublished offers report: retrieves the report that was created in the previous request once creation is complete.

How to use

Whenever you publish offers to the bol.com platform, there is a chance that offers will not be published after validation. There can be several reasons why offers are not being published, such as incomplete information, insufficient stock or a price level that is deemed suboptimal.

To get an overview of all the offers that are currently not being published in your catalog, you can request the unpublished offers report. For each of these unpublished offers we will show one reason for its not being visible in the webshop. You can use the contents of this list to find issues in your offer catalog and to remedy these.

The unpublished offer report is designed to provide an overview of unpublished offers, to allow retailers to make corrections to their catalogs. Please, do not try to fix errors based on the report alone and then regenerating it.

Instead, you can request the offer from the retrieve offer endpoint, which will show all the reasons it is not currently published in the webshop. You can now address all these errors at once.

It is advisable to take these steps for each offer in the unpublished offers report, since it is far more efficient than trying to fix errors and regenerating the report to see the next error.

Unpublished offers report flow

The retrieval of your unpublished offers report is similar to the regular V3 offer export; however be aware that the version, format, and naming of the endpoint is different.

The following steps must be followed to retrieve your report:

1. Request offers report

First you need to request the report which will begin the creation of the unpublished offers file. This is required be a CSV file. In the response to the request you can find the value id. This id is not the offer-report-id but relates to a process status.

2. Retrieve process status

Use the id of the above response in a retrieve process status request. The process status is used because of the asynchronous processing of the request which means you always have to check if the request processing has completed.

For more details on how the process status flow works, please read the documentation.

If you correctly perform the retrieve process status request you should receive a response with an id which is the process status, and an entityId which contains the id needed to retrieve the export file.

3. Retrieve unpublished offers report

Once the process status reaches the SUCCESS status, you can use the entityId (unpublished offers report id) in combination with the retrieve unpublished offers request. The response will be the requested CSV file which will contain the requested information. You can use our demo environment to view an example of the CSV file.

This request requires the Accept: application/vnd.retailer.v4+csv header to be used.

If the process status returns PENDING, this means that the report has not finished being generated. Please poll the process status every second or so to wait for it to change status.

Unpublished offers report format

The CSV file being returned will contain the following fields:

Table 1. Unpublished offers report field descriptions
Field name	Description
`offerId`	The internal `offerId` mapped for the offer, which is used as a identifier for update and delete requests.
`ean`	The EAN that was used by the partner to create the specific offer.
`notPublishableReason`	One 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. Detailed information on not publishable reasons for offers is available in the documentation.
`notPublishableReasonDescription`	A specific description of the response provided in the `notPublishableReason` which will give further context and possible steps to resolve the `notPublishableReason`.

Example unpublished offers report output.

offerId, ean, notPublishableReason, notPublishableReasonDescription
9e37bba2-3e4a-491f-e053-4242090a165e, 4053858829879, UNMATCHED_OFFER, You are the first to sell this item on bol.com. Please add a product category.
9e37bba2-4248-491f-e053-4242090a165e, 4053858417762, UNMATCHED_OFFER, For this product essential product information is missing. Go to ‘Mijn aanbod’ to enrich this product.

In the above example, the notPublishableReason value is the same for both offers, but the notPublishableReasonDescription specifies which action needs to be taken to resolve the error.

How to apply for access

The unpublished offers report is currently in closed beta. To apply for access, please fill in this form. If slots are available we will get in touch with you to make sure you get access.