Short answer. Through bol's Retailer API you automate prices, stock, delivery time, orders, shipments and invoices. Version 10 was the last time the whole API got a new version; since then bol versions per component. Write actions are asynchronous: you get a 202 with a process status id and then ask whether it succeeded. Automate what you can measure and reverse; leave content and cancellations to a human.
What the Retailer API is
The Retailer API is the official connection through which sellers (and the tools they use) talk to their seller account. Every seller creates their own API keys in the seller account. A tool that works for you uses your keys and therefore acts on your behalf; store them encrypted and never pass them on by email.
Versions: v10 was the last "big" version
According to bol's migration guide, v10 was the last time the full API was released as a new version. Since then versioning happens per resource: orders, offers, shipments and the other components each get their own version and their own end date. bol's lifecycle page names fixed moments for new versions, 1 April and 1 October, although that page is not up to date everywhere. Two consequences:
- If you build a connection yourself, you have to track per component which version you use and when it stops. The Accept and Content-Type headers carry the version (
application/vnd.retailer.v10+json). - If you use a tool, check whether the vendor keeps up with the migrations. A tool still on v9 in November 2024 was cut off.
Asynchronous: 202 and then the process status
A price or stock change is not processed immediately. The API answers with a 202 and a process status id; the actual processing follows later, and only in the process status do you see whether the change went through or was rejected with a validation error. A connection that only looks at the 202 thinks everything succeeded. Every serious automation stores the id, fetches the status and records the result per item.
What you automate
| Component | What you do with it | Watch out |
|---|---|---|
| Offers | Price, stock, delivery time and whether an item is for sale | Floor price and ceiling in your own system; never write a price without that check |
| Orders and shipments | Fetch orders, register shipments (several items per shipment, several shipments per order line) | Send track-and-trace along; the standard counts in your quality score |
| Commissions | Fetch the commission per EAN and per price | Use this for your floor price instead of a category average |
| Insights and competing offers | Competing offers, buy box status, price stars | Rate limits; fetch per country separately (NL and BE) |
| Invoices | Fetch invoices and specifications for your bookkeeping | Monthly, not daily |
| Returns and customer questions | Process returns, fetch questions | Automate the fetching, let a human handle them |
Rate limits: wait before the limit, not after
bol sets a limit per component on the number of requests. Exceed it and you get a 429 and have to wait; under load that means delayed prices and stale market data. The practical rule: keep track yourself of how much room is left and wait before the limit, with a margin of about twenty percent. A connection that "just retries" on a 429 makes the problem worse. With several seller accounts in one system, keep a separate budget per account, so one busy customer does not block the rest.
What you had better not automate
- Product content. Automatically overwriting titles and specifications from a feed sounds handy, until an empty column in the feed wipes your best title. Change content with a check beforehand.
- Cancellations. An automatic cancellation at "stock 0" costs quality score. Better: set stock to zero before the order comes in, and review by hand an order that comes in anyway.
- Prices without a floor. Every pricing rule without a floor price per item is a loss waiting for a competitor without a floor.
- Answers to customer questions. Fetching and assigning is fine; a human writes the answer itself, within 24 hours.
Build it yourself or use a tool
Building yourself pays off if you have your own system (ERP, webshop) that is the source of truth and you have the development capacity to migrate per resource version. In all other cases a tool is cheaper: the vendor carries the migrations, the rate limits and the process status handling. Ask three things when choosing: which API version per component the tool is on, whether you can see price proposals in dry-run before they are written, and whether every write action is logged with the result from the process status.
Checklist for a safe connection
- Own API keys per seller account, stored encrypted.
- Every write action logged: what, when, process status id, result.
- Floor price and ceiling per EAN checked before every price change.
- Rate limit budget per component and per account, waiting before the limit.
- A dry-run mode in which nothing is written to bol.
- An overview of the resource versions in use and their end dates.