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

How to use

Whenever publishing 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 of it 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 reasons it is not currently published in the webshop. You are now able to address all these errors at once.

It is advisable to take these steps for each offer in the unpublished offers report, far more efficient than trying to fix errors and generating the report again 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 differs. The following steps need to be taken to retrieve your report.

1. Request offers report

First you need to request the report which will start the creation of the unpublished offers file. The required format of this is 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 use of the process status is 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 then you should receive a response with an id (which is the process status again) and an entityId. The entityId contains the id which is needed to retrieve the export file.

3. Retrieve unpublished offers report

Once the process status reaches 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 for 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 generation of the report has not yet completed. 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.
Fieldname Description

offerId

The internal offerId that we have mapped for the offer and 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 Reason is a general reason which includes several closely related scenario’s. Use the notPublishableReasonDescription for 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 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.