Home › Upgrade Guide to Offer API version 2

Upgrade Guide to Offer API version 2

The guide below will show you the difference between version 1 and version 2 of our Offer API. We recommend always using the latest version of our API and to upgrade at your earliest convenience. With the introduction of version 2, version 1 has become deprecated and will be shut down one year after the release of version 2.

Please note that during beta-testing your SellerID will have to be manually added to the beta-test program. If not added, you can not use this new API.

Create Offer

In version 2, Create and Update has been combined into 1 single endpoint. The OfferID has been dropped as a unique identifier for all offers. The combination EAN+Condition is now the new unique identifier for an offer. This also means you do not have to provide an OfferID when creating a new offer.

In version 2, it is also possible to add multiple offers in one Create request. Up to 50 <retailerOffer> elements can be added to one Create request.

In version 2, 2 new attributes have been introduced:

  • FulfillmentMethod
  • Title
Version 1 Version 2 
POST /offers/v1/offerID
 
PUT /offers/v2/
 
<OfferCreate xmlns="http://plazaapi.bol.com/offers/xsd/api-1.0.xsd">
<EAN>8715704021177</EAN>
<Condition>NEW</Condition>
<Price>10.00</Price>
<DeliveryCode>24uurs-16</DeliveryCode>
<QuantityInStock>13</QuantityInStock>
<Publish>true</Publish>
<ReferenceCode>MyReference</ReferenceCode>
<Description>Samsung Telefoon</Description>
</OfferCreate>
 
<UpsertRequest xmlns="https://plazaapi.bol.com/offers/xsd/api-2.0.xsd">
 <RetailerOffer>
 <EAN>8715704021177</EAN>
 <Condition>NEW</Condition>
 <Price>10.00</Price>
 <DeliveryCode>24uurs-16</DeliveryCode>
 <QuantityInStock>13</QuantityInStock>
 <Publish>true</Publish>
 <ReferenceCode>MyReference</ReferenceCode>
 <Description></Description>
 <Title>Title of my product</Title>
 <FulfillmentMethod>FBR</FulfillmentMethod>
 </RetailerOffer>
</UpsertRequest>

Update Offer

In version 2, Create and Update has been combined into 1 single endpoint. If the supplied EAN+Condition combination is a known combination it will be updated with the values provided. If it is not a known combination, the values provided will be used for the creation of a new offer.

Version 1 Version 2 
PUT /offers/v1/offerID
 
PUT /offers/v2/
 
<OfferUpdate xmlns="http://plazaapi.bol.com/offers/xsd/api-1.0.xsd">
 <Price>10.00</Price>
 <DeliveryCode>24uurs-16</DeliveryCode>
 <Publish>true</Publish>
 <ReferenceCode>MyReference</ReferenceCode>
 <Description>add new ref</Description>
</OfferUpdate>
 
<UpsertRequest xmlns="https://plazaapi.bol.com/offers/xsd/api-2.0.xsd">
 <RetailerOffer>
 <EAN>8715704021177</EAN>
 <Condition>NEW</Condition>
 <Price>11.50</Price>
 <DeliveryCode>24uurs-20</DeliveryCode>
 <QuantityInStock>13</QuantityInStock>
 <Publish>true</Rublish>
 <ReferenceCode>MyReference</ReferenceCode>
 <Description></Description>
 <Title>Title of my product</Title>
 <FulfillmentMethod>FBR</FulfillmentMethod>
 </RetailerOffer>
</UpsertRequest>

Update Offer stock

In version 2, Create and Update has been combined into 1 single endpoint. This is also true for the Stock update.

Version 1 Version 2 
PUT /offers/v1/offerID/stock
 
PUT /offers/v2/
 
<?xml version="1.0" encoding="UTF-8"?>
<StockUpdate xmlns="http://plazaapi.bol.com/offers/xsd/api-1.0.xsd">
 <QuantityInStock>7</QuantityInStock>
</StockUpdate>
 
<UpsertRequest xmlns="https://plazaapi.bol.com/offers/xsd/api-2.0.xsd">
 <RetailerOffer>
 <EAN>8715704021177</EAN>
 <Condition>NEW</Condition>
 <Price>10.00</Price>
 <DeliveryCode>24uurs-16</DeliveryCode>
 <QuantityInStock>7</QuantityInStock>
 <Publish>true</Publish>
 <ReferenceCode>MyReference</ReferenceCode>
 <Description></Description>
 <Title>Title of my product</Title>
 <FulfillmentMethod>FBR</FulfillmentMethod>
 </RetailerOffer>
</UpsertRequest>

Prepare Offer file

No change except for endpoint location.

Version 1 Version 2 
GET /offers/v1/export/
 
GET /offers/v2/export/

Request Offer file

Title added as new field in export file.

Version 1 Version 2 
GET /offers/v1/export/offerfilename.csv
 
GET /offers/v2/export/offerfilename.csv

Delete Offer

In version 2, the option to delete more than one offer has been introduced. Up to 1000 <retailerOfferIdentifier> child elements can be added to a single delete request.

Version 1 Version 2 
DELETE /offers/v1/offerID
 
DELETE /offers/v2/
 
<DeleteBulkRequest xmlns="https://plazaapi.bol.com/offers/xsd/api-2.0.xsd">
 <RetailerOfferIdentifier>
 <EAN>8715704021177</EAN>
 <Condition>NEW</Condition>
 </RetailerOfferIdentifier>
</DeleteBulkRequest>

Get Single Offer

Entirely new API endpoint which provides information on a single offer, including (error) status and Fulfillment information.

Get Commission

Entirely new API endpoint which provides Commission information.

bol.com Development Center