Retailer API v10 OAuth2 NL + BE

A Bol.com Seller API integration that actually scales

For professional sellers with their own ERP, WMS or PIM. Not a generic plug-in, but a custom integration that handles orders, stock, shipments and returns automatically, using your business rules, your general ledger accounts and your carriers.

// POST /orders/{id}/shipment
Authorization: "Bearer eyJhbGc..."
Accept: "application/vnd.retailer.v10+json"
 
{
"orderItems": [{...}],
"transport": {
"transporterCode": "TNT",
"trackAndTrace": "3SAB..."
  }
}

What exactly is a Bol.com Seller API integration?

Bol.com has two roles: seller (you, via the Seller Dashboard) and platform. The Retailer API is the bridge between the two: every action you normally take in the dashboard, such as confirming an order, adjusting stock or processing a return, can be done automatically from your own systems.

For small volumes, a pre-built connector from a marketplace tool is enough. But as soon as you deal with multiple warehouses, multi-channel logistics, your own pricing rules or VAT complexity (NL + BE + OSS), you hit their limits. At that point, a custom integration is more efficient and cheaper in the long run.

We build that integration specifically for your ERP stack, whether that's Exact Online, AFAS, Navision, SAP Business One, Microsoft Dynamics or a custom .NET application. The Retailer API itself is only the source: the value lies in how that data flows into your financial, logistics and marketing processes.

From intake to go-live in four steps

Discovery & scoping

We map your current flow: which systems (ERP/WMS/PIM), which bol.com accounts (NL/BE), orders per day, edge cases (LVB, bol.com Plus, dropshipping). Result: an RFC with architecture and prioritisation.

Technical design

Data mapping between bol.com entities and your ERP/WMS schema: order states, item SKUs, customer data, NL/BE VAT treatment. OAuth2 credentials and vault setup. A staging environment is set up with bol.com.

Build and iteration

The integration is built in Node.js or .NET (depending on your stack) with a queue-based architecture. Two-week sprints: orders first, then shipments, stock, returns and content. Dashboards in Grafana or Datadog for monitoring.

Go-live & maintenance

Soft launch with a limited set of products, monitoring error rate and SLA. Once stable, we roll out in full. SLA agreements cover uptime, response times for incidents and quarterly reviews for API version migrations.

Functionality we cover as standard

Order polling & webhooks

Orders are fetched every X minutes or processed in real time via the announced webhooks. We prevent duplicates with idempotency keys and a local staging layer that validates orders before they land in your ERP.

Stock sync ERP ↔ bol

Your master stock in the ERP or WMS is pushed to bol.com via the Offers endpoint. With multiple warehouses, we respect your allocation rules, e.g. 80% to bol.com and a 20% buffer for your own webshop.

Shipments & track & trace

After pick & pack in your WMS, we register shipments with track & trace codes at bol.com. Carrier mapping (PostNL, DHL, DPD, UPS) lives in config, so you can add new carriers without code changes.

Commission fee processing

We match bol.com commission invoices to the original order in your accounting, so you see real margins per order. Splitting across general ledger accounts for marketplace fee, advertising fee and bol.com logistics is possible.

Returns handling

Return notifications trigger credit flows in your ERP, stock rebookings and customer communication. Unprocessed returns are auto-accepted after a configurable period (default 14 days). Dashboards show return reasons and outliers.

Content & catalogue management

You sync product descriptions, images, specifications and EAN links from your PIM (Akeneo, Pimcore, Shopware) to bol.com via the Content endpoint. Changes are sent as deltas to conserve quota.

Typical integration scenarios

Multi-channel seller

Your webshop (Shopware / Magento / custom), bol.com and Amazon share a single stock pool in your WMS. Our middleware allocates stock per channel according to your rules and prevents overselling with a real-time lock.

Traditional wholesaler adding bol.com

You have always sold B2B through your ERP and now want to sell B2C on bol.com. We set up a separate division in your ERP, with dedicated article SKUs, bol.com-specific descriptions and a separate VAT flow.

Dropshipping via supplier feeds

Your stock comes from external suppliers (via EDI, API or daily FTP). We aggregate those feeds and push them to bol.com, with configurable buffers and exclusion rules for supplier outages.

Private label with PIM sync

Your own brand needs up-to-date content management. From Akeneo or Pimcore, you sync product descriptions, rich content and variants to bol.com via the Content endpoint. Delta sync avoids unnecessary API calls.

Technical stack and architecture

Core endpoints we use

GET /retailer/orders
PUT /retailer/orders/{orderItemId}/shipment
POST /retailer/offers
PUT /retailer/offers/{offerId}/stock
GET /retailer/returns
POST /retailer/returns/{rmaId}/handle
GET /retailer/insights/offer
GET /retailer/invoices

Architecture principles

Queue-based: every API call is a message in RabbitMQ or AWS SQS. Workers are stateless and can scale horizontally under peak load (such as Black Friday).

Idempotent: every operation (shipment, offer update) has an idempotency key based on your order ID or SKU. Retries after timeouts never create duplicates.

Observability: logs go to Datadog or Grafana Loki, metrics to Prometheus, with alerts on error rate and queue depth. Within 5 minutes you know if bol.com is down or if your backend is slowing down.

Secret management: client_id and client_secret are kept in a vault (HashiCorp, AWS Secrets Manager). Never in your repo or environment files.

Why Appfront?

Marketplace knowledge

We know not only bol.com but also Amazon (SP-API), Marktplaats Pro and Beslist. The concepts (seller APIs, commission models, returns logic) are similar enough to switch or combine quickly.

ERP experience

Our team has production integrations with Exact Online, AFAS, Navision, SAP and Dynamics. We know where the data models cause friction (VAT in NL vs BE, administration splits) and build around it.

A single point of contact

No team changes or offshore handovers. The developer who builds your integration is also the one who handles incidents after go-live. Short communication loops, no tickets that get lost.

Security & compliance

Your bol.com credentials are the crown jewels: anyone who has them can change your orders, sabotage your prices or zero your stock. We treat them with the care they deserve.

Secret storage in a dedicated vault (HashiCorp Vault or AWS Secrets Manager), never in your codebase or .env files. Audit logs on all API calls, retained for 90 days. IP whitelisting where possible. GDPR-compliant storage of customer data (name, address, email): encrypted at rest, retention according to your policy, sub-processor agreements.

We prefer to host within the EU (Hetzner, AWS eu-central-1, Azure West Europe) and run pentests where relevant for your sector.

Frequently asked questions

What exactly is the Bol.com Retailer API?
The Bol.com Retailer API (currently v10) is the official REST interface that lets bol.com sellers handle their sales process programmatically. Instead of working manually in the Seller Dashboard, your own ERP or WMS retrieves orders, confirms them, registers shipments and processes returns. For sellers with more than a few dozen orders a day, this integration is essential to keep scaling.
Which sellers benefit from a custom integration?
If you handle more than 50-100 orders a day, sell across multiple channels (your own webshop + bol.com + Amazon), or have specific stock logic (multiple warehouses, dropshipping, pre-orders), you'll hit the limits of off-the-shelf connectors. Custom integrations give you fine-grained control: you decide which offers are updated and when, how you handle stockouts, and how commission fees are posted to your accounting.
Which endpoints and entities do we cover?
The Retailer API has resources for Orders (retrieve, ship, cancel), Shipments (create, transport labels), Returns (retrieve, handled/unhandled), Offers (CRUD on price/stock/delivery), Inventory (LVB stock for bol.com fulfilment), Insights (performance and sales data), Invoices (commission invoices), Product Content (catalogue) and Replenishments. In most integrations we focus on orders and offers first, then shipments and returns, and content and insights last.
How does authentication (OAuth2) work?
Bol.com uses the OAuth2 client-credentials flow. You register an API account in the Seller Dashboard, receive a client_id and client_secret, and exchange them at `/token` for an access token that is valid for 299 seconds. Every API call uses a `Bearer` header plus an Accept header for the version (`application/vnd.retailer.v10+json`). We handle token refresh and secrets management (preferably via a vault).
How do you handle rate limits?
Bol.com applies rate limits per endpoint and returns a `Retry-After` header when you exceed them. We implement exponential backoff with jitter, queue-based worker pools (e.g. RabbitMQ or AWS SQS) and batching where possible. For offer updates we use the bulk endpoint rather than single-offer calls to conserve quota. Idempotency on our side ensures retries never create duplicate shipments.
Can you connect our bol.com integration to our Exact Online / Navision / SAP accounting?
Yes. We regularly integrate bol.com with Exact Online, Navision, SAP Business One, AFAS Profit and Microsoft Dynamics 365. Orders flow from bol.com into the ERP as sales orders or directly as invoices, and bol.com commission invoices are booked as purchase invoices. Stock movements flow the other way. With multiple channels (your own webshop + bol.com), we make sure each channel hits its own ledger accounts/dimensions.
What happens with a return or cancellation?
Both cancellations (order not yet shipped) and returns (order already delivered) are retrieved from the API as events. In your ERP we create credit notes, restock inventory and, if needed, trigger a refund via your PSP. Unhandled returns are automatically accepted by bol.com after 14 days, so we set up dashboards/alerts that allow your customer service team to respond to exceptions in time.
How long does an integration like this take?
A standard integration (orders + shipments + stock sync with a single ERP or WMS) usually takes 4-8 weeks: 1-2 weeks of discovery and mapping, 3-4 weeks of development, and 1-2 weeks of testing in a staging environment and going live with real orders. More extensive scenarios with content sync, dynamic pricing or multiple warehouses take 10-16 weeks. We work in sprints, so you see working functionality every two weeks.
What do maintenance and monitoring cost after delivery?
Bol.com regularly changes its API versions (v8 → v9 → v10) with breaking changes, so after go-live we handle monitoring (error rate, latency, queue depth), quarterly reviews and migrations to new versions. We charge fixed monthly fees depending on volume and criticality. A starter package begins at a few hours a month for alerting, and can be extended with feature development and new endpoints as needed.

Ready to truly scale your bol.com channel?

Schedule a no-obligation conversation. We'll look at your current flow and outline which integrations will deliver the most value.

Current context (May 2026)

REST architecture has become the de facto standard for web APIs, based on stateless HTTP requests and resource-oriented URLs — a pattern that Roy Fielding defined in his dissertation in 2000.

Source: MDN Web Docs — REST (developer.mozilla.org)

Edit content