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 that is already known as an offer, this request will result in an update for that offer. When inserting an EAN+Condition combination that is not yet known as an offer, it will result in a newly created offer.

Bulk update

This endpoint allows insert/update actions 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. Please consult the Available Conditions for more information.
Price decimal Required. The price of the product with a dot (.) as a decimal separator (Decimal). Attention: Maximum value: 9999
DeliveryCode string Required. The delivery promise that applies to this product. Please consult the Available Delivery Codes for more information.
QuantityInStock int Required. The amount of items in stock. Attention: Minimum value: 0. Maximum value: 999.
Publish boolean Required. Boolean (true/false) determining whether the seller desires the product to be offered for sale on the bol.com website. Note: Even when set to true, other factors may cause the offer not to be online.

Attention: This field is identical to the “ForSale” field that exists in the offer management through FTP.

ReferenceCode string Required.  A value that may help you identify this particular offer when receiving orders. This element can optionally be left empty. Attention: Maximum amount of characters: 20.
Description string Required. A description that is only applicable when the chosen condition is unequal to “NEW”. Note: It will be ignored if condition is NEW.

Attention: Maximum amount of characters: 2000.

Title string Title of the product as shown on the bol.com webshop. When the EAN is unknown at bol.com, your input will be shown. However, the bol.com title will be shown when it entails a known EAN.

Attention: 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 are:

  • FBR (default)
  • FBB

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>

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. Note: If validation fails on 1 item, the entire request will be ignored and included offers will not 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 – success

Status: 202 Accepted

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 (see examples below). All reasons for an offer being rejected on can be found at the offer errors page.

  • You are not allowed to sell the specific product due to a restricted category (e.g. certain pharmaceuticals or jewelry).
  • You are trying to add a duplicate offer (this product is already present in your offer file).
  • Your price is way above the market price set by bol.com.