Offer API use case guide

This API is currently in beta with limited availability. If you want to participate, you can look here. If you have any questions or remarks that can improve this API, mail us at retailerapi-beta@bol.com. Updates to this beta will be communicated via our developers portal.

This guide shows common use case examples.

Create a single offer

Create an offer by using this endpoint.

Use case 1: Create a Fulfilment By Bol (FBB) offer

This example creates a fulfilment by bol (fbb) offer on the bol marketplace with the following attributes:

The product is new.
One single price applies (no volume discount).
For sale in the Netherlands only.
The fulfilment is handled by bol.

{
    "ean": "4015211100803",
    "condition": {
        "type": "NEW"
    },
    "pricing": {
        "bundlePrices": [
            {
                "quantity": 1,
                "unitPrice": 4.99
            }
        ]
    },
    "countryAvailabilities": [
        {
            "countryCode": "NL"
        }
    ],
    "fulfilment": {
        "method": "FBB"
    }
}

Use case 2: Create a Fulfilment By Retailer (FBR) refurbished offer

This example creates a fulfilment by retailer (fbr) offer on the bol marketplace with the following attributes:

The product is a refurbished product with grade A.
One single price applies (no volume discount).
For sale in the Netherlands and Belgium.
The fulfilment is handled by the retailer itself, using a delivery promise defined by bol (within 24-hour; if ordered before 10 PM)
With a stock level of 5.
Where the stock levels are managed by bol.

{
    "ean": "4015211100803",
    "condition": {
        "type": "REFURBISHED",
        "attributes": {
            "grade": "A",
            "margin": false
        }
    },
    "pricing": {
        "bundlePrices": [
            {
                "quantity": 1,
                "unitPrice": 9.99
            }
        ]
    },
    "countryAvailabilities": [
        {
            "countryCode": "NL"
        },
        {
            "countryCode": "BE"
        }
    ],
    "fulfilment": {
        "method": "FBR",
        "schedule": "BOL_DELIVERY_PROMISE",
        "deliveryPromise": {
            "minimumDaysToCustomer": 0,
            "maximumDaysToCustomer": 1,
             "ultimateOrderTime": "22:00"
        }
    },
    "stock": {
        "amount": 5,
        "managedByRetailer": false
    }
}

Use case 3: Create a Fulfilment By Retailer (FBR) second hand offer

This example creates a fulfilment by retailer (fbr) offer on the bol marketplace with the following attributes:

The product is a second hand product with a product state that is as good as new.
With volume discount in case the customer buys at least 2 quantities.
For sale in Belgium only.
The fulfilment is handled by the retailer itself, using its own defined delivery schedule.
With a stock level of 2.
Where the stock levels are managed by the retailer itself.

{
    "ean": "4015211100803",
    "condition": {
        "type": "SECONDHAND",
        "attributes": {
            "state": "AS_NEW",
            "comment": "An optional comment. If you don't want to include a comment, you can ommit this field entirely."
        }
    },
    "pricing": {
        "bundlePrices": [
            {
                "quantity": 1,
                "unitPrice": 9.99
            },
            {
                "quantity": 2,
                "unitPrice": 4.99
            }
        ]
    },
    "countryAvailabilities": [
        {
            "countryCode": "BE"
        }
    ],
    "fulfilment": {
        "method": "FBR",
        "schedule": "MY_DELIVERY_PROMISE"
    },
    "stock": {
        "amount": 2,
        "managedByRetailer": true
    }
}

Use case 4: Create a Fulfilment By Retailer (FBR) offer using shipping via bol

This example creates a fulfilment by retailer (fbr) offer on the bol marketplace with the following attributes:

The product is new.
One single price applies (no volume discount).
For sale in the Netherlands only.
The fulfilment is done via shipment via bol.
With a stock level of 44.

{
    "ean": "4015211100803",
    "condition": {
        "type": "NEW"
    },
    "pricing": {
        "bundlePrices": [
            {
                "quantity": 1,
                "unitPrice": 9.99
            }
        ]
    },
    "countryAvailabilities": [
        {
            "countryCode": "NL"
        }
    ],
    "fulfilment": {
        "method": "FBR",
        "schedule": "SHIPPING_VIA_BOL"
    },
    "stock": {
        "amount": 44,
        "managedByRetailer": false
    }
}

Retrieve a single offer

Retrieve a single offer by using this endpoint.

Use case 1: Retrieve an FBB offer

This example retrieve a fulfilment by bol (fbb) offer on the bol marketplace with the following attributes:

The product is new.
One single price applies (no volume discount).
For sale in the Netherlands only.
The fulfilment is handled by bol.
Has a stock level of 10 quantities and a corrected stock level of 8 (meaning there are currently 2 orders pending with both a quantity of 1).

{
    "offerId": "6f9478d7-2b2f-4156-b694-758506a3fdcc",
    "ean": "4015211100803",
    "lastModifiedDateTime": "2025-10-14T09:09:43.904312+02:00",
    "onHoldByRetailer": false,
    "stock": {
        "amount": 10,
        "correctedStock": 8,
        "managedByRetailer": false
    },
    "countryAvailabilities": [
        {
            "countryCode": "NL",
            "forSale": true
        }
    ],
    "condition": {
        "type": "NEW"
    },
    "product": {
        "bolProductId": "9200000066291279"
    },
    "pricing": {
        "bundlePrices": [
            {
                "quantity": 1,
                "unitPrice": 9.99
            }
        ]
    },
    "fulfilment": {
        "method": "FBB"
    }
}

Use case 2: Retrieve a refurbished FBR offer

This example retrieve a fulfilment by retailer (fbr) offer on the bol marketplace with the following attributes:

The product is a refurbished product with grade C.
One single price applies (no volume discount).
For sale in the Netherlands and Belgium.
The fulfilment is handled by the retailer itself, using a delivery promise defined by bol (within 24-hour; if ordered before 10 PM).
Has a stock level of 5 and no current pending orders.

{
    "offerId": "11561569-24c9-470e-9f81-d32e3500c64b",
    "ean": "4015211100803",
    "lastModifiedDateTime": "2025-10-14T09:14:04.101703+02:00",
    "onHoldByRetailer": false,
    "stock": {
        "amount": 5,
        "managedByRetailer": false
    },
    "countryAvailabilities": [
        {
            "countryCode": "NL",
            "forSale": true
        },
        {
            "countryCode": "BE",
            "forSale": true
        }
    ],
    "condition": {
        "type": "REFURBISHED",
        "attributes": {
            "grade": "C",
            "margin": false
        }
    },
    "product": {
        "bolProductId": "9200000066291279"
    },
    "pricing": {
        "bundlePrices": [
            {
                "quantity": 1,
                "unitPrice": 9.99
            }
        ]
    },
    "fulfilment": {
        "method": "FBR",
        "schedule": "BOL_DELIVERY_PROMISE",
        "deliveryPromise": {
            "minimumDaysToCustomer": 0,
            "maximumDaysToCustomer": 1,
            "ultimateOrderTime": "22:00"
        }
    }
}

Use case 3: Retrieve a secondhand FBR offer

This example retrieve a fulfilment by retailer (fbr) offer on the bol marketplace with the following attributes:

The product is a second hand product with a product that is in a good condition.
With volume discount in case the customer buys at least 2 quantities.
For sale in Belgium only.
The fulfilment is handled by the retailer itself, using its own defined delivery schedule.
Has a stock level of 2 and currently 1 pending order with a quantity of 1.

{
    "offerId": "f90ac33c-2e7a-43cb-83e5-378afc9a40de",
    "ean": "4015211100803",
    "lastModifiedDateTime": "2025-10-14T09:16:04.181827+02:00",
    "onHoldByRetailer": false,
    "stock": {
        "amount": 2,
        "correctedStock": 1,
        "managedByRetailer": false
    },
    "countryAvailabilities": [
        {
            "countryCode": "BE",
            "forSale": true
        },
        {
            "countryCode": "NL",
            "forSale": false
        }
    ],
    "condition": {
        "type": "SECONDHAND",
        "attributes": {
            "comment": "An optional comment. If you don't want to include a comment, you can ommit this field entirely.",
            "state": "GOOD"
        }
    },
    "product": {
        "bolProductId": "9200000066291279"
    },
    "pricing": {
        "bundlePrices": [
            {
                "quantity": 1,
                "unitPrice": 9.99
            },
            {
                "quantity": 2,
                "unitPrice": 4.99
            }
        ]
    },
    "fulfilment": {
        "method": "FBR",
        "schedule": "MY_DELIVERY_PROMISE"
    }
}

Use case 4: Retrieve an FBR offer using shipping via bol

This example retrieve a fulfilment by retailer (fbr) offer on the bol marketplace with the following attributes:

The product is new.
One single price applies (no volume discount).
For sale in the Netherlands only.
The fulfilment is done via shipment via bol.
Has a stock level of 44 and no current pending orders.

{
    "offerId": "efb32ecb-5d06-42ca-a812-3ad29619cf73",
    "ean": "4015211100803",
    "lastModifiedDateTime": "2025-10-14T09:18:02.455809+02:00",
    "onHoldByRetailer": false,
    "stock": {
        "amount": 44,
        "managedByRetailer": false
    },
    "countryAvailabilities": [
        {
            "countryCode": "NL",
            "forSale": true
        }
    ],
    "condition": {
        "type": "NEW"
    },
    "product": {
        "bolProductId": "9200000066291279"
    },
    "pricing": {
        "bundlePrices": [
            {
                "quantity": 1,
                "unitPrice": 9.99
            }
        ]
    },
    "fulfilment": {
        "method": "FBR",
        "schedule": "SHIPPING_VIA_BOL"
    }
}

Update a single offer

Update an offer by using this endpoint.

Use case 1: Set your offer on hold (pause offer)

You can pause your offer by sending the following payload

{
	"onHoldByRetailer": true
}

Use case 2: Remove a previous set field value

{
     "reference": null
}

Use case 3: Update the economic operator and set a reference

{
     "economicOperatorId": "0c6573a2-a80c-48b7-a03e-d5939f1173fa",
     "reference": "This is my new reference"
}

Use case 4: Put your offer for sale in both NL and BE

{
    "countryAvailabilities": [
        {
            "countryCode": "BE"
        },
        {
            "countryCode": "NL"
        }
    ]
}

Use case 5: Put your offer for sale in countries based on your account setting

{
    "countryAvailabilities": null
}

Use case 6: Update the price of your offer

Update your offer to set the unitPrice to 4.99 euro in case the customer buys a quantity of 1.

{
    "pricing": {
       "bundlePrices": [
            {
                "quantity": 1,
                "unitPrice": 4.99
            }
       ]
    }
}

Update your offer to set the unitPrice to 8.99 euro in case the customer buys a quantity of 1 and 7.99 in case the customer buys a quantity of 2.

{
    "pricing": {
       "bundlePrices": [
            {
                "quantity": 1,
                "unitPrice": 8.99
            },
            {
                "quantity": 2,
                "unitPrice": 7.99
            }
       ]
    }
}

Use case 7: Update your stock levels for an (FBR) offer

Update your stock level for this offer to 8.

{
	"stock": {
		"amount": 8
	}
}

Use case 8: Update your price and stock levels for an (FBR) offer

Update your stock level for this offer to 12 and set a unit price of 7.99 and manage the stock levels yourself.

{
    "pricing": {
       "bundlePrices": [
            {
                "quantity": 1,
                "unitPrice": 7.99
            }
       ]
    },
    "stock": {
        "amount": 12,
        "managedByRetailer": true
    }
}

Use case 9: Update your price, stock levels and fulfilment for an FBR offer

The following scenario updates:

Your stock level for this offer to 12.
Your unit price to 7.99 when a customer buys 1 item and 6.99 when a customer buys 3 items.
The fulfilment schedule to my custom created calendar. In this scenario, the current offer was already an FBR offer.

{
    "pricing": {
       "bundlePrices": [
            {
                "quantity": 1,
                "unitPrice": 7.99
            },
            {
                "quantity": 3,
                "unitPrice": 6.99
            }
       ]
    },
    "fulfilment": {
        "method": "FBR",
        "schedule": "MY_DELIVERY_PROMISE"
    },
    "stock": {
        "amount": 12
    }
}

Use case 10: Switch an FBB offer to an FBR offer

The following scenario:

Switches your offer to an FBR offer while it was previously set as an FBB offer.
With a stock level of 12.
The fulfilment is handled by the retailer itself, using a delivery promise defined by bol (within 24-hour; if ordered before 6 PM)

{
    "fulfilment": {
        "method": "FBR",
        "schedule": "BOL_DELIVERY_PROMISE",
        "deliveryPromise": {
            "minimumDaysToCustomer": 0,
            "maximumDaysToCustomer": 1,
            "ultimateOrderTime": "18:00"
        }
    }
    ,
    "stock": {
        "amount": 12,
        "managedByRetailer": false
    }
}

Use case 11: Switch an FBR offer to an FBB offer

The following scenario:

Switches your offer to an FBB offer while it was previously set as an FBR offer.

{
    "fulfilment": {
        "method": "FBB"
    }
}

Delete a single offer

Delete an offer by using this endpoint.

Deleting an offer does not require a payload. The offerId is part of the path parameter.

Get not for sale reasons

Get not for sale reasons by using this endpoint.

Use case 1: NL offer that is currently not for sale

The following response is an offer that is only sold in the Netherlands (countryCode = NL) and is offline due to missing product content.

{
	"offerId": "ffccfa1f-1360-43c9-a9d7-b457c9d2b949",
	"countries": [
		{
			"countryCode": "NL",
			"reasons": [
				{
					"code": "4004-2",
					"description": "This offer is offline because mandatory product attributes (content) is missing."
				}
			]
		}
	]
}

Use case 2: NL and BE offer that are both currently not for sale

The following response is an offer that is sold in the Netherlands (countryCode = NL) and Belgium (countryCode = BE), but the offer is offline in both countries because there is no stock available anymore.

{
    "offerId": "ffccfa1f-1360-43c9-a9d7-b457c9d2b949",
    "countries": [
        {
            "countryCode": "NL",
            "reasons": [
                {
                    "code": "4003-3",
                    "description": "This offer is offline because there is no more stock left to fulfil a potential future order."
                }
            ]
        },
        {
            "countryCode": "BE",
            "reasons": [
                {
                    "code": "4003-3",
                    "description": "This offer is offline because there is no more stock left to fulfil a potential future order."
                }
            ]
        }
    ]
}

Use case 3: NL and BE offer that is partially for sale

The following response is an offer that is sold in the Netherlands (countryCode = NL) and Belgium (countryCode = BE), but that is only for sale in the Netherlands, but not for sale in Belgium.

{
	"offerId": "ffccfa1f-1360-43c9-a9d7-b457c9d2b949",
	"countries": [
		{
			"countryCode": "BE",
			"reasons": [
				{
					"code": "3000-1",
					"description": "This offer is offline because selling rights apply to this product."
				}
			]
		}
	]
}

Use case 4: NL and BE offer that is for sale in both countries

When an offer is for sale in both the Netherlands (countryCode = NL) and Belgium (countryCode = BE), you will receive a 204 No content.