bol.com API integration that keeps stock, orders and returns in step with your shop

What is a bol.com API integration, and what does the Retailer API cover?

A bol.com API integration is software that talks to bol's Retailer API on your behalf, so your seller account stays in sync with the system where you actually manage products and stock. Instead of editing offers in the seller dashboard and retyping orders, the integration does both automatically.

According to bol's own getting-started documentation, the Retailer API lets you manage products, offers, orders and shipments, retrieve and confirm cancellations, handle returns, view invoices and print shipping labels. Integrators authenticate with OAuth2 against bol's login service, using credentials you create inside your seller account. bol also provides a demo environment with example responses for every endpoint, which is where development and testing start.

One design point shapes everything: bol's documentation states that most calls are asynchronous. When you create an offer or confirm a shipment, bol accepts the request and returns a process status that you check afterwards. A reliable integration always follows up on that status instead of assuming success.

• Offers: what you sell on bol.com, identified by EAN, with price, stock, condition and delivery promise.
• Orders: what customers bought, fetched by your integration.
• Shipments: your confirmation that items left, with track and trace.
• Cancellations and returns: customer requests your system must process.

For the official reference, see bol's Retailer API documentation.

Do you actually need a bol.com API integration?

Not if you sell a few dozen products and process a handful of orders a day; the seller dashboard is fine. You need a bol.com API integration once stock must be shared with another channel, order volume makes retyping error-prone, or overselling starts costing you cancellations.

Overselling is usually the trigger. A product sells out in your webshop, but bol.com still shows it available because nobody updated the stock in time. The customer orders, you cancel, and your seller performance suffers. An integration that pushes one stock figure to both channels removes that problem at its root.

The second trigger is time. Copying orders into a shop admin or ERP, typing track-and-trace codes back into bol.com, and checking return requests every morning adds up. When that routine takes someone an hour or more a day, the build usually pays back quickly in staff time alone.

How are bol.com offers created and updated through the API?

In a bol.com API integration, offers are created per EAN, with your price, stock, condition, delivery code and fulfilment method. bol's offer documentation notes that creating a new offer is asynchronous: the request is queued, you receive a process status ID, and when processing finishes you get the new offer's ID. The integration stores that ID next to your product for all later updates.

Prices can be simple or tiered: bol's offer model supports bundle prices with up to four quantity-and-price tiers. Stock and price updates go to separate endpoints, which is handy, because stock changes often and price changes rarely. The API also offers an export of all your offers as a CSV file, which a good integration uses for a periodic cross-check against your own catalogue.

Product content is a separate matter. bol builds its catalogue from product data per EAN, and whether your content becomes the visible listing depends on bol's rules. Our integration focuses on your offers; if you supply new product content, we can connect that flow too, but the listing decisions stay with bol.

• Map each product in your shop to its EAN; flag products without one.
• Create offers in batches, then check each process status.
• Store bol's offer ID with your product for later updates.
• Send price changes and stock changes separately.
• Compare a weekly offer export against your catalogue for drift.

How does a bol.com API integration prevent overselling?

A bol.com API integration prevents overselling by treating one system as the stock master and pushing its figure to bol.com every time it changes, minus a safety buffer if you want one. Orders from bol.com reduce stock in the master first, which then updates your webshop and bol.com alike.

Timing is the subtle part. Between a sale in your webshop and bol.com receiving the new figure, there is a window where both channels show the old stock. Event-driven updates keep that window to seconds or minutes rather than the hour a scheduled feed might take. For products with very low stock, a buffer of one or two units on bol.com trades a little availability for far fewer cancellations.

bol's offer data includes a corrected stock value that accounts for open and handled orders, and a setting (managedByRetailer) that decides whether bol counts down for open orders or leaves that to you. Choosing the right mode prevents a double countdown, where both bol.com and your system subtract the same order. We set it deliberately, based on which side your master stock already accounts for.

• One master stock per product, usually your shop or ERP.
• Push on every change, not only on a timer.
• Optional buffer for low-stock or high-demand items.
• Deliberate choice of how bol counts open orders.
• Daily comparison of master stock versus bol.com stock.

How often should a bol.com integration fetch new orders?

bol's best-practice guide for the order process recommends polling the order list every 5 to 15 minutes, and offers a parameter that returns only orders changed since your last check. That rhythm keeps orders flowing to your warehouse quickly without wasting API budget.

Each new order is created in your master system with bol's order ID, customer delivery details and the promised delivery date, so pickers treat it like any other order. The integration marks the order as ‘from bol.com’ so shipping, invoicing and reporting can tell channels apart.

Keep your own copy of everything. bol's guide says shipped and cancelled items stay in the order list for 48 hours and in detailed endpoints for three months, and warns not to rely on the API as a permanent archive. Your integration should therefore store order data in your own database or ERP from the first fetch, which your bookkeeping will need anyway.

If Exact Online is where orders end up, the Exact integration guide explains how bookings, fees and payouts are mapped.

Shipment confirmation and track and trace: what must the integration send back?

For orders you ship yourself, your bol.com API integration must confirm each shipment to bol.com, ideally with the carrier and track-and-trace code in the same request. That confirmation is what tells bol the order is on its way.

bol's order best-practice guide is blunt about the stakes: if bol does not receive a successful shipment confirmation, the order will expire and be cancelled, and you will not receive payment. Because the shipment call is asynchronous, the integration must check the process status and retry or alert when it fails, rather than assume the confirmation landed.

Track-and-trace can be added later on the same day if your label is created after the shipment is confirmed, but sending it upfront gives customers better information. From Retailer API version 10, bol also supports splitting one order item over several shipments, useful when a customer orders several units that leave your warehouse in separate parcels.

• Warehouse marks the order shipped in your master system.
• Integration sends the shipment with carrier and track-and-trace code.
• Process status checked until success; failures alert a named person.
• Customer receives bol's shipping notification with tracking.

Logistiek via bol (LVB) or own fulfilment: how does the integration differ?

With LVB, which the API calls fulfilment by bol, a bol.com API integration has less to do on shipping: bol stores your stock and ships orders itself; with own fulfilment, you pick, pack and confirm shipments. The integration handles both, often in the same account, but the stock logic is different for each.

For LVB offers, bol's order guide notes that orders are picked up by bol as soon as possible, sometimes even before your system polls. Your integration fetches those orders for bookkeeping and reporting, but does not ship them or reduce your own warehouse stock. What it can do is show LVB stock at bol next to your own stock, so you know when to send new inventory.

For own-fulfilment offers, the full cycle applies: stock sync, order fetch, shipment confirmation and track-and-trace. Many sellers mix the two: fast movers in LVB, bulky or slow items shipped from their own warehouse. The integration keeps a fulfilment flag per offer so each order follows the right path.

Which is cheaper for your products depends on bol's current fee terms and your own logistics costs; that comparison is your call, and we build either way. For warehouse software beyond bol.com, see logistics software development.

Handling cancellations and returns without overselling or double refunds

In a bol.com API integration, cancellation requests and return registrations come through the API, and your integration must pick them up, act in your master system, and confirm back to bol.com. Ignoring them leads, in bol's words, to unhappy customers and unnecessary shipments and returns.

Cancellations are time-critical. When a customer asks to cancel before you ship, the integration should flag the order in your warehouse immediately so it is not packed, then confirm the cancellation to bol. If the parcel has already left, it should say so instead of confirming. Either way, stock must be corrected: a cancelled unfulfilled order returns its unit to available stock.

Returns follow a different path. A return registered on bol.com appears in your integration; when the parcel arrives, your team inspects it and records the outcome, which is then handled with bol. Only returns accepted back into saleable condition should go back into stock. Refund handling for bol orders happens through bol, so your own shop must not refund the same order a second time.

• Cancellation requests checked on every order poll.
• Warehouse flag before picking; confirmation back to bol.com.
• Stock restored only for unshipped or saleable returned units.
• Return outcomes recorded in your system and reported to bol.

Feed tools like Channable or a custom bol.com API integration?

Feed-management tools such as Channable connect a product feed to many marketplaces and advertising channels through settings rather than code. They are a strong choice when you sell on several channels with fairly standard rules. A custom bol.com API integration makes more sense when bol.com is a main channel and your stock, fulfilment or ERP logic does not fit a tool's options.

Questions to ask yourself: Do you need orders created directly in your ERP with specific fields? Do you mix LVB and own fulfilment with shared stock? Do you need event-driven stock updates rather than scheduled ones? Do you want full control over error alerts? If most answers are yes, custom wins. If you mainly want your catalogue on many channels quickly, a tool wins.

There is no shame in starting with a tool and moving to a custom integration later, or combining them: a tool for listings on other marketplaces, a custom integration for bol.com stock and orders. We will recommend the tool if it fits your case better.

The comparison table below the guide sets out the trade-offs row by row.

bol.com API integration for Shopify and WooCommerce stores

When your webshop is the master, the bol.com API integration listens to your shop's product, stock and order events and translates them into bol.com calls, and brings bol orders back into the shop. Your team keeps working in the familiar admin; bol.com follows.

For Shopify, we run the integration as a separate service using the Shopify Admin API and webhooks, so it adds nothing to your theme and survives theme changes. bol orders appear in Shopify with a channel tag, enter your usual fulfilment workflow, and send the shipment confirmation to bol.com when you mark them fulfilled.

For WooCommerce, the same service uses WooCommerce's REST API and webhooks. Running it outside WordPress keeps your shop fast and avoids yet another heavy plugin. Stock reservations are handled carefully, because WooCommerce reduces stock at different moments depending on payment method and settings.

Rebuilding the shop itself? See our Shopify developer and WooCommerce developer pages for Dutch merchants.

Connecting bol.com to an ERP or your own software

If stock and orders live in an ERP, warehouse system or software you built, the integration should connect bol.com to that system directly instead of going through a webshop. This is where a custom bol.com API integration is most clearly the right choice.

The design is the same as for shops, with a small service between bol.com and your system handling authentication, rate limits, retries and logs. What changes is the mapping: warehouse locations, article codes, customer records for marketplace buyers, and how commissions and payouts are booked. We agree these with your operations and finance people before building.

For accounting packages, marketplace sales often go to a separate sales journal with bol's commission and fees booked as costs. That is a bookkeeping decision; we implement the mapping your bookkeeper approves.

Wholesalers selling to businesses as well as on bol.com may also want a B2B webshop reading from the same stock.

Rate limits and asynchronous calls: building a reliable bol.com integration

bol applies rate limits and returns HTTP 429 when your budget runs out; every response carries headers saying how much budget remains and when it refills. A reliable bol.com API integration reads those headers and paces itself, rather than retrying blindly.

bol's rate-limit documentation says the API is optimised for a steady flow of updates over time rather than large batches every hour. That fits event-driven design: send each stock change as it happens, queue requests, and slow down when headers say the budget is low. It also says header names may vary in capitalisation, so the integration should read them case-insensitively.

Asynchronous calls add a second loop. For every create, update or shipment, the integration stores the process status ID and checks it until the process succeeds or fails. Failures go to an error list with bol's message, and the relevant person gets an alert. Nothing is marked done until bol confirms it.

• Queue all outgoing calls; never fire them in uncontrolled bursts.
• Read remaining budget from response headers on every call.
• Back off on 429 until the refill time the headers indicate.
• Track every process status to success or failure.

Retailer API versions: why integrations need planned upgrades

Every bol.com API integration needs occasional upgrades, because bol releases new Retailer API versions and retires old ones on announced dates. At the time of writing, bol's offer documentation marks the v10 offers endpoints as deprecated, recommends v11, and gives 1 February 2027 as the sunset date for v10.

An integration built against a retiring version will stop working on that date unless it is upgraded. We read bol's release notes as part of the care plan, estimate the work, and schedule the upgrade well before the deadline. New integrations are built against the current recommended version from the start.

Keeping the bol-specific code in one small service makes upgrades cheaper: only that service changes, while your shop or ERP stays untouched.

If you run an older integration built by someone else, send us its repository; we will check which versions it calls and what an upgrade involves.

How much does a bol.com API integration cost?

With BtechWaleTech, a focused bol.com API integration for stock and orders starts from US$600; a full integration covering offers, prices, shipments, cancellations, returns, LVB and reporting starts from US$900. Care after the two free months starts from US$120/mo. All are starting prices with an itemised written quote.

What moves the price: the number of products and how clean their EANs are, whether the master is a shop, ERP or custom system, whether you mix LVB and own fulfilment, how returns are processed, and whether accounting bookings are part of scope. Upgrading or fixing an existing integration depends on the state of its code, so we quote that after a review.

Running costs are separate: bol's own seller fees, hosting for the integration service and any tool subscriptions you keep. Quotes from others vary widely; compare them on the same list of flows, on how asynchronous calls and rate limits are handled, and on what happens when a sync fails.

For wider ecommerce budgets in the Netherlands, see webshop cost; all our starting prices are on the pricing page.

How long does a bol.com API integration take?

A bol.com API integration focused on stock and orders usually takes two to four weeks, and a full integration six to twelve weeks, from written approval. Development happens against bol's demo environment first, then a controlled switch to live data.

The work starts with a product audit: which products have valid EANs, which are already offered on bol.com, and which system is the stock master. Then the integration is built and tested against the demo environment, which bol describes as having the same models and validation as production. After that we connect your live seller account for a small set of offers, watch orders and shipments for a few days, and only then switch on the whole catalogue.

• Week 1: product and EAN audit, master system decision, credentials created by you.
• Weeks 1–3: build and test against bol's demo environment.
• Following week: live pilot on a small set of offers.
• Then: full catalogue, daily checks, handover documentation.

What does working with a bol.com integration team in India look like?

Straightforward: you create the API credentials in your bol.com seller account and share access securely, we build and test, and we talk on WhatsApp and short calls. India is three and a half hours ahead of Dutch summer time and four and a half in winter, which gives a shared working window from your late morning onward.

You receive an itemised USD quote within about two working days. Nothing is billed before you approve it in writing, and payment goes in milestones by Wise, bank wire or PayPal, with invoices issued from India. We work in English; Dutch product or customer texts come from you.

The integration service runs in a cloud account in your name, the code lives in your repository, and credentials can be rotated by you whenever you like. Our three-person setup means one of us writes the integration, another of us hosts and monitors it, and the third of us plans the rollout and automations, so there is always someone who knows the code.

For more on how a remote offshore team fits alongside your staff, see offshore web development team.

Worked example: a hypothetical homeware seller in Den Bosch

This scenario is illustrative, not a client case. Picture a homeware seller near Den Bosch with a WooCommerce shop and a growing bol.com account. Candles and small textiles sell fast; large mirrors and furniture sell slowly. Both channels draw on one warehouse, and staff update bol.com stock by hand twice a day. Twice a week something oversells.

The plan: WooCommerce stays the stock master. A small integration service pushes every stock change to bol.com, with a one-unit buffer on items under five in stock. Fast movers move to LVB, so the integration tracks their bol warehouse stock separately and alerts when replenishment is due. Orders for own-fulfilment offers are fetched every ten minutes, appear in WooCommerce with a bol tag, and send shipment confirmations with track and trace once packed.

Cancellations are checked on each poll and flagged in the picking list. Returns land in an inspection queue; only accepted items go back into stock. After a two-week pilot on twenty offers, the rest follow. A morning email compares stock on both sides and lists any failed calls. Hand updates stop, and overselling becomes a rare exception to investigate.