Offers

Offers API

The Offers API allows you to create and manage offers for your products. It enables you to perform operations like creating, retrieving, updating, deleting and getting an export of all the available offers through one of the following endpoints:

Create a new offer

Create a new offer - Allows you to create a new offer and add it to your assortment using the POST request. The Create a new offer request uses an asynchronous process which means that the request will be put on an internal queue and therefore will require more time to get processed.

Offers can be created using either the Seller Dashboard or through the Retailer API.

Perform the following steps to create a new offer using the Create a new offer endpoint of the API:

  1. Send a request to create a new offer. The processStatusId is returned by this endpoint.

  2. Use the processStatusId as an input parameter to the Get the status of an asynchronous process by process status id endpoint to retrieve the current processing status of your request.

  3. The response includes a status and an entityId.

    entityId is returned only if the status of the request is SUCCESS. For more information on other statuses, refer to the table below.

  4. If the status is SUCCESS, your offer has been created. For more information on the request statuses, refer to the process overview.

  5. The value of the entityId field corresponds to the offer id of the recently created offer.

Use this endpoint for only creation of a new offer. This endpoint does not support updating an offer after its creation.

Retrieve an offer by its offer id

Retrieve an offer by its offer id - Allows you to retrieve all the offer details and the current field values corresponding to the specified offerID. Using this endpoint, you can determine the validity of an offer and its current status (active/inactive) on the web shop.

This endpoint uses offerId, provided during retrieving the process status of a newly created offer to identify and list all the existing offers.

Update an offer

Update an offer - Allows you to update the following details of the specified offer:

  • reference - Specifies a user-defined identifier that allows you to identify a particular offer. This value is exposed in several other domains, such as the Get a list of orders endpoint in order to allow you to recognize the specific product in your own system.

  • onHoldByRetailer - Specifies if the offer can be put for sale on bol. It allows you to adjust the status of an offer to not for sale while keeping it visible in your Seller Dashboard. When set to true, your product is not exposed in the web shop. Setting it to false means you are indicating that the product can be sold.

  • unknownProductTitle - Specifies an identifier for the products not known to bol. It allows you to set a temporary title for your product when the product has not been assigned its content category. The title provided in this field is not used for our content services and is only temporarily visible in the Seller Dashboard. This title helps you to recognize the offer and add a product category to it.

  • fullfilment.method - Specifies the fulfilment method for the provided offer. It indicates whether the offer is going to be fulfilled by bol (FBB) or by the retailer (FBR).

  • deliveryCode - Specifies the delivery window applicable to the offer. It allows you to set the deliveryCode for a product and indicates the delivery timelines to the customer.

  • economicOperatorId - The identifier of the responsible economic operator in the EU.

For more information on the list of available delivery codes, see Create a new offer.

This endpoint returns the processStatusId which can be used as an input parameter to the Get the status of an asynchronous process by process status id endpoint to retrieve the current processing status of the request.

If economicOperatorId field is omitted from the payload of Update an offer endpoint, this will remove the link between the specified offer and the economic operator. This does not delete the economic operator itself. To delete an economic operator, use the Delete a specific economic operator associated with a retailer endpoint. This change will not affect your other offers linked to the same economic operator. To unlink the economic operator from your other offers, you need to repeat this process for each offer individually.
Although the visible field is mandatory, it maybe sent as an empty list in the response. This means that while the visible field is required in the schema, it may not contain any country codes at this time. Ensure your application can handle this scenario without errors and do not rely on this field to determine offer visibility in specific countries.

Update price(s) for offer by id

Update price(s) for offer by id - Allows you to solely update the price of the specified offer through bundle pricing. The structure of this request is aimed at allocating bundle prices for your offers.

Creating multiples bundles is not mandatory.

Use the processStatusId returned by this endpoint as an input parameter to the Get the status of an asynchronous process by process status id endpoint to retrieve the current processing status of the request.

Update stock for offer by id

Update stock for offer by id - Allows you to update the stock value for the specified offer. Using this endpoint, you can indicate if you want your system to be in the lead for the stock countdown process or if you want to use the corrected stock flow. For more information, refer Stock management.

Use the processStatusId returned by this endpoint, as an input parameter to the Get the status of an asynchronous process by process status id endpoint to retrieve the current processing status of the request.

Handling offer updates with no stock changes

Often, a lot of price and delivery updates for offers are received that don’t have any stock changes. Such requests require more processing capacity and hence loads the system. To address this, exclude all the Fulfillment By Retailer (FBR) offers that have no stock available from your update flows until they are back in stock again.

This approach offers the following benefits:

  • Lowers the total request count which reduces the load on the systems.

  • Allows room for other retailers and processes.

Delete offer by id

Delete offer by id - Allows you to permanently delete the specified offer from your assortment of offers.

Use the processStatusId returned by this endpoint, as an input parameter to the Get the status of an asynchronous process by process status id endpoint to retrieve the current processing status of the request.

Removal of an offer can be subjected to the following scenarios:

  • Permanent removal of the offer - Use Delete offer by id endpoint to permanently delete the offer.

  • Removal of the offer from the web shop, but not from the assortment of the retailer - Set the value of onHoldByRetailer field to true for your product. This will remove/pause the offer from the web shop, but not from your assortment of offers. Alternatively, you can also update the stock of your offer to zero to make it visible only on the Seller Dashboard.

It is recommended that you carefully evaluate the removal choices and your decision before performing the delete operation.

Request an offer export file

Request an offer export file - Requests an export of your current offers that contains detailed information of all your offers (online and offline) in the CSV format. It consists of a POST request that triggers the preparation of the CSV for the retrieval through the GET request.

Use the processStatusId returned by this endpoint, as an input parameter to the Get the status of an asynchronous process by process status id endpoint to retrieve the current processing status of the request.

Requesting the offer export file more than once within fifteen minutes of the first request will result in retrieving the same export report file. This means if you have updated your offers within fifteen minutes of requesting the first export, the updates might not reflect in the latest offer export file. Any updates made to an offer such as new offer, deleted offer, stock or price changes etc. are recognised as a change.

For example, the stock value of an item in the offer export file might differ from the current stock values. Hence, it is recommended to use the Retrieve an offer by its offer id endpoint to know the current field values corresponding to the specified offer.

Retrieve an offer export file by report id

Retrieve an offer export file by report id - Allows you to retrieve the offer export file generated from Request an offer export file endpoint.

To retrieve the offer export file, perform the following steps:

  1. Provide the report-id as an input parameter to the Retrieve an offer export file by report id.

  2. The response will be the requested CSV file which will contain the details of all the offers.

    NOTE:

    • The offer export file expires 14 days after its date of creation.

    • You can retrieve the offer export file only when you have the associated offerId.

Offer export file format

The following table presents comprehensive details of your offers obtained from the CSV file. It provides descriptions for each field and their corresponding meanings.

Table 1. Offers export field descriptions
Field name Description

offerId

Specifies the assigned ID that serves as an identifier for the offer.

ean

Specifies the EAN number associated with the product. If an ISBN is provided, it will be substituted with the corresponding EAN associated with that ISBN.

conditionName

Specifies the current state or quality of the product being offered.

conditionCategory

Specifies the categorization of the product’s condition. If the category is not explicitly provided, NEW or SECONDHAND category shall be determined based on the value of the condition.name field.

conditionComment

Specifies the description regarding the product’s condition. This field is permitted only under the following conditions:

  • The conditionName of the product does not indicate the value NEW.

  • Does not include any email address.

bundlePricesPrice

Specifies a set of prices (comprising a quantity and selling price) that are applicable to the offer.

fulfilmentDeliveryCode

Specifies the delivery commitment associated with the offer. This value can only be used in combination with the fulfilmentMethod FBR.

stockAmount

Specifies the quantity of the product available in the retailer’s warehouse, excluding FBB stock. It is set to a default value of 0.

onHoldByRetailer

Specifies the option to list an offer for sale on the bol website through a boolean value. By default, it is set to false.

fulfilmentType

Specifies the chosen fulfilment method. It could have any one of the following values:

  • Fulfilled by the retailer (FBR)

  • Fulfilled by bol (FBB).

mutationDateTime

Specifies the latest timestamp and date indicating the most recent modification made to the offer.

referenceCode

Specifies a user-defined identifier that helps in recognizing a specific offer when receiving data from bol’s system. This element can be optionally left empty and is limited to a maximum of 100 characters.

correctedStock

Specifies the quantity of items in stock, excluding the number of handled and open orders, in comparison to the stock information provided by you. Once this value reaches zero, your offer will become unavailable for sale on the web shop.

economicOperatorId

An identifier referring to the Economic operator entity (manufacturer, authorized party, importer, distributor or other natural person or legal entity for whom the obligations apply with regards to the manufacturing, or making available on the market of the product in line with the applicable EU laws).

Retrieving offer id(s)

The Retailer API requires the offerId to identify, update, retrieve or delete an offer. This offerId is received while retrieving the process status after an offer was created successfully. You can use it to get, update, retrieve or delete your offers. You can retrieve the offer id for your offers in the following ways:

  • Retrieving offer Id(s) for existing offers.

  • Retrieving offer Id(s) for newly created offers.

Using the Retrieve an offer export file by offer export id endpoint, you can retrieve all the corresponding offer Ids for your offers through the offer export file.

Retrieving Offer id(s) for existing offers

All processes require the offerId hence it’s important that you retrieve all offer Id(s) for your assortment.

If you already have an active assortment of offers online, the best way to retrieve the offer Id(s) for all your orders is by requesting an offer export file.

Your offers will already have an offer id if you use:

  • Previous versions of the Retailer API

  • Seller Dashboard

  • FTPS

To retrieve the offer Id(s) for existing offers:

  1. Use the Request an offer export file endpoint to trigger the preparation of the offer export file in the CSV format.

  2. Use the processStatusId returned by this endpoint, as an input parameter to the Get the status of an asynchronous process by process status id endpoint to retrieve the current processing status of the request.

  3. If the status is SUCCESS, you get entityId in the response. The entityId field contains the id required to retrieve the offer export file.

  4. Use the entityId received in step 3 as an input parameter to Retrieve an offer export file by offer export id endpoint.

  5. The response includes the CSV file containing detailed information on offers including EAN and offerId which can be used to map to the offer Id(s) in your database.

For more information on how to create the offers export CSV file, use our demo-environment for reference.

Retrieving Offer id(s) for newly created offers

If you have created any new offers you will still need the associated offer Id(s) in order to update or delete them in the future. You can retrieve these Offer Id(s) is by using the Create a new offer endpoint.

Bundle pricing

The Retailer API allows you to configure volume discounts for your offers. With volume discounts you can offer your customer a lower product price when buying more items. Bundle pricing allows you to configure the price of your product in a bundle. Every bundle is a combination of quantity and price, where the quantity specifies the minimum order quantity for the specified price.

Use the field bundlePrices, containing quantity and a selling price to configure the set of prices that apply to your offer. A retailer should provide at least one and at the most four bundles.

The first bundle will have mandatory single unit offer (quantity=1). All prices mentioned in the bundles should be in the EURO (€) currency.

An example of the bundle prices supplied by a retailer for an offer is given below:

{
    "pricing": {
        "bundlePrices": [
            {
                "quantity": 1,
                "price": 9.99
            },
            {
                "quantity": 5,
                "price": 8.99
            },
            {
                "quantity": 10,
                "price": 7.99
            },
            {
                "quantity": 15,
                "price": 6.99
            }
        ]
    }
}

In the aforementioned example, the offer will be priced at €9.99 for an order of 1-4 items, €8.99 for an order of 5-9 items and €7.99 for an order of 10-14 items and €6.99 for 15 items or more.

The maximum quantity and unitPrice for a single bundlePrice in your offer can be up to 24 and 9999 respectively.

To remove the bundle discount, update your bundlePrices offer with only single unit bundle (quantity=1).

For more information on volume discounts, visit the Partner platform.

Stock management

The Retailer API allows you to manage your inventory by reviewing and adjusting the stock quantities for your products.

The Retrieve an offer by its offer id endpoint offers the following elements to track the quantity of products for sale:

  • amount - Specifies the current quantity of products available in the warehouse for a specific product within the offer.

  • correctedStock - Specifies the amount of products in stock except the handled and open orders.

The endpoints Create a new offer and Update stock for offer by id allow you to update your current stock. When a customer places an order from one of the offers, one order is reserved until it is shipped from the warehouse. This is done in order to prevent it to be ordered by someone else. When an item is shipped, the value of the correctedStock remains the same. However, when you update the stock amount after shipping, the reservation is no longer taken into account. Updating the stock before confirming the shipment leads to double stock countdown.

These corrections can be overridden through the managedByRetailer element that has been added to the stock element in the following endpoints:

  • Create a new offer

  • Update stock for offer by id

The default value for the element managedByRetailer is false. If set to true, all the stock events happening before the retailer’s stock update will not be taken into account.

When you update the stock and assign the value true to the element managedByRetailer, the stock is not adjusted for open orders. Additionally, the customer cancellations are also not taken into account thereby preventing higher values for the corrected stock. Cancellations by the retailer result in the corrected stock being set to 0.

Use this functionality only if you use the endpoint exclusively for stock management. Processing the stock update through the Seller Dashboard, will result in the value of the managedByRetailer field being reset to false.

Two distinct scenarios detailing the uses and effects of the managedByRetailer value are given below:

Table 2. Offers with stock managedByRetailer=false
event seller stock corrected stock explanation

retailer updates stock (@10:00:00)

10

10

reservation (orderId=1) on web shop (@10:10:00)

10

9

corrected_stock -1

retailer updates stock (@11:00:00)

9

8

open order (id = 1) taken into account (no shipment/cancellation)

customer cancellation (orderId=1) (@11:15:00)

9

9

corrected_stock +1

reservation (orderId=2) on web shop (@11:20:00)

9

8

corrected_stock -1

retailer updates stock (@11:30:00)

2

1

cancelled order (id = 1) no longer taken into account

open order (id = 2) taken into account (no shipment/cancellation)

shipment (orderId = 2) (@11:40:00)

2

1

shipping an order does not change the corrected stock

retailer updates stock (@11:50:00)

1

1

cancelled order (id = 1) no longer taken into account

shipped order (id = 2) also no longer taken into account

shipped and cancelled orders are no longer taken into account once the retailer updates his stock
Table 3. Offers with stock managedByRetailer=true
event seller stock corrected stock explanation

retailer updates stock (@10:00:00)

10

10

reservation (orderId=1) on web shop (@10:10:00)

10

9

corrected_stock -1

retailer updates stock (@11:00:00)

9

9

open order (id =1) not taken into account

customer cancellation (orderId=1) (@11:15:00)

9

9

customer cancellation (id = 1) not taken into account

reservation (orderId=2) on web shop (@11:20:00)

9

8

corrected_stock -1

retailer updates stock (@11:30:00)

2

2

cancelled order (id = 1) not taken into account

open order (id = 2) not taken into account

shipment (orderId = 2) (@11:40:00)

2

2

shipping an order does not change the corrected stock

retailer updates stock (@11:50:00)

1

1

cancelled order (id = 1) not taken into account

shipped order (id = 2) also not taken into account