API v4 – Unpublished Offers Report [Temporary endpoint]

Access can be requested by filling in our form.

Introduction

After the release of the Retailer API v3 we have received feedback that the current set-up for retrieving the reason(s) why offers are not allowed to be published in the webshop is not working for everybody. Over the coming months we will be working on improving the feedback flow for different aspects related to offers.

However we do realize that currently retrieving invalid offers is a costly flow as there is not a way to define which offers are invalid without retrieving all of them with the use of the GET single offer request. To provide an option during the development phase of our long-term solutions we have created a separate report flow for invalid offers with which you can retrieve all invalid offers for a seller account.

Temporary solution

The unpublished offer report will be different from the regular flow as it is solely created to bridge a gap upon specific requests from users. This means that we will be providing it as part of the v4 beta but reserve the right to alter the timing of the deprecation and end-of-life schedule.

As soon as we have completed our improvements for the offer feedback we will consider this temporary solution to have served its purpose and will greatly reduce the deprecation period. We will off course communicate clearly during this period and keep users informed of the development phase of the long-term solutions. The unpublished report will be deprecated as soon as we have finished the innovations for the feedback flow. There will not be any extension possible at that point and further migration will be needed to retrieve feedback.

 

Flow of the unpublished offers report

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:

Step 1

a. First you need a POST request  which will start the creation of the offer export file. The required format of this is a csv file.

b. In the response to the POST request you can find the value ‘ID’. This ID is not the Offer-Report-ID but relates to a process status.

Step 2

Use the ID of the above response in a GET 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 was handled correctly.

If you correctly perform the GET process status request then you should get a response with a ID (which is the Process Status again) and an entityId. The entityId returns the id which is needed to retrieve the export file.

Step 3

Once the process status is set to ‘success’ you can use the Entity ID (UnpublishedOffers-Report-ID) in combination with the GET Retrieve an Unpublished Offer Report. 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.

Note: This request requires the following accept-header: application/vnd.retailer.v4+csv

Other responses are;

‘pending’ – the process is still ongoing and you need to re-try the GET process status request until the process reaches a end-state.

’time-out’ – the process has timed-out and the report has not been created. Re-try the process at a later moment. Contact bol.com support if the status remains ’time-out’ over the course of several hours.

‘failure’ – the process has not been successful and the report could not be created. Re-try the process at a later moment. Contact bol.com support if the status remains ‘failed’ over the course of several hours.

Format of the response

The csv that is returned includes the following columns;

offerId: The internal offerID that we have mapped for the offer and is used as a identifier for update and delete requests. It is the same as the one that is being used for the Retailer API v3.

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.

notPublishableReasonDescription: A specific description of the response provided in the notPublishableReason which will give further context and possible steps to resolve the notPublishableReason.

Example:

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.

Note that the Reason provided in the notPublishableReason is the same for both offers but the description indicates which action is specifically needed to resolve the error.

Possible reasons:

Please be aware that the notPublishableReasonDescription gives the most information regarding the issue that needs solving but these are volatile and are likely to change over time. Several distinct Descriptions are grouped into one specific notPublishableReason. The Reason gives the general issue and description give specific actions that can be taken.

1000 ISBN_EAN_INCORRECT”
1001 CONDITION_INCORRECT”
1002 PRICE_INCORRECT”
1003 STOCK_INCORRECT”
1004 TITLE_INCORRECT”
1005 REFERENCE_COMMENT_INCORRECT”
1006 FOR_SALE_INDICATOR_INCORRECT”
1007 COMMENT_INCORRECT”
1008 DAYS_TO_WAREHOUSE_INCORRECT”
1009 DELIVERY_TIME_INCORRECT”
1010 FULFILLMENT_CALENDAR_INCORRECT”
1011 FULFILLMENT_INCORRECT”
2000 BLOCKED”
2001 INSUFFICIENT_PERMISSIONS”
2002 UNMATCHED_OFFER”
2003 EXCLUSIVE_PRODUCT”
2004 FULFILLMENT_NOT_ALLOWED_FOR_CONDITION”
2005 INSUFFICIENT_PERMISSIONS”
2006 BRAND_NOT_ALLOWED”
2007 FUTURE_RELEASE”
3000 INSUFFICIENT_PERMISSIONS”
4000 PRICE_NOT_COMPETITIVE”
4001 DUPLICATE_OFFER”
4002 NON_EXISTENT_OFFER”
4003 NOT_PUBLISHED_BY_SELLER”
4004 UNMATCHED_OFFER”
4005 OTHER”
5000 OTHER”
5001 FULFILLMENT_CALENDAR_INCORRECT”
5002 FULFILLMENT_INCORRECT”