Overview
Bol.com is the dominant online marketplace in the Netherlands and Belgium, with millions of active buyers and a seller platform that allows businesses to reach customers across both countries. For retailers, brands, and fulfilment operations that sell on bol.com, the bol.com API is the integration point that makes automated order management, inventory synchronisation, listing management, and operational reporting possible without requiring manual work in the bol.com seller dashboard for every transaction.
The bol.com Retailer API (v10 and onwards) is the REST API that bol.com provides for programmatic access to seller operations. It covers orders, shipments, inventory, offers (product listings with pricing and availability), process statuses for asynchronous operations, returns, performance metrics, and the promotions that sellers use to manage pricing. The API uses OAuth 2.0 with client credentials authentication — the seller's API credentials used to obtain an access token that authorises subsequent requests.
Bol.com API operations fall into two categories: synchronous operations that return an immediate result (reading orders, reading inventory, reading offer data) and asynchronous operations that queue a task and return a process status token (bulk offer updates, bulk inventory changes, creating shipments). Asynchronous operations require polling the process status endpoint to determine when the queued operation has completed and whether it succeeded or failed. Correctly handling this two-phase pattern — submit, then poll for completion — is one of the more important bol.com API implementation details for reliable integration.
Bol.com also provides the fulfilment by bol.com (FBB) service where bol.com stores and ships seller inventory from its own fulfilment centres. Sellers using FBB have different integration requirements than sellers fulfilling their own orders (FBM — Fulfilled by Merchant), and the integration must correctly handle both models when a seller uses a mix of FBB and FBM across their product range.
We build bol.com integrations for Dutch and Belgian retailers, multi-channel e-commerce operations, warehouse management systems, and ERP platforms that need to connect their operations to bol.com's seller platform.
What Bol.com Integration Covers
Authentication and API access. The bol.com Retailer API uses OAuth 2.0 client credentials flow — the standard machine-to-machine authentication that does not require user interaction.
Client credentials authentication: the API client ID and client secret obtained from the bol.com seller dashboard, used to request access tokens from bol.com's OAuth endpoint (https://login.bol.com/token). The access token returned has a one-hour expiry and must be refreshed by requesting a new token before expiry. The Authorization: Bearer {access_token} header included in every API request.
Token lifecycle management: the token refresh logic that requests a new access token before the current one expires, caching the current token and its expiry time to avoid unnecessary token requests on each API call. The retry logic that handles token request failures — temporary network issues or bol.com authentication service unavailability — with appropriate backoff before retrying.
Test versus production environments: bol.com provides a separate test environment (api.bol.com/retailer-demo) for integration testing without affecting the production seller account. The test environment that uses test credentials and returns synthetic data — order data, inventory levels, offer data — for integration testing without creating real shipments or modifying real listings.
Orders API. The central integration point for order management — retrieving orders from bol.com and updating their status as they are processed.
Order retrieval: the GET /retailer/orders endpoint that returns open orders awaiting fulfilment, with pagination via the page parameter. The order response that includes the order items with their quantities, the delivery address, the fulfilment method (FBB or FBM), the latest delivery date (the date by which the order must be shipped to meet bol.com's delivery promise), and the order reference numbers.
Order item detail: each order line item includes the order item ID, the EAN (the product's European Article Number used as bol.com's product identifier), the title, the ordered quantity, the selling price, and the fulfilment method. The order item ID is the reference used for shipment confirmation and cancellation operations.
Single order retrieval: the GET /retailer/orders/{orderId} endpoint for retrieving the full details of a specific order — used when the order list provides insufficient detail or when looking up a specific order by its bol.com order ID.
Order filtering: the fulfilment-method parameter that filters orders to FBB only, FBM only, or both. The order status filtering that returns only orders in specific states — open orders for fulfilment, all orders for reporting.
Shipments API. Confirming order fulfilment by submitting shipment details to bol.com.
Shipment creation: the POST /retailer/shipments endpoint that confirms shipment of FBM order items. The shipment payload includes the order item IDs being shipped, the transport (carrier code and tracking code), and the shipment date. The asynchronous response — a process status token — that must be polled to confirm the shipment was accepted.
Carrier codes: bol.com's enumerated carrier codes for Dutch and Belgian carriers — TNT, DHL, DPD, GLS, POSTNL, BPOST, and the other carriers bol.com recognises. The carrier code that matches the shipping label generated for the order. The tracking number from the carrier's label that bol.com uses to provide delivery tracking to the buyer.
Partial shipment: shipping a subset of ordered items when not all items in an order can be shipped together. The shipment payload that specifies which order item IDs are included in each shipment, with the remainder shipped in a subsequent shipment.
Returns API. Handling customer returns for FBM orders.
Return retrieval: the GET /retailer/returns endpoint that lists returns awaiting handling. The return data including the return reference number, the order item ID, the EAN, the return reason the customer provided, and the return handling deadline.
Return handling: the PUT /retailer/returns/{returnId} endpoint for updating the handling outcome of a return — the result (RETURN_RECEIVED, EXCHANGE_PRODUCT, RETURN_DOES_NOT_MEET_CONDITIONS, REPAIR_PRODUCT) and the quantity handled. The return handling that closes the return case in bol.com's system and determines whether a refund is issued to the customer.
Offers API. Managing product listings on bol.com — creating, updating, and managing the offers that make products available for purchase.
Offer retrieval: the GET /retailer/offers/{offerId} endpoint for retrieving the current state of a specific offer — the price, the stock level, the condition, the fulfilment method, and the reference code. The POST /retailer/offers/export endpoint that generates a bulk export of all offers — an asynchronous operation that produces a downloadable CSV with all active offer data.
Offer creation: the POST /retailer/offers endpoint that creates a new offer for an existing bol.com product (identified by EAN). The offer payload includes the EAN, the seller's own reference code, the condition (NEW, AS_NEW, GOOD, REASONABLE, MODERATE), the pricing, the stock level, the fulfilment method, and the delivery window.
Offer updates: the PUT /retailer/offers/{offerId} endpoint for updating a single offer's price, stock level, condition, or fulfilment configuration. The bulk offer update via the POST /retailer/offers/bulk-price-update and POST /retailer/offers/bulk-stock-update endpoints for updating many offers simultaneously — the asynchronous operations that process large price and inventory update files.
Stock management: the stock level maintained in bol.com's system for FBM offers — the quantity available for purchase. The stock synchronisation that keeps bol.com's displayed availability aligned with the seller's actual warehouse inventory. The stock buffer that prevents overselling by maintaining a safety margin between the total available inventory and what is displayed as available on bol.com.
Price management: the selling price and list price for each offer. The price synchronisation that updates bol.com prices in response to pricing decisions made in the seller's ERP or pricing system. The promotion prices for offers participating in bol.com's promotional events.
Process Status API. The mechanism for tracking the outcome of asynchronous bol.com API operations.
Process status polling: the GET /retailer/process-status/{processStatusId} endpoint that returns the current status of an asynchronous operation — PENDING (still processing), SUCCESS (completed successfully), FAILURE (failed). The polling loop that checks status at appropriate intervals (every few seconds for short operations, every minute for bulk operations) until a terminal status is returned.
Bulk process status: the POST /retailer/process-status endpoint for retrieving the status of multiple process status IDs simultaneously — reducing the number of API calls required when tracking many concurrent asynchronous operations.
Error handling for asynchronous operations: the FAILURE status includes error details — the error type and error message that describe why the operation failed. The error handling that processes these failures, logs the detail, and triggers the appropriate retry or alert.
Inventory API. For FBB sellers — managing inventory in bol.com's fulfilment centres.
FBB inventory levels: the GET /retailer/inventory endpoint that returns the current inventory levels in bol.com's fulfilment centres for each EAN. The sellable quantity, the quantity in transit from the seller to bol.com, and the unsellable quantity currently in the fulfilment centre.
Replenishment triggers: monitoring FBB inventory levels and triggering replenishment shipments to bol.com's fulfilment centre when stock falls to defined thresholds. The replenishment logic that calculates the optimal replenishment quantity based on sales velocity and bol.com storage constraints.
Retailer Performance API. Seller performance metrics that bol.com tracks and uses to determine seller visibility and eligibility for promotional features.
Performance metrics retrieval: order fulfilment rate, cancellation rate, on-time delivery rate, return rate, and the customer review score. The metrics that indicate how the seller's performance compares to bol.com's expectations and to other sellers on the platform.
Performance monitoring: tracking performance metrics over time and alerting when metrics approach or breach bol.com's acceptable thresholds. The performance dashboard that surfaces the seller's current standing without requiring manual review of the bol.com seller dashboard.
Integration Patterns
Order synchronisation. The primary bol.com integration workflow — polling the orders endpoint at regular intervals (every 5–15 minutes), importing new orders into the seller's OMS or ERP, processing them through the fulfilment workflow, and confirming shipment back to bol.com when orders are dispatched. The incremental polling that retrieves only open orders rather than the full order history on each run.
Inventory synchronisation. Keeping bol.com's displayed stock level aligned with the seller's warehouse inventory. The push-based inventory update that triggers a bol.com stock update when inventory levels change in the warehouse management system — each goods receipt, each shipment, each stock adjustment propagated to bol.com. The scheduled full reconciliation that compares bol.com stock levels with the warehouse system and corrects discrepancies that may have accumulated.
Price synchronisation. Updating bol.com prices from the seller's pricing system — the scheduled price update job that compares current bol.com prices with target prices from the pricing system and submits updates for any offers where the price has changed. The event-driven price update that responds to pricing system changes with immediate bol.com offer updates.
Multi-channel integration. Bol.com as one of multiple sales channels managed by a central inventory and order management system. The bol.com channel connector that receives orders from bol.com and routes them into the central OMS alongside orders from other channels (own website, Amazon, other marketplaces). The central inventory system that maintains the total available inventory and distributes available quantity across channels, preventing overselling when the same products are sold on multiple platforms simultaneously.
Technologies Used
- C# / ASP.NET Core — primary bol.com integration implementation, leveraging .NET's HTTP client ecosystem and JSON processing for the bol.com REST API
- Rust / Axum — high-performance bol.com data processing for high-volume sellers with demanding synchronisation requirements
- TypeScript / Node.js — bol.com integration for JavaScript-based e-commerce platforms and operational dashboards
- OAuth 2.0 client credentials — bol.com API authentication
- REST / HTTP — bol.com Retailer API communication
- SQL (PostgreSQL / MySQL) — order data storage, offer data caching, synchronisation state, process status tracking
- Redis — access token caching, synchronisation job coordination, rate limit management
- Hangfire / scheduled jobs — order polling, inventory synchronisation, price update scheduling
- Docker — containerised integration service deployment
- GitHub Actions — CI/CD pipeline for integration service deployment
Bol.com Integration in the Dutch E-commerce Context
For Dutch and Belgian retailers, bol.com is often the most significant online sales channel outside of their own website. The volume of orders processed through bol.com, the seller performance requirements that bol.com enforces, and the operational complexity of managing FBM and FBB products simultaneously make manual management through the bol.com seller dashboard impractical at any meaningful scale.
Automated bol.com integration removes the manual work from the order processing loop — orders appear in the seller's OMS the moment they are placed, inventory updates propagate to bol.com automatically as stock levels change, and shipment confirmations are submitted to bol.com as part of the normal fulfilment workflow rather than as a separate manual step. The seller's team focuses on operational decisions rather than data entry, and bol.com's performance metrics benefit from the faster, more consistent processing that automation enables.
Bol.com Connected to Your Operations
Bol.com integrations built for the operational realities of Dutch e-commerce — correct OAuth authentication, robust asynchronous operation handling, reliable order and inventory synchronisation, and the monitoring that surfaces API issues before they cause fulfilment delays or performance metric degradation.