Sells your OpenCart catalogue on bol.com in the Netherlands and Belgium with your own bol API credentials: category mapping with a markup, offers by EAN, price and stock sync, the reason shown when bol holds an offer back, orders imported as real OpenCart orders (company, VAT and KvK number), tracking with a bol transporter code, cancellations and returns, a job queue with retries and a full log. Credentials stored encrypted. OpenCart 4, events and cron only, no OCMOD.
Tested on 4.1.0.4Version 1.0.1Compatible with OpenCart 4.1.0.4 No core file edits
Built forOpenCart
Every offer, its state and its reason1 of 6
What it does
Sells your OpenCart catalogue on bol.com in the Netherlands and Belgium with your own bol API credentials: category mapping with a markup, offers by EAN, price and stock sync, the reason shown when bol holds an offer back, orders imported as real OpenCart orders (company, VAT and KvK number), tracking with a bol transporter code, cancellations and returns, a job queue with retries and a full log. Credentials stored encrypted. OpenCart 4, events and cron only, no OCMOD.
What it changes for your store
Your OpenCart shop on bol.com. This extension connects your shop to your own bol seller account so that offers, stock, price and orders move without copy and paste. It is a two-way connector: offers go out, orders and tracking come back into your shop.
Know the limits. You need your own bol seller account with API credentials. The demo environment only returns fixed examples, so test mode proves the connection, not a full order flow. Products need an EAN; bol holds back an offer for an EAN it does not know until product content exists (add it in the bol Partner Platform). bol is polled by cron, so new orders arrive at the next sync. Not included: product content upload screens, attribute mapping, Logistics via bol shipping labels, invoices and refunds (use the bol Partner Platform). Imported orders do not send e-mails or fire the events of other extensions. Tested against a stand-in of the bol API built from the official OpenAPI files, not against a live seller account. bol and bol.com are trademarks of their owner. This extension is an independent product by Kavio Labs, not affiliated with or endorsed by bol.
Features
Connection
Your own API credentials (client ID and secret) from the bol Seller Dashboard; the secret is stored encrypted and never logged, the token is renewed automatically
Demo mode on the bol demo environment and live mode, one-click connection test
Sell in the Netherlands, Belgium or both; fulfilment by you (FBR) or by bol (FBB, orders are imported)
Offers
Search the bol category list and map it to your categories with a markup per category
Offers are created by EAN with price including VAT, stock, delivery promise and condition new; an EAN that already has an offer is updated instead
Per product: see whether it is not listed, waiting for bol or live, and the exact reason when bol holds an offer back (for example price or missing product information)
Price and stock
Markup in percent and a fixed amount per product, per category or for the account; price endings x.99, x.90 or whole numbers; exchange rate; stock buffer, zero limit and maximum; delivery time and VAT
Price and stock go out as updates only when something changed
Orders, tracking and returns
Every bol order becomes an OpenCart order: buyer, delivery address with house number, pickup point, billing address with company, VAT and KvK number, prices as sold, the status you choose, stock taken like a normal order
Orders whose product is not mapped are listed as failed imports with the reason and retried
Set the order to Shipped and write the tracking number in the order history ("Tracking: ABC123 carrier: PostNL"): bol receives the shipment with its transporter code (unknown carriers are sent as OTHER) and the process status is followed
Cancel items you cannot supply with a bol reason code; accept returns from the admin
Reliable
Job queue with retries (5 minutes up to 12 hours) and rate limit handling, a Jobs page with a run button, a filtered log with CSV export
Events and cron only, no OCMOD, no core edits; OpenCart 4, tested on 4.1.0.4
What you get
Download & installOne installer package (.ocmod.zip) for OpenCart 4.0.2 – 4.1.x. There is no OpenCart 3 edition. Download it from My licenses right after payment.
12 months of updates & supportNew versions and help for 12 months (24 or 36 months at checkout). After that the extension keeps working; renew anytime at 50%.
License for your storeOne production domain with all its subdomains; staging and local development hosts are free. How licensing works
30-day refundFull refund within 30 days of your first purchase, no reason needed. Refund policy
Tested buildsOpenCart 4.1.0.4. Tested on OpenCart 4.1.0.4.
Documentation & supportFull guide (Installation, Settings, Usage, Developer notes) on this page. Tickets from your account, first reply within 1 business day.
Compatibility
Bol.com Marketplace Connector works with OpenCart 4.1.0.4.
We list the builds we install and test on. “Tested” means the test plan ran on that build; “Supported” means the build is inside the supported range.
Compatibility
Version
Range
Runs on
Status
OpenCart 4.1.0.x
4.1.0.0 – 4.1.0.4
PHP 8.1 – 8.3
Tested on 4.1.0.4
OpenCart 4.0.2.x
4.0.2.0 – 4.0.2.3
PHP 8.0 – 8.2
Supported
1.0.0
Latest
First release for OpenCart 4.1: bol Retailer API with your own API credentials (client ID and secret, HTTP Basic token request, token renewed automatically), demo mode on the bol demo environment and live mode, connection test.
Category mapping from the bol category list with a markup per category, price rules, stock buffer and delivery promise.
Offers by EAN with the Offers API v11 (price including VAT, stock, fulfilment by you or by bol, Netherlands and/or Belgium, economic operator); existing offers are found by EAN and updated; the reason shown on the product when bol holds an offer back.
Price and stock as PATCH requests when something changed, nothing is re-sent otherwise.
Order import from open and changed orders into real OpenCart orders (delivery and billing address with house number, pickup point, company, VAT and KvK number, prices as sold).
Shipments with the carrier code and tracking number found in the order history, followed on the Process Status API; cancellations with a bol reason code (one order item per request, as the API requires); returns imported and accepted from the admin.
Job queue with retries, back-off and rate limit (429) handling, OpenCart cron and a secret web address, log with CSV export.
Every request is validated in the unit tests against the official bol OpenAPI files (Retailer API v10, Offers v11, Process Status v10, Product Content v10).
How do I install the extension?
Upload. Extensions > Installer: upload the .ocmod.zip. It is for OpenCart 4 (4.0.2 to 4.1.x).
Install and enable. Extensions > Extensions > Modules: install, open the settings and switch it on. Events register themselves; nothing is patched.
Enter the license key. Paste the key from My licenses. Subdomains, staging and local hosts are included; you have 14 days to do it.
OpenCart 4.1.0.4. Tested on OpenCart 4.1.0.4. The Compatibility tab lists every version range.
Do the extensions change core files?
No. They work through OpenCart events and standard extension types (modules, order totals, themes). No core file edits, no OCMOD patches, no theme template edits, so OpenCart updates and other extensions keep working.
What does the license cover?
One production store domain with every subdomain (www, shop., staging.), plus local development hosts such as localhost, *.local and *.test. A store on another domain needs its own license; a second-store license is 40% off. You have 14 days after installing to enter the key. 12 months of updates and support are included; after that the extension keeps working and renewals are 50% off. How licensing works
Can I get a refund?
Yes. Ask for a full refund within 30 days of your first purchase, no reason needed: open a ticket or write to [email protected] with your order number. The money goes back to the card or bank account you paid with within 5 business days of approval. Refund policy
How do I get help?
Open a ticket from your account, so your license details are attached. We answer Monday to Friday: bug reports within 1 business day, how-to questions within 2. Support policy. Not a customer yet? Ask a pre-sales question.
Sells your OpenCart catalog on bol.com (Netherlands and Belgium): category mapping with price rules, offers created by EAN, price and stock updates, order import, tracking numbers, cancellations and returns, all through your own bol API credentials.
What it does
Maps store categories to bol categories (a price markup per category or product, price endings, a stock buffer).
Creates offers on bol from mapped products with the Offers API v11: EAN, price (including VAT), stock, delivery promise, country shops (Netherlands, Belgium or both) and condition new. An EAN that already has an offer is updated instead. When bol holds an offer back, the reasons (price, missing content, on hold) are shown on the product.
Pushes price and stock with one update per offer when a product changes and on a schedule.
Imports open orders (the list for new or changed orders, then each order for its addresses) into OpenCart orders without duplicates: delivery address with house number and extension, pickup point, billing address with company name, VAT number and KvK number, prices as sold. Order items that bol anonymised stay anonymised.
Reports the tracking number of your own carrier (shipment with a transporter code from the bol list) and follows bol's process status until the shipment is accepted. Cancels order items with a bol reason code and accepts returns.
Your own bol API credentials (client ID and secret from the Seller Dashboard) are stored encrypted; the access token (valid for five minutes) is cached and renewed. The extension polls bol, so no inbound firewall rule is needed.
A job queue with automatic retries (5 minutes, 15 minutes, 1 hour, 3 hours, 12 hours) that also honours bol's rate limits (a 429 answer is retried later), and a log with filters and CSV export.
Trademark
bol and bol.com are trademarks of their owner; this extension is not affiliated with or endorsed by bol. It uses the public bol Retailer API with your own seller credentials and is subject to the bol terms of use of that API.
Compatibility
OpenCart 4.1 (tested on 4.1.0.4). OpenCart 3 is not supported by this extension.
PHP 7.4 or newer (tested on 8.1 and 8.3) with cURL and OpenSSL.
The queue is processed by the OpenCart cron; a secret web address is available as well (see Configuration).
Next steps
API conformance
Every request the extension sends is checked in the unit tests against the official bol OpenAPI files (Retailer API v10, Offers API v11, Process Status API v10, Product Content API v10): operation, query parameters, media types, required fields, enums, lengths and ranges. The bol demo environment needs a seller's credentials, so the full flow is tested against a local mock built from the same files.
Installation
Requirements
OpenCart 4.1 (tested on 4.1.0.4), PHP 7.4 or newer with cURL and OpenSSL (outgoing HTTPS to api.bol.com and login.bol.com).
A bol seller account (Verkopen op bol) with API access. You create the API credentials yourself: in the bol Seller Dashboard open Settings, then API settings, and add a new set of credentials. bol shows a client ID and a client secret; keep the secret safe, bol shows it once.
Products with an EAN barcode: bol matches every offer to its catalogue by EAN.
The standard OpenCart cron line on your server.
Install the extension
In the admin go to Extensions > Installer, upload kv_bol.ocmod.zip and click Install.
Extensions > Extensions, choose "Modules", find "Bol.com Marketplace Connector" and click Install (the green button).
Click Edit. Switch the connector on and, if you have one, enter your Kavio Labs license key. Without a key the extension works for 14 days.
The bol pages are under Sales > bol.com: Listings, Connection, Categories, Rules, Orders, Returns, Log, Jobs.
Cron: the install registers an hourly entry in the OpenCart cron, which needs the standard OpenCart cron line on your server (shown on the settings page). For a faster sync call the secret web address from the settings page every few minutes with your host cron.
First connection
Open Sales > bol.com > Connection.
Enter your client ID and secret. Test mode talks to the bol demo environment (answers are fixed examples and nothing is changed at bol); live mode talks to your seller account. The same credentials work in both: enter them in both sets, test first, then switch the mode to Live.
Choose where you sell (Netherlands, Belgium or both) and how you fulfil (you ship, or bol ships), and press Save and test.
Open Categories, map your categories to bol categories, then Listings to map products (barcode = EAN).
Update and uninstall
Install the new kv_bol.ocmod.zip over the old one from Extensions > Installer; your settings and tables are kept. Uninstalling the module in Extensions > Extensions removes the tables and settings (orders already imported stay in OpenCart).
Settings
Open Extensions > Extensions > Modules > Bol.com Marketplace Connector > Edit for the general settings, and Sales > bol.com for the working pages (Listings, Categories, Rules, Orders, Returns, Connection, Log, Jobs).
General
Setting
Default
Description
Enable
On
When off, no new work is started. Jobs of work that is already under way are still processed.
Debug log
Off
Also stores every HTTP call with masked request and response. Secrets and tokens are never stored.
Log retention (days)
90
Older log entries are removed by the cron run.
Sync interval (minutes)
15
How often products are synchronized, orders and returns imported and shipments reported.
Status of imported orders
Processing
Status of a new bol order in OpenCart (Processing takes the stock). The status mapping on the Rules page can override it.
Connection
Credentials are not ordinary settings: they are entered on the Connection page and stored encrypted (AES-256-GCM, key derived from your store's own secret). They are never shown again; leave the secret field empty to keep the saved value.
Field
Description
Mode
Test = bol demo environment (fixed example answers, nothing changes at bol). Live = your seller account.
Client ID / Client secret
Created in the bol Seller Dashboard (Settings, API settings). Enter the same pair in the test and live sets.
Sell in
Netherlands, Belgium or both. The offers are published in these bol country shops.
Fulfilment
You ship (FBR): offers carry a delivery promise and tracking numbers are reported. Bol ships (FBB, Logistics via bol): offers need stock in a bol warehouse and orders are only imported.
Economic operator ID
Optional. Sent with new offers (product safety information).
The access token lives five minutes; the extension keeps it and asks for a new one when needed. bol asks integrations not to log in for every call.
Rules page
Group
Setting
Description
Prices
Markup %, fixed amount
Added to the OpenCart price. A category mapping overrides it for its products, a product markup (Listings page) overrides both. The price sent to bol includes VAT and must be between 1.00 and 9999.00.
Prices
Price endings
Keep, whole numbers, always x.99 or x.90.
Prices
Exchange rate
Amount in euro per 1 unit of the store's primary currency. 1 = use the rate of the OpenCart currency EUR when it exists, else prices go unchanged.
Stock
Stock buffer, show zero at or below, maximum
bol sees stock minus the buffer; 0 at or below the minimum; 0 maximum = no limit.
New listings
Create offers automatically
Mapped products that are not on bol yet are sent by the sync.
New listings
VAT rate
Used for the order lines. bol prices include VAT.
New listings
Delivery time (days)
The promise sent for offers you ship: from N to N+1 days to the customer.
Orders
Status mapping
OpenCart status for each bol state (Created, Shipped, Cancelled, Returned ...). Empty = leave unchanged.
Shipping
I ship with my own carrier
Sends the tracking number found in the order history (a comment such as "Tracking: ABC123456 carrier: UPS") to bol (transporter code from the bol list, otherwise OTHER) and follows the process status.
Shipping
Cancel reason
The bol reason code used by Cannot supply on the Orders page (default OUT_OF_STOCK).
Cron
The install registers an hourly entry in the OpenCart cron (it needs the OpenCart cron line shown on the settings page). For a faster sync call the secret web address shown on the settings page every minute:
bol limits calls per endpoint (for example 25 order list calls per minute); the extension keeps well below and retries after a 429 answer.
Usage
Listings
Sales > bol.com > Listings lists the mapped products with their state: not listed, waiting for bol, live or with an error. Add a product with its EAN (the barcode is the offer key), or add all products of a category. Stock and price switches decide what is pushed. Sync now queues the sync at once.
A new offer is created at bol in one request and evaluated afterwards: the product shows Waiting for bol until bol has released it for sale in a country. When bol holds it back, the reasons are shown on the product, for example "Price too high (4000-1)" or "essential product information is missing (4004-2) [missing: Title, Brand]". Fix the cause (price, product content in the bol Partner Platform) and press Retry.
Categories and rules
Map each store category to a bol category (search the list, it is loaded from bol). The mapping carries the price markup for its products; the deepest mapped category of a product decides. Price, stock and delivery rules are on Rules.
Orders
New and changed orders are read from bol every sync interval: first the list of orders changed in the last minutes, then every order for its addresses. Each becomes one OpenCart order with the buyer, the delivery address (street, house number and extension; pickup point name when bol delivers to a point), the billing address (company, VAT number and KvK number go to the order comment) and the prices as sold. An order whose item has no mapped product is not imported and shows the reason (for example "No product mapping for barcode ..."); it is retried.
When an order item is shipped or cancelled at bol, the OpenCart order status follows the mapping on the Rules page. If the customer asks bol to cancel an item, bol marks it as a cancellation request; confirm it with Cannot supply (reason code REQUESTED_BY_CUSTOMER) so that the customer is refunded by bol.
Shipping and cancelling
Set the order to Shipped and write the tracking number in the order history (for example Tracking: 3SKABA123456789 carrier: PostNL). The extension then sends the open order items to bol with your carrier (the transporter code from the bol list when the name matches, otherwise OTHER) and reads bol's process status until bol accepts it. A failure is logged and retried. Cannot supply on the Orders page cancels the order and sends the reason code.
Returns
Returns registered at bol appear on Returns with items and reasons. Approve sends the handling result RETURN_RECEIVED with the expected quantity for every open item; bol refunds the customer. Other handling results are decided in the bol Partner Platform.
Log and jobs
Log shows every action with filters and a CSV export (secrets and tokens are masked). Jobs shows the queue, retries and the jobs that gave up, with a Retry button.
Developer notes
The extension is built on the shared Marketplace Hub: the generic parts (mapping, price rules, stock buffer, sync jobs, order import, status mapping, shipments, returns, log, queue) are channel independent; the bol part is three files (OpenCart glue in oc4/, shared code in src/).
Part
Role
Client\Api
The bol HTTP calls. Client credentials token (HTTP Basic at login.bol.com), versioned media types (application/vnd.retailer.v10+json, v11 for offers), problem+json error mapping, the Process Status host.
Drivers\Bol\Mapper
Pure translation: offer requests, order and return mapping, process outcome, transporter codes, reason texts. Unit tested with samples from the specifications.
Drivers\Bol\Driver
Implements Hub\DriverInterface: one request per offer, read back for the sale state, orders list then order, shipment and cancellation with process status follow, returns.
Hub\*, Queue, Jobs, Accounts, Log
Channel independent.
Endpoints used
Purpose
Call
Token
POST https://login.bol.com/token (Basic, grant_type=client_credentials)
Categories
GET /retailer/products/categories (Accept-Language nl)
Offers (v11)
POST /retailer/offers, PATCH /retailer/offers/{id}, GET /retailer/offers, GET /retailer/offers/{id}, GET /retailer/offers/{id}/not-for-sale-reasons
Orders
GET /retailer/orders (status, fulfilment-method, change-interval-minute, page), GET /retailer/orders/{id}, PUT /retailer/orders/cancellation (one order item per request, as the OpenAPI file demands)
Shipments
POST /retailer/shipments
Returns
GET /retailer/returns, GET /retailer/returns/{id}, PUT /retailer/returns/{rma-id}
Process status
GET /shared/process-status/{id}
Test mode uses /retailer-demo and /shared-demo.
API conformance (official bol documentation)
Checked on 2026-11-06 against the provider's own documentation. Offers v11 was compared with the OpenAPI file; bol offers no push channel used here, the connector polls.
admin/model/catalog/product.editProduct/after and deleteProduct/after mark the product for a push, catalog/model/checkout/order.addHistory/after follows stock changes, admin/view/sale/order_info/after adds the bol panel to the order page and admin/view/common/column_left/before the menu entry. No OCMOD.
Tests
php81 tests/unit.php (also php83): mapping, driver, glue and the OpenAPI conformance check (tests/SpecCheck.php validates every request against tests/spec/*.json, the official files). node tests/mock-server/server.js 11840 is a mock built from the same files; node tests/e2e.js drives the OpenCart 4.1 dev store against it (sets the setting module_kv_bol_base_url and restores it). The bol demo environment needs a seller's credentials, so it is not part of the automated tests.
Configuration for tests
The setting module_kv_bol_base_url (for example http://127.0.0.1:11840/retailer) redirects the API, the token endpoint and the shared host to the mock. Leave it empty in production.
Troubleshooting
"Test connection" fails
"Client authentication failed" (HTTP 401): the client ID or secret is wrong or was revoked. Create a new pair in the bol Seller Dashboard (Settings, API settings) and enter it again.
HTTP 403: bol blocks the account or the call (for example a blocked retailer account). Check your seller account status at bol.
Check the mode: test mode talks to the demo environment, live mode to your seller account. Enter the credentials in the set of the mode you use.
Check for spaces before or after the client ID and secret.
Your server must reach api.bol.com and login.bol.com over HTTPS (outgoing port 443) and have a current CA bundle.
The Log tab shows the bol answer (masked).
An offer does not go live
The Listings page shows the reason from bol: "Price too high" (the price is outside what bol accepts for the product), "essential product information is missing" (content for the EAN must exist at bol), the offer is on hold, or the seller account or country shop is not allowed to sell it. A price below 1.00 or above 9999.00 is refused by the extension before it is sent. An EAN must have 8 to 14 digits.
An order is not imported
"No product mapping for barcode ...": map the product with that EAN on the Listings page; the import is retried.
Orders of FBB (Logistics via bol) are only imported when Fulfilment is set to "bol ships".
bol anonymises customer data when the customer asks for it; such orders arrive with the text ANONYMISED in the address fields.
A shipment is not accepted
The log shows the text of bol's process status, for example an order item that is already shipped or cancelled. Shipments are sent for the items that are still open.
HTTP 429 (rate limit)
bol limits calls per endpoint. The extension retries the job after a pause (5 minutes first). If it keeps happening, lengthen the sync interval.
A job is "Waiting to retry" or "Gave up"
The last error is shown in the list. Fix the cause and press Retry. Jobs are retried automatically after 5 minutes, 15 minutes, 1 hour, 3 hours and 12 hours before they give up.
The cron address answers "Forbidden"
The key in the address is wrong. Copy the address again from the settings page.
Still stuck
Send the log export (secrets and tokens are masked) and the extension version to support.
FAQ
Does it work with the bol demo environment?
Test mode uses it. The demo returns fixed example answers (nothing is changed at bol), so it proves that your credentials and the request shapes work, not a full order flow.
Do I need a bol partner agreement?
No. You create API credentials for your own seller account in the Seller Dashboard and use them in your own store. Software providers who connect other sellers' accounts work as bol intermediaries under separate terms; this extension does not do that.
Which countries?
The Netherlands and Belgium, prices in euro.
Which fulfilment?
You ship (FBR) with full support. For Logistics via bol (FBB) offers can be created and orders are imported; bol ships.
What happens to products bol does not know?
The offer is created with the title; bol holds it back until content exists. The reason is shown on the product. Content is added in the bol Partner Platform.
Are prices with or without VAT?
bol prices include VAT. The extension sends the OpenCart price with your rules applied.
Does bol call my store?
No. The extension polls bol (push subscriptions are not used), so no inbound access is needed.
Can I get a Logistics via bol shipping label?
Not in this version: shipments are sent with your own carrier and tracking number.
OpenCart 3?
Not in this version; the extension is for OpenCart 4.1.
Does it change the OpenCart core?
No. It uses OpenCart events and its own tables; no OCMOD patches.
Server-side tracking for OpenCart 4.x and 3.0.x: purchases, refunds, add to cart, checkout, product views and leads go from your server to the free official GA4 Measurement Protocol, Meta Conversions API and TikTok Events API, deduplicated with the browser pixels through shared event ids. Consent-aware, SHA-256 hashed customer data, order status mapping, queue with retries, test mode and an event log. No paid relay, events only, no OCMOD.
The department store theme for OpenCart 4.x and 3.0.x: colour-coded departments, a department list beside the hero slider with two side promos, a big search with a department selector, tabbed product blocks, a 2 + 1 + 2 offer grid, deals of the day with real countdowns, a department showcase, a promotions band and a three-column product page with a sticky buy box. Four styles (Meridian, Harbor, Citrus, Night) and your own colours on top. Events only, no core changes.
Stop AI crawlers, scrapers, vulnerability scanners and unwanted countries before OpenCart 4.x or 3.0.x builds a page. Googlebot and Bingbot are verified by DNS and always allowed; 50+ bots get one switch each; country rules use free GeoIP databases and can close only the checkout; IP and network lists, rate limits, honeypots and the cart flood fix; a one-second challenge instead of a captcha; learning mode, dashboard, log, IP tester and Cloudflare export. No core changes, no OCMOD.
