← Back to EcomCentral
BOL.COM RETAILER API v10

Bol.com Setup Guide

Connect your Bol.com seller account to EcomCentral using the Retailer API v10 with OAuth2 client credentials flow.

Prerequisites

ℹ️ Bol.com uses OAuth2 client credentials flow — no user authorization redirect is needed. EcomCentral acquires a token automatically using your client_id and client_secret via POST https://login.bol.com/token?grant_type=client_credentials.

Getting Your API Credentials

  1. Log in to the Bol.com seller portal and go to Settings → API Credentials (or navigate to the Bol.com Developer Portal)
  2. Click Create new API credentials
  3. Give your app a name and enable the required scopes: Orders (read/write) and Offers/Inventory (read/write)
  4. Save — you will see a Client ID and Client Secret. Copy both; the secret is only shown once
  5. In EcomCentral, add a new Bol.com connection and enter both values
  6. Click ⚡ Test — a successful OAuth token acquisition confirms the credentials work
⚠️ The Client Secret is shown only once at creation time. Store it securely — if lost you must regenerate new credentials.

Credentials Reference

KeyRequiredDescriptionExample
client_id Required OAuth2 Client ID from the Bol.com Developer Portal xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
client_secret Required OAuth2 Client Secret (shown only once at creation) secret_xxxxx…
sandbox Optional Set to true to use the shared demo environment (/retailer-demo) false
✅ Alternative key names: clientId / clientSecret are also accepted.

API Endpoints Used

OperationMethodEndpoint
Test connection (get token)POSThttps://login.bol.com/token?grant_type=client_credentials
List ordersGET/retailer/orders?page=P&status=ALL
Order detailGET/retailer/orders/{order-id}
Create shipment (tracking)POST/retailer/shipments
FBB inventoryGET/retailer/inventory?page=P
Update offer stockPUT/retailer/offers/{offer-id}/stock
Get offerGET/retailer/offers/{offer-id}
ℹ️ All requests use vendor media types: Accept: application/vnd.retailer.v10+json and Content-Type: application/vnd.retailer.v10+json. EcomCentral sets these automatically.

Transporter Codes (Carriers)

When adding tracking via the API, a Bol.com-specific transporter code is required. The EcomCentral tracking form provides a dropdown with common codes:

POSTNL
DHL
DHLFORYOU
TNT
UPS
DPD
GLS
BPOST
TRUNKRS
CYCLOON
FIEGE
PACKS
OTHER
✅ Use OTHER for carriers not in the list. Check the Bol.com Retailer API documentation for the full and up-to-date list of transporterCode values.

Supported Features

FeatureSupportedNotes
View orders (paginated)✅Order ID, date, first item fulfilment status (list endpoint is lean — no total price)
View order detail✅Customer, billing & shipping address, all order items with price, commission, fulfilment method
Add tracking / create shipment✅Bol.com transporter code + track & trace number. Async: returns 202 + processStatusId
View FBB inventory✅EAN, title, regular FBB stock. FBR offers are not included
Update offer stock✅Requires offer UUID (not EAN). Async 202 response.
Test connection✅Successful OAuth2 token acquisition confirms credentials
View all offers (products)❌Bol.com offers list is async (CSV export only) — not suitable for real-time paged display. FBB inventory is used instead.
⚠️ Stock updates require the offer UUID. Bol.com's stock-update endpoint is keyed by offerId (a UUID), not the EAN. Find your offer IDs in the Bol.com seller dashboard under Manage Offers or via the API offers export.
⚠️ Shipment creation is asynchronous. A 202 Accepted response means Bol.com has queued the request. The actual shipment is processed within seconds; check the Bol.com portal if you need confirmation.

Order Item Fulfilment Statuses

StatusMeaning
OPENOrder item received; awaiting shipment
HANDLINGBeing processed at Bol.com (FBB only)
SHIPPEDShipment created and tracking submitted
CANCELLEDFully cancelled by buyer or retailer
PARTIALLY_CANCELLEDOnly part of the quantity was cancelled
EXPIREDDelivery deadline passed without shipment

Troubleshooting

✕ 401 Unauthorized on token endpoint

The client_id or client_secret is incorrect. Verify both in the Bol.com Developer Portal. If the secret was lost, regenerate and update via Rotate Keys.

✕ Shipment creation fails — "no shippable items"

The order must have at least one item with a valid orderItemId. Orders in CANCELLED or SHIPPED status cannot receive new shipments.

✕ Stock update fails with 4xx

Ensure you are using the offer UUID, not an EAN or SKU. The offer UUID looks like xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Passing an EAN will result in a 404 from Bol.com's API.

✕ FBB inventory is empty

The /retailer/inventory endpoint only returns stock held in Bol.com fulfilment centres (FBB). If you fulfil orders yourself (FBR), your offers will not appear here — use the Bol.com offer export instead.