bol.com WooCommerce Integration (Koppeling) in 2026: Orders, Stock & Shipping Explained

If you sell on bol.com and also run a WooCommerce store, you already know the problem this article solves. Every bol order has to be found in the Seller Dashboard and copied into your own system. Then it has to be packed, shipped, and confirmed back on bol with a track-and-trace code before bol pays you. Stock that sold on bol has to be taken off the webshop before someone else buys it there, and vice versa. Two platforms, one warehouse, a lot of double work, and a few expensive ways to get it wrong.

A bol.com WooCommerce integration (in Dutch: a bol.com koppeling) connects the two so that orders, shipments and stock move automatically. This guide explains how that connection actually works, from the Retailer API down to the order states. It compares the options on the market (middleware, paid plugins, free plugins, custom code), what each costs, and where sellers get burned. It’s written for store owners and the developers who help them, with the Dutch terms people search for kept alongside the English ones.

I build WooCommerce plugins for a living, including a free bol.com orders sync plugin, so I’ll be open about where that fits and where it doesn’t.

What a bol.com koppeling actually does

“Integration” covers several separate flows, and not every tool handles all of them. Before comparing products, it helps to name the flows and decide which system is the source of truth for each.

The first four are the ones that cost you money or your seller rating when they fail, and they are what a bol.com WooCommerce integration has to get right before anything else. Most sellers should automate those first and leave offer content to the Seller Dashboard, where bol’s own tools are good enough. That is also why the lightweight plugins on the market are “orders-first”: orders, shipments and stock are the part worth doing reliably.

“bol.com WordPress plugin” vs “bol.com WooCommerce plugin”: which do you need?

A lot of people search for a bol.com WordPress koppeling or a bol.com WordPress plugin. That’s a reasonable thing to type, but it’s worth being precise, because it changes what you should install.

WordPress on its own has no products, orders, stock or customers. All of that comes from WooCommerce, the free ecommerce plugin that turns a WordPress site into a store. So when you integrate bol.com with “WordPress”, you are in practice integrating it with WooCommerce. bol orders become WooCommerce orders, bol stock updates read WooCommerce stock levels, and the shipment you confirm to bol is a WooCommerce order you marked as shipped.

There is one genuine “WordPress, not WooCommerce” case: affiliate sites that promote bol.com products with partner links and earn commission, without selling anything themselves. Those use bol’s Partner API (affiliate feeds, search, product data), which is a completely different API from the Retailer API this article is about. If you are a bol affiliate looking for a product-feed plugin, this guide is not what you need. If you are a bol seller with a webshop, read on; everything below applies whether you call your site a WordPress store or a WooCommerce store.

How the bol.com Retailer API works (the part every koppeling is built on)

Every integration, whether it’s a SaaS middleware, a paid plugin or something you build yourself, talks to the same thing: the bol.com Retailer API. Understanding its rules explains most of the behaviour you’ll see from any tool.

Getting API access

API access is tied to your seller account. In the Seller Dashboard you go to Instellingen → Diensten → API Instellingen and fill in a technical contact; bol requires one before it grants access. Then you create Client Credentials: a Client ID and a Client Secret. Those two values are what you paste into a plugin or middleware. Anyone who has them can read your orders and change your stock, so treat the secret like a password and prefer tools that store it encrypted.

Tokens, and why bol bans IP addresses

The Retailer API uses OAuth2 client credentials. Your integration exchanges the Client ID and Secret for a short-lived access token (about five minutes) and sends that token with each request. bol is explicit about one rule: an integration that requests a fresh token for every API call will get its IP address banned. A well-built koppeling caches the token and reuses it until just before it expires, then refreshes it. If you ever see an IP-ban warning from bol, the cause is almost always a tool (or two tools on the same server) that doesn’t cache tokens.

Versioning, rate limits and asynchronous operations

Requests must declare the API version through a versioned media type (currently application/vnd.retailer.v10+json); bol retires old versions on a schedule, which is why unmaintained plugins stop working. Rate limits are enforced per endpoint, and the API returns a Retry-After header when you hit one; good integrations back off instead of hammering.

Several operations, including creating a shipment, are asynchronous: the API accepts the request and returns a process status ID, and the integration has to poll that until it reports success. This matters in practice. A tool that fires the shipment request and assumes it worked can leave you with an order bol considers unhandled.

How bol expects you to poll for orders

bol’s own best-practice guidance for the order process is to poll the order list every 5 to 15 minutes, using the change-interval-minute parameter so you only receive new or changed orders. Full order details, including customer data, should be fetched once per order, when you are ready to ship, because the detail endpoint is not designed to be polled. A 15-minute import cycle is therefore not a limitation of a plugin; it is what bol asks for.

Data retention: the 48-hour and 3-month windows

bol’s orders and shipments documentation spells out the retention rules. Open order items stay visible until you handle them. Once shipped or cancelled, an item remains in the order list for only 48 hours, and in order details for three months. bol tells integrators to import the data they need into their own systems. That is one reason a koppeling that stores orders as native WooCommerce orders is more useful than a dashboard that merely displays bol’s list.

Customer data has its own rules. If a customer uses bol’s privacy option, name and address fields come back as ANONYMISED and you must delete that customer’s data from your systems. The customer email is blanked after 61 days, and billing details are not exposed for orders older than a month. A compliant integration imports what it needs at order time and doesn’t expect to re-fetch it later.

FBR, FBB and “Verzenden via bol”: which orders should you import?

bol has two fulfilment methods, and they need different handling.

FBR (Fulfilment by Retailer) means you store, pack and ship the item yourself. These are the orders you want in WooCommerce, because your warehouse has to act on them and you have to confirm the shipment back to bol.

FBB (Fulfilment by bol, also called LVB) means your stock sits in bol’s warehouse and bol ships it. bol picks up FBB orders almost immediately, so they can leave the “open” list before your integration even polls. You usually don’t need FBB orders in WooCommerce for operations, but you may want them for reporting. You may also want FBB stock levels flowing into WooCommerce so your webshop knows what bol is holding.

Verzenden via bol (VVB) is a third option inside FBR: you ship the parcel, but with a label bought through bol. The API marks these items with the distribution party BOL, and the shipment has to be confirmed using bol’s shipping-label ID rather than your own transporter code. Not every plugin supports VVB labels; check before you commit if you rely on them.

A sensible default for most webshop sellers: import FBR (including VVB if your tool supports it), optionally import FBB for records, and push stock only for products you fulfil yourself.

The order flow, step by step

Here is what happens to a single bol order inside a properly working bol.com WooCommerce integration. The details are the same for any tool; only the screens differ.

1. Import

On each poll, new or changed open orders are pulled from bol and created as WooCommerce orders. That includes line items, prices, shipping and billing addresses, the delivery window (standard, evening, same-day, Sunday), and whether the customer chose a pickup point. The bol order ID is stored on the WooCommerce order so the same bol order can never be imported twice.

A flag is also read on import: cancellationRequest. If it’s true, the customer asked bol to cancel before you shipped. A good integration surfaces this prominently (a note, a status, a warning) so your warehouse doesn’t pack an item that must be cancelled instead.

1. Match the product

Each bol order line has to be matched to a WooCommerce product so stock is reduced and the warehouse knows what to pick. The reliable match keys are your offer reference (the reference you set on the bol offer, normally your SKU) and the product’s EAN. If neither matches, the line should still be imported as a placeholder with a warning, never silently dropped: a missing line item is how you ship incomplete orders.

1. Process it like any other order

From this point the order is a normal WooCommerce order. It appears in your order list, prints on your pick lists, works with your shipping plugin, and counts in your reports. This is the whole point of importing as native orders rather than into a separate “bol orders” screen.

1. Ship and confirm

When you ship, bol needs a shipment confirmation per order item with a transporter code (PostNL, DHL, DPD, bpost, GLS, UPS and so on, each with bol’s own code). In practice it also needs a track-and-trace code, because without it the customer never receives a shipping email. Integrations typically trigger this when the WooCommerce order reaches a status you choose, such as Completed. The better ones read the tracking number that your shipment-tracking plugin already stored and map the carrier name to bol’s code automatically.

Then comes the step that sellers underestimate: verify the confirmation succeeded. Shipment creation is asynchronous, and bol is blunt about the consequence of failure. If bol does not receive a successful shipment confirmation, the order expires, is cancelled, and you are not paid, even though you physically shipped it. Unhandled FBR items are auto-cancelled three days after the expected delivery date. A sync log that shows the process-status result for every shipment is not a nice-to-have.

1. Cancellations

There are two kinds, and bol scores them differently. A customer-requested cancellation (the flag from step 1) should be confirmed with the reason REQUESTED_BY_CUSTOMER; bol refunds the customer and it does not affect your cancellation performance indicator. A retailer-initiated cancellation (you ran out of stock, the item was damaged) does lower your indicator, and using the customer-requested reason to dodge that is something bol detects and penalises. Your integration should send cancellations with the correct reason when you cancel the WooCommerce order. It should also re-check for customer cancellation requests just before shipping, because customers can request one right up to the moment you ship.

Stock sync (voorraad synchroniseren): where overselling comes from

Stock is the flow with the most hidden complexity, and the one where cheap integrations cut corners.

bol doesn’t address stock by SKU or EAN. It addresses it by offer ID, an identifier bol assigns to each of your offers. To update stock you need a map from your products to offer IDs. The official way to get that map is an asynchronous offer export: you request the export, wait for bol to generate it, then download and parse a CSV. Some plugins do that. Some learn offer IDs from the orders they import instead, which covers products that have sold at least once but not the long tail. Middleware services usually run the export for you.

The second decision is direction and timing. For FBR products, WooCommerce (or your WMS) is the source of truth and stock should flow to bol. For FBB products, bol’s warehouse count is the truth and should flow from bol. Pushing in the wrong direction is how a store “resets” bol stock to zero, or how a sold-out webshop keeps selling on bol.

The third is frequency. Hourly stock pushes are fine for most catalogues, but if you sell fast-moving items on both channels you need updates triggered by each sale, not just a schedule. Note that order import itself protects you here: when a bol order lands in WooCommerce and reduces stock, the next push sends the lower number back to bol.

Finally, large catalogues have to be pushed in batches, both for bol’s rate limits and for PHP’s execution time on shared hosting. A plugin that tries to update 5,000 offers in one request on a budget host will time out silently and leave you believing stock is in sync when it isn’t.

Offers, prices and content: do you need two-way product sync?

Sellers often assume a “full” integration must also create bol offers from WooCommerce products and keep prices and descriptions in sync. In practice this is the least valuable flow to automate for most small and mid-size sellers. There are three reasons.

bol’s catalogue is EAN-based: the product page on bol is shared across all sellers of that EAN, and what you control is your offer (price, stock, delivery promise, condition), not most of the content. Creating offers is a one-off job per product, done comfortably in the Seller Dashboard or via bol’s bulk upload. And pricing on bol usually follows a different strategy from your webshop (margins, commission, competing on the buy box), so a straight price copy is often wrong anyway.

Where two-way offer sync earns its cost is at scale: hundreds of SKUs with frequent price changes, multiple marketplaces, or an ERP as the master. That’s the territory of middleware or a custom build, and it’s priced accordingly.

Returns, settlements and VAT: what a koppeling can and can’t do for you

Returns are handled on bol’s side: the customer registers the return with bol, bol refunds the customer, and the item comes back to you (or to bol’s warehouse for FBB). The Retailer API exposes returns so an integration can register the return in WooCommerce and update stock when the item is received. Many orders-first tools leave this manual, which is acceptable at low return volumes and painful at high ones.

Payment and invoicing work differently from your webshop: the customer pays bol, bol pays you in periodic settlements net of commission. An imported WooCommerce order shows the amounts the customer paid, which is right for the pick list and the customer record. Your accounting, however, has to be booked from bol’s settlement reports, not from the WooCommerce order totals. Otherwise you will count revenue twice and get the commission wrong. Keep bol orders identifiable in WooCommerce (a dedicated status, a tag, or the bol order ID on the order) so they can be excluded from webshop revenue reports.

VAT is your responsibility as the seller. Imported prices are consumer prices including VAT. Make sure the integration assigns the correct tax class so the order’s VAT breakdown is right, especially if you sell both reduced-rate and standard-rate goods or ship to Belgium as well as the Netherlands.

Your options for a bol.com WooCommerce integration

There are four ways to get a working bol.com WooCommerce integration. They differ far more in cost model and control than in what the API lets them do.

A few honest notes on choosing. Middleware is the right answer when bol is one of several marketplaces and you already pay for a feed tool; paying a subscription for bol alone is hard to justify. Paid and free WordPress plugins keep everything inside WooCommerce, which is simpler to run and to back up, and is what most single-shop sellers want. Custom work makes sense once your process has rules no off-the-shelf tool models, and is a waste before that.

Whichever you pick, verify four things: it caches API tokens, it confirms shipments and checks the process status, it never silently drops unmatched order lines, and it is HPOS-compatible. WooCommerce’s High-Performance Order Storage is the default for new stores, and plugins that still write to the old posts table are on borrowed time.

Setting up a free bol.com WooCommerce koppeling in ten minutes

Here is the setup with my own plugin, mainly to show how little is involved once the API side is understood. The full documentation has screenshots and every setting.

1. Install and activate the plugin. WooCommerce has to be active.
2. In the bol Seller Dashboard, open Instellingen → Diensten → API Instellingen, complete the technical contact details, and create Client Credentials for the Retailer API.
3. In WordPress, go to WooCommerce → bol.com Sync, paste the Client ID and Client Secret (the secret is stored encrypted), and save.
4. Click Test connection. Fix any error here before going further.
5. Choose which fulfilment methods to import (FBR, FBB or both) and the WooCommerce status new bol orders should get, usually Processing. Then set the status that triggers a shipment confirmation, usually Completed, and a default transporter.
6. Tick Enable syncing. Orders import every 15 minutes, stock pushes hourly, and the Sync log shows the raw API result for every call.
7. Run one order sync before expecting stock sync to do anything. The plugin learns bol offer IDs from imported orders, so products that have sold at least once are kept in sync.

The plugin is free: no licence keys, no order quotas, no time limits. Products are matched on your offer reference first, then EAN, and unmatched lines are imported as placeholders with a warning. Tracking numbers already entered by common shipment-tracking plugins are picked up and the carrier is mapped to bol’s transporter code. Cancelling an order in WooCommerce cancels the item on bol with a proper reason code, and customer cancellation requests are flagged on import.

The free edition deliberately leaves four things out: the full asynchronous offer export (complete stock coverage for products that have never sold), partial and multi-parcel shipments, returns, and Verzenden via bol labels. Those are available as a Pro edition or as custom work, and if your operation needs them you should know that before you rely on the free version.

Common problems with a bol.com koppeling, and what causes them

Orders cancelled by bol even though you shipped them. The shipment confirmation never succeeded. Either it was sent without checking the process status, or it was sent to the wrong order item ID. Check the sync log for the shipment call; if your tool has no log, that is the problem.

Duplicate orders in WooCommerce. The integration isn’t keying imports on the bol order ID, or two integrations are running at once (a plugin plus a middleware trial, for example). Keep exactly one tool writing orders.

Order lines missing from the WooCommerce order. Product matching failed and the tool dropped the line. Fix the offer reference or EAN on the product, and switch to a tool that imports unmatched lines as placeholders.

“IP banned” or “too many requests” from bol. Token caching is missing, or several tools on the same server each request tokens. Consolidate.

Stock sync reports “no offers known” or updates only some products. Offer IDs haven’t been resolved. Run an order sync (for tools that learn IDs from orders) or an offer export (for tools that support it).

Stock keeps drifting. The push direction is wrong for FBB products, or batches are timing out on your host. Compare a handful of SKUs between WooCommerce and the Seller Dashboard after a push and check PHP’s max execution time.

Customer address shows ANONYMISED. This is bol’s privacy feature, not a bug. Ship using the address bol gave you at import, and delete the customer’s data afterwards as bol requires.

Shipped orders disappear from the integration’s list. They are only visible in bol’s order list for 48 hours after handling. If your tool doesn’t store orders in WooCommerce, you are losing history.

Cancellation performance indicator dropping. You are cancelling with the wrong reason, or shipping items the customer already asked to cancel because the flag isn’t being shown to your warehouse.

When it’s time to involve a developer

Off-the-shelf tools cover the standard flow well. You need custom WooCommerce plugin work when the standard flow isn’t yours. Typical cases: stock split across several warehouses or a 3PL; an ERP or WMS that must stay the master of stock and prices; VVB labels or partial shipments as the norm; bol-specific pricing rules; different assortments on bol.be and bol.nl; or bol as one of five marketplaces alongside Allegro, Mirakl or TikTok Shop. In those cases the right answer is usually a small, hook-based extension of a solid base plugin rather than a new integration from scratch. That keeps the maintenance burden where it belongs: on the base.

If you want to talk through your bol.com setup, I’ll tell you honestly whether the free plugin covers it, whether the Pro features do, or whether you need something built.

Frequently asked questions

Need this set up for your store, or need it to do something the standard tools don’t? See my WooCommerce plugin development service, or start with the free bol.com orders sync plugin and its documentation.