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, with your business rules, your general ledger accounts and your carriers.

Book an intake Technical details

// 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 would normally perform through the dashboard, such as confirming an order, adjusting stock or handling a return, can be carried out automatically from your own systems.

For low volumes, a pre-built connector from a marketplace tool is usually sufficient. But once you deal with multiple warehouses, multi-channel logistics, your own pricing rules or VAT complexity (NL + BE + OSS), you run into their limitations. A custom integration is then more efficient and cheaper in the long run.

We build that integration specifically for your ERP stack: whether that is 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 fits into your financial, logistics and marketing processes.

From intake to go-live in four steps

Discovery & scoping

We map out your current flow: which systems (ERP/WMS/PIM), which bol.com accounts (NL/BE), orders per day, and exception 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, product SKUs, customer data, VAT treatment for NL/BE. OAuth2 credentials and vault setup. A staging environment is set up at bol.com.

Build & iteration

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

Go-live & management

Soft launch with a limited number of products, monitoring of error rate and SLA. Full rollout once stable. SLA agreements on uptime, response time for incidents, and quarterly reviews for API version migrations.

Functionality we cover as standard

Order polling & webhooks

Orders are retrieved 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 ERP or WMS is pushed to bol.com via the Offers endpoint. For multi-warehouse setups 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) is held in configuration, so you can add new carriers without any code changes.

Commission fee processing

We link Bol.com commission invoices to the original order in your accounts, so you see your real margin per order. Splitting into general ledger accounts for marketplace fees, advertising fees and Bol.com logistics is possible.

Returns handling

Return notifications trigger credit flows in your ERP, stock re-entries and customer communication. Auto-accept for unhandled returns after a configurable period (default 14 days). Dashboards show return reasons and outliers.

Content & catalogue management

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

Typical integration scenarios

Multi-channel seller

Webshop (Shopware / Magento / custom) + bol.com + Amazon share one 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, dedicated item SKUs with 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 requires up-to-date content management. From Akeneo or Pimcore, we sync your 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 during peak loads (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 to Datadog or Grafana Loki, metrics to Prometheus, alerts on error rate and queue depth. You know within 5 minutes if bol.com is down or if your backend slows down.

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

Why Appfront?

Marketplace expertise

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 quickly or combine them.

ERP experience

Our team has live 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 we build around them.

A dedicated point of contact

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

Security & compliance

Your bol.com credentials are crown jewels: whoever holds them can change your orders, sabotage prices or zero out your stock. We handle 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, 90-day retention. IP whitelisting where possible. GDPR-compliant storage of customer data (name, address, email): encrypted at rest, retention per your policy, sub-processor agreements.

We preferably host within the EU (Hetzner, AWS eu-central-1, Azure West Europe) and carry out penetration tests where relevant to 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 sellers on bol.com handle their sales process programmatically. Instead of working manually through the Seller Dashboard, your own ERP or WMS retrieves orders, confirms them, registers shipments and processes returns. For sellers handling more than a few dozen orders a day, this integration is essential to stay scalable.

For which sellers is a custom integration worthwhile?

If you process more than 50 to 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 will hit the limits of off-the-shelf connectors. A custom integration gives you fine-grained control: you decide which offers are updated and when, how you handle stockouts, and how you post commission fees to your accounts.

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 logistics), Insights (performance and sales data), Invoices (commission invoices), Product Content (catalogue) and Replenishments. In most integrations we focus first on orders and offers, then shipments and returns, and finally content and insights.

How does authentication work (OAuth2)?

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 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 secret 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 they are exceeded. 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 in our system ensures that retries never create duplicate shipments.

Can you connect our bol.com integration to our Exact Online / Navision / SAP accounting?

Yes. We regularly connect bol.com to 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 run the other way. With multiple channels (your own webshop + bol), we make sure each channel hits its own general ledger accounts and dimensions.

What happens with a return or cancellation?

The API retrieves both cancellations (order not yet shipped) and returns (order already delivered) as events. In your ERP we create credit notes, book stock back in and, where needed, trigger a refund via your payment service provider. Unhandled returns are automatically accepted by bol.com after 14 days, so we set up dashboards and alerts to let your customer service respond to exceptions in time.

How long does an integration like this take?

A standard integration (orders, shipments and stock sync with one 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 followed by go-live with real orders. Extensive scenarios involving content sync, dynamic pricing or multi-warehouse logistics take 10-16 weeks. We work in sprints so you see working functionality every two weeks.

What do maintenance and monitoring cost after handover?

bol.com regularly changes its API versions (v8 → v9 → v10) with breaking changes, so after go-live we provide monitoring (error rate, latency, queue depth), quarterly reviews and migrations for new versions. Fixed monthly fees depend on volume and criticality: a starter package from a few hours a month covers alerting, which can be extended with feature development and new endpoints as needed.

Ready to genuinely scale your bol.com channel?

Schedule a no-obligation conversation. We'll review your current workflow and outline which integrations would deliver the most value.

Book an intake Call us directly on 085 401 1220

Current context (May 2026)

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

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