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.
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.
||Required. EAN code for the product being added.|
||Required. Whether the offer refers to a new or second hand product. Please consult the Available Conditions for more information.|
||Required. The price of the product with a dot (.) as a decimal separator (Decimal). Attention: Maximum value: 9999|
||Required. The delivery promise that applies to this product. Please consult the Available Delivery Codes for more information.|
||Required. The amount of items in stock. Attention: Minimum value: 0. Maximum value: 999.|
||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:
<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>
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>
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.