Create and Update

Create and Update (Upsert) Offer

In the Offer API V2 Create and Update calls have been combined into 1 single endpoint. The OfferID has been dropped as a unique identifier.

Offers are uniquely identified by the combination of EAN+Condition. When inserting an EAN+Condition combination which is already known as an offer, this request will result in an update for that offer. When inserting an EAN+Condition combination which is not yet known as an offer it will result in a newly created offer.

Bulk update

This endpoint allows insert/update in bulk with a maximum of 50 offers per Request. You can add multiple  <RetailerOffer> elements in one request.

PUT /offers/v2/

Input

Name Type Description
EAN string Required. EAN code for the product being added
Condition string Required. Whether the offer refers to a new or second hand product.
Available Conditions.
Price decimal Required. The price of the product with a dot (.) as a decimal separator (Decimal).
Maximum value: 9999
DeliveryCode string Required. The delivery promise that applies to this product.
Available Delivery Codes 
QuantityInStock int Required. The amount of items in stock.
Maximum value: 999.
Minimum value: 0
Publish boolean Required. Boolean (true/ flase ) determining whether the seller desires the product to be offered for sale on the bol.com website or not.

Note 1: Even when set to true, other factors may cause the offer not to end up being for sale.
Note 2: This field is identical to the “ForSale” field that exists in the FTP variant of offer management. (Boolean)

ReferenceCode string Required.  A value that may help you identify this particular offer when receiving orders. Element can optionally be left empty.
Maximum amount of characters: 20
Description string Required. A description that is only applicable when the chosen condition is NOT “NEW”. This describes the condition of the article to the buyer. It will be ignored if condition is NEW.
Maximum amount of characters: 2000
Title string Title for this product as shown on the webshop. When the EAN is new for bol.com your input will be shown. When this is already a known EAN, the bol.com title will be shown.
Maximum amount of characters: 500
FulfillmentMethod string Specifies whether this shipment will be fulfilled by the seller (FBR) or by bol.com (FBB).

possible values:

  • FBB
  • FBR

will default to FBR if not provided

Example request

 

<UpsertRequest xmlns="https://plazaapi.bol.com/offers/xsd/api-2.0.xsd">
 <RetailerOffer>
   <EAN>9789076174082</EAN>
   <Condition>REASONABLE</Condition>
   <Price>7.50</Price>
   <DeliveryCode>3-5d</DeliveryCode>
   <QuantityInStock>1</QuantityInStock>
   <Publish>true</Publish>
   <ReferenceCode>HarryPotter-2ehands</ReferenceCode>
   <Description>boek met koffievlekken</Description>
   <Title></Title>
   <FulfillmentMethod>FBR</FulfillmentMethod>
 </RetailerOffer>
</UpsertRequest>

Example response – succes

Status: 202 Accepted

Validation

All fields you send in the request will be validated. If any element fails to validate you will receive an error code and feedback on the problem. Please note, that if validation fails on 1 item the entire request will be ignored. None of the sent offers will be inserted.

Example request (invalid data)

<UpsertRequest xmlns="https://plazaapi.bol.com/offers/xsd/api-2.0.xsd">
 <RetailerOffer>
   <EAN>9789076174082</EAN>
   <Condition>REASONABLE</Condition>
   <Price>7.50</Price>
   <DeliveryCode>MORGEN</DeliveryCode>
   <QuantityInStock>1</QuantityInStock>
   <Publish>true</Publish>
   <ReferenceCode>HarryPotter-2ehands</ReferenceCode>
   <Description>boek met koffievlekken</Description>
   <Title></Title>
   <FulfillmentMethod>FBR</FulfillmentMethod>
 </RetailerOffer>
</UpsertRequest>

Example response – Failure

Status: 400 Bad Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Errors xmlns="https://plazaapi.bol.com/offers/xsd/api-2.0.xsd">
 <ValidationErrors>
 <ValidationError>
 <ErrorCode>41104</ErrorCode>
 <ErrorMessage>The delivery code is not valid; check the documentation for valid values.</ErrorMessage>
 <Field>DeliveryCode</Field>
 <Value>MORGEN</Value>
 </ValidationError>
 </ValidationErrors>
</Errors>

Offer Rejection

Even if your offer request is properly formed and passes validation, this does not always mean your offer is valid to be shown on bol.com.

There are several reasons why an offer might be rejected, some examples include:

  • You are not allowed to sell that specific product (e.g. certain pharmaceuticals or jewelry categories)
  • You are trying to add a duplicate offer (you already sell this product)
  • Your price is way above marketprice

We have listed all reasons why an offer might be rejected on: Appendix D – Offer Errors