Retailer API: Complete Guide

The retailer API of bol.com is the backbone of every professional sales strategy on the platform. Whether you want to automate orders, synchronize inventory, or monitor competitor prices - the bol.com Retailer API makes it possible. In this comprehensive guide, we explain how the retailer API works, what possibilities you have, what it costs to build it yourself versus using a ready-made solution, and how to get the most out of the API integration.

What is the retailer API of bol.com?

The retailer API is a set of programming interfaces (APIs) that bol.com offers to sellers on the platform. Through this API, you as a seller can automate almost all actions that you normally perform manually in the sales portal via software. Think of retrieving orders, updating inventory and prices, confirming shipments, and requesting sales statistics. The official documentation can be found on developers.bol.com, where bol.com documents all available endpoints, authentication methods, and examples.

The Retailer API replaced the outdated Plaza API in 2020. The new API is built on modern REST principles with JSON responses, making integration easier than ever. Every seller with an active bol.com sales account can create API keys in the partner portal and get started right away.

The three APIs of bol.com explained

Bol.com offers not one but three separate APIs, each with a specific purpose. It's essential to understand which API you need for your use case, as the endpoints and authentication may vary per API.

1. Bol Offer API

The Offer API focuses on product management. With this, you can create, modify, and delete offers. You manage your assortment, prices, inventory levels, publication status, and delivery times with this API. When you sell thousands of products, the Offer API is indispensable for keeping your product data up-to-date without having to log in manually.

2. Bol Advertiser API

The Advertiser API provides access to the advertising system of bol.com. With this, you can create and manage Sponsored Products campaigns, set budgets, adjust bids, and request detailed reports on impressions, clicks, conversions, and ACOS values. For sellers who actively advertise on bol.com, this API is a powerful tool to automate and optimize campaigns.

3. Bol Retailer API

The Retailer API is the most comprehensive of the three and covers the entire operational sales process. With this, you retrieve orders, confirm shipments, manage returns, request commissions, and analyze competing offers. The Retailer API is the API that most sellers need for their daily business operations.

Retailer API endpoints and possibilities

The retailer API offers a wide range of endpoints that together cover the entire sales process. Below is an overview of the most important functionalities and their applications:

Endpoint category	Functionality	Example use case
Orders	Retrieve, send, cancel orders	Automatically generate shipping labels for new orders
Offers	Create, update, delete offers	Inventory synchronization with your own ERP system
Shipments	Confirm shipments, update track & trace	Link with PostNL or DHL for automatic updates
Returns	Retrieve and process returns	Automate return processing in your warehouse
Commissions	Retrieve commission percentages per product group	Profit calculation per product automated
Insights	Sales statistics and performance reports	Build dashboards with real-time sales data
Competitor Offers	Analyze competitor offers	Adjust pricing strategies based on competition
Inventory	Inventory management for LVB and own shipping	Automatic reordering when stock is low
Promotions	Manage promotional actions and bundles	Plan seasonal discount actions

Getting started with the retailer API: authentication and setup

To use the retailer API, you first need to create API credentials. This process works as follows:

Step 1: Generate API keys

Log in to your bol.com partner account and navigate to Settings → API settings. Here, you create a Client ID and Client Secret. Store these details securely - the Client Secret is only shown once.

Step 2: Obtain an OAuth 2.0 token

The Retailer API uses OAuth 2.0 for authentication. You send your Client ID and Client Secret to the token endpoint to receive an access token. This token is valid for a limited time (usually 5 minutes) and must be sent with every API call in the Authorization header.

Step 3: Respect rate limits

Bol.com enforces strict rate limits to protect the API servers. By default, you can make a maximum of 25 requests per second. If you exceed this, you'll receive a 429 Too Many Requests response. Always implement exponential backoff in your code to handle temporary errors.

Step 4: Test in the sandbox environment

Before going live, you can test your integration in the sandbox environment of bol.com. The sandbox simulates the production behavior of the API without affecting actual orders or offers. This is essential to prevent errors when launching your integration.

Build yourself or choose ready-made software?

This is the core question for every seller who wants to work with the retailer API. Building yourself sounds appealing - full control, custom-made, and no monthly subscription fees. But the reality is often more complex than expected. Let's compare both options honestly.

Option 1: Build your own software on the Retailer API

Building your own integration requires experienced developers with knowledge of REST APIs, OAuth 2.0 authentication, rate limiting, and error handling. The initial development usually takes 120 to 200 hours for basic functionality (order management, inventory synchronization, shipping confirmations). With an average hourly rate of €70-€100, you'll quickly end up with €8,400 to €20,000 for the first version.

In addition to this, you need to consider ongoing maintenance. Bol.com regularly updates the API with new versions, changed endpoints, and additional requirements. This requires an average of 6-10 hours per month of maintenance to keep your integration up-to-date and stable.

Option 2: Ready-to-use bol.com software

Platforms like Boloo offer ready-to-use integrations that work directly with the bol.com API. Without any technical knowledge, you get access to powerful tools for product research, sales analysis, ranking tracking, and more. The monthly costs are a fraction of what it would cost to build it yourself.

Cost comparison: building yourself vs. ready-to-use solution

Cost item	Building yourself	Ready-to-use software
Initial development	€8.400 – €20.000 (120-200 hours)	€0
Monthly maintenance	€420 – €1.000 (6-10 hours/month)	Included in subscription
Annual costs (year 1)	€13.440 – €32.000	€180 – €600
Annual costs (year 2+)	€5.040 – €12.000	€180 – €600
Total costs over 2 years	€18.480 – €44.000	€360 – €1.200
Time-to-market	2-4 months	The same day
Technical knowledge required	Yes (developer needed)	No
API updates	Self-responsible	Automatically updated

When do you choose to build your own API integration?

Although ready-to-use software is the best choice for most sellers, there are situations where building your own integration makes sense:

• Unique business processes: If you have very specific workflows that no standard software supports, such as a connection to a custom ERP or WMS system.
• High volume: With more than 10,000 orders per day, a custom solution can be more efficient than generic software.
• In-house development team: If you already have a software team that can build and maintain the integration without additional costs.
• Multiple marketplaces: When you sell on bol.com and other platforms like Amazon, Kaufland, or others, and want to build a central system.

Common mistakes in retailer API integrations

Based on our experience with thousands of bol.com sellers, we regularly see the same mistakes in API integrations:

1. Not handling rate limits correctly

Many developers don't build retry logic for 429 responses. This leads to missed orders and inventory problems. Always implement exponential backoff with jitter to catch rate limit errors.

2. No monitoring and alerting

An API integration without monitoring is like a car without a dashboard. You need to know when errors occur, when response times increase, and when the API is unavailable. Set up alerts for critical errors.

3. Insufficient error handling

The bol.com API can return various HTTP status codes (400, 401, 403, 404, 500, 503). Each status code requires a different handling. A generic try-catch is not enough - you need specific handlers for each error type.

4. Not fully automating manual processes

Some sellers only automate order retrieval but still manually confirm shipments or process returns. This limits the value of the integration significantly. Automate the entire process for maximum efficiency.

5. No sandbox tests for updates

With every change in your code or API updates from bol.com, you should first test in the sandbox. Deploying directly to production is a recipe for problems.

Best practices for a successful retailer API integration

Follow these best practices to get the most out of your API integration:

• Use webhooks where possible: Instead of constantly polling the API for new orders, use bol.com's push notifications to stay up-to-date in real-time with new events.
• Implement idempotent requests: Ensure that resending a request doesn't lead to duplicate actions (like duplicate shipment confirmations).
• Cache static data: Data that doesn't change often (like commission percentages) doesn't need to be fetched with every request. Cache this data locally and refresh periodically.
• Log all API interactions: Keep request and response logs for debugging and auditing. This is indispensable when tracking down problems.
• Version your integration: bol.com maintains multiple API versions at the same time. Always specify the API version in your requests and plan migrations to new versions in time.

How Boloo utilizes the retailer API

At Boloo, we use the bol.com Retailer API to offer sellers powerful tools without them having to program themselves. Our sales dashboard fetches real-time sales data via the Insights endpoints, the product tracker monitors competing offers, and the automatic invoicing processes order data to generate invoices.

By abstracting away API complexity, our users save thousands of euros in development costs and can focus on what really matters: selling successfully on bol.com. With over 1,700 active sellers, we know exactly which API features make a difference for growth and efficiency.

Frequently asked questions about the retailer API

Is the bol.com Retailer API free to use?

Yes, using the API itself is free for all bol.com sellers. You only pay the regular commission on your sales. The costs are in the development and maintenance of the software that accesses the API.

Do I need programming knowledge to use the API?

For direct API integration, you need knowledge of a programming language (Python, PHP, Node.js, Java, etc.) and REST API principles. Want to benefit from API functionality without programming knowledge? Use a ready-made tool like Boloo.

How long does it take to build an API integration?

A basic integration (order management + inventory synchronization) typically costs 120-200 development hours. A fully extended integration with all endpoints can take 300-500 hours. With ready-made software, you're operational the same day.

What happens if bol.com changes the API?

bol.com usually communicates API changes 3-6 months in advance via their developer portal. For breaking changes, you need to adjust your code. If you use software like Boloo, updates are automatically implemented.

Can I combine the Retailer API with the Advertiser API?

Yes, you can use all three APIs (Retailer, Offer, and Advertiser) at the same time with the same API credentials. This makes it possible to build a fully integrated system that automates both your sales and your advertisements.

Are there limits to the number of API calls?

Yes, bol.com has rate limits of up to 25 requests per second. For bulk operations (like updating thousands of products), bol.com offers special bulk endpoints that are more efficient than individual calls.