All documentation below refers to the Offer-API-Version-1. in February 2017, Offer-API-Version-2 will be released.
This interface allows the authenticated seller to request a list of all his offers as known to bol.com.
The offers in this file are either published or not-publish.
Published (for sale) offers are free of errors and were requested to be published by the seller.
Not published offers:
- May contain errors causing them not to be available on the bol.com selling channels;
- May have been configured explicitly to not be published on the bol.com selling channels;
- May be out of stock;
- May not comply with the general rules for an offer.
Note that even though an offer may appear to be for sale it can still be blocked because of lacking or insufficient product information. This is currently not visible nor manageable through the Offer API.
Using the optional “filter” parameter separate lists of offers that are “published” or “not published” can be requested. Omitting this parameter yields a list containing both “published” and “not published” offers.
This is an asynchronous API call. This means that the response to this request is not given immediately after the request was made. Instead an URL is returned where the list of offers will be published as soon as it becomes available.
URL structure: https://plazaapi.bol.com/offers/v1/export[?filter=<filter value>]
Filter values: <empty>, PUBLISHED, NOT-PUBLISHED (not case sensitive)
HTTP Verb: GET
Content-type: application/xml; charset=UTF-8
X-BOL-Date: Fri, 07 Oct 2011 13:24:01 GMT (See “Authentication” for more info)
X-BOL-Authorization: 0123456789abcdef:7ZHDSYabavdvIG0N4h1py//u3n/UNaqKdqblLhquMig= (See “Authentication” for more info)
Root element: None
Sub elements: None
A 200 status header is returned on success, including the XML conform the example below. Expect a report like this to take up to 15 minutes.
This export is cached on our server for 1 hour. Changes to your offers during this hour will not be reflected in the export untill and new export is generated an hour later.
Response XML Example:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
In case of an invalid filter value a 400 status header will be returned with an error XML message containing error code 41010 and an error message.
Try requesting the URL specified in “Location” every 5 minutes until the file becomes available. These calls must be signed just as any other PlazaAPI call.
A 412 (Precondition Failed) HTTP status will be returned if the file is not yet available.
|k003||PINGUIN||1122334455667||NEW||0||12.00||24uurs-12||TRUE||FALSE||OUT_OF_STOCK||Out of stock or remaining stock is reserved for pending orders||seller|
|k004||9988776655443||AS_NEW||1||5.95||Krasje op de achterkant||24uurs-12||TRUE||FALSE||INSUFFICIENT_PERMISSIONS||Not permitted to sell products in this category.||seller|
|k215||LEMUR||2233445667553||NEW||1||20.99||24uurs-12||FALSE||FALSE||NOT_PUBLISHED_BY_SELLER||Publish set to false by seller||seller|
|k515||BEAVER||3463445667553||NEW||1||23.99||24uurs-12||FALSE||FALSE||UNMATCHED_OFFER||Unknown EAN code: 57868547263||seller|
The columns are named identically as the XML elements of the Create call with a few exceptions:
- Published: Describes whether the offer is published on the website or not.
Note that this value is not fool proof as there are several potential reasons for an offer not to be published not taken into account. Those reasons are:
- Insufficient product content – This can be seen by manually visiting the bol.com seller backend at bol.com/sdd.
- Offers that have been ordered, but not shipped yet by the seller can cause the stock to drop to 0. This is not yet represented in this list until the orders have actually been fulfilled and marked as such.
- If an offer is being fulfilled by bol.com, the value for stock is no longer applicable! For more info see the next bullet point “FulfillmentMethod”.
- FulfillmentMethod: Describes whether this offer is being fulfilled by bol.com or by the seller himself.
Fulfillment By bol.com (FBB) is a new service allowing the seller to keep his stock at the bol.com warehouses from where they are being distributed to the buyers by bol.com.
Currently stock info for FBB offers are not available and the number shown is the last known stock from before the offer was configured to be fulfilled by bol.com.
- ReasonCode: When an offer has a “published” value of “FALSE” then this field contains a value that explains at a high level why the offer is not for sale on our at the reason.
- ReasonMessage: A textual, more detailed explanation of the reason that the offer is not published. The same reason code can be encountered in the same document with different reason messages.
Note that the OfferId field is not yet present in the open orders response. If you need that value for your fulfilment chain make sure to put the OfferID in the ReferenceCode field as well. A potential pitfall is that a ReferenceCode can be 14 characters whereas the OfferID can be 64 characters.