The BOL.com connector integrates the app with bol.com, the leading marketplace in the Netherlands and Belgium. It uses the BOL.com Retailer API v10 and Offers API v11, authenticating with OAuth2 client credentials.
The connector pulls orders and returns from bol.com and pushes fulfillments, inventory levels, and price updates back, on a 5-minute sync cycle. Like Amazon, BOL.com distinguishes items fulfilled by the retailer (FBR) from items fulfilled by bol.com itself (FBB), and a single order can mix both. By default the connector pulls FBR orders — the ones you deliver — but it can be configured to pull FBB orders or both, and mixed orders are handled per line item: only the FBR lines are routed for fulfillment.
Key capabilities:
- Pull new and updated orders from BOL.com — FBR, FBB, or both — including cancellations and synthesized refunds
- Push shipment confirmations with tracking numbers back to BOL.com for FBR orders
- Push inventory levels to BOL.com offer stock
- Push product price updates to BOL.com offers
- Pull handled customer returns (RMAs), with an option to report received returns back to BOL.com
Setup
Before you begin:
- You need a BOL.com retailer account with access to the Seller Dashboard.
- Your API credentials must include read access to offers — the connector uses it to resolve SKUs and to match return lines to your products.
- BOL.com publishes a detailed guide on creating API credentials; follow it if you have not created credentials before.
To set up the connector:
- Log in to your BOL.com Seller Dashboard.
- Navigate to API Instellingen (API Settings) and create API credentials.
- Add the BOL.com connector in the app.
- Enter your Client ID and Client Secret in the connection settings.
- Save the connection.
- Enable the flows you need — orders, fulfillments, inventory, products, and returns are all off by default.
The connector creates a single location in the app for the integration, named BOL.com - DEFAULT by default. You can rename it — the connector identifies it by its external ID, not its name. bol.com has no warehouse or locations API on the retailer side, so the connector creates only this one location; you can still create other locations in the app, and the Push inventory from a specific location only setting can point at any of them.
SKU matching: the app's SKUs are matched to BOL.com through the offer reference field. BOL.com maintains a shared product catalog (by EAN) that is the same for every retailer; each retailer sells through their own offers on those products, and the offer's reference field holds the retailer's internal identifier. Your SKU in the app must equal the offer reference in BOL.com — this is what products and inventory sync key on. Fill in the reference on your BOL.com offers before enabling those flows.
Settings
The BOL.com Settings page groups settings by flow. Click Save to apply changes, or Restore Defaults to reset the page.
| Setting | Description | Options/Default |
|---|---|---|
| Exclude orders created before this date (Orders) | Pull only orders changed after this date. BOL.com keeps order history for 3 months, so an earlier date has no effect. Because the filter matches last-changed time rather than creation time, an older order is pulled if it has been modified recently — and to pull a past order after sync has begun, modify it in BOL.com to trigger its pull. | Default: integration creation date |
| Order fulfilment method to sync (Orders) | Which fulfilment method orders to pull. FBR = fulfilled by you, FBB = fulfilled by BOL.com. Select All to sync both flows. | Default: FBR only (Fulfillment by Retailer) |
| Process only orders and fulfillments with specific order IDs (Orders) | When set, the connector fetches these order IDs directly and ignores integration sync state. Intended for onboarding and testing. | Empty by default (all orders) |
| Only allow order updates for orders with a matching Pipe17 status (Orders) | When an order changes on the BOL.com side, the app pulls the update but applies it only if the order's status in the app is in this list. One exception: if the change includes a new cancellation, it is applied regardless of status — a cancellation after fulfillment is a refund, and refunds are always recorded. | Default: draft, new, onHold, toBeValidated, reviewRequired, readyForFulfillment |
| Process only Products with specific SKUs (Products) | Push price updates only for these SKUs. The filter matches your SKUs in the app (which equal BOL.com offer references). Supports regex (for example, /^978.*/i). Trigger a product resync after changing this setting. |
Empty by default (all products) |
| Force product resync (Products) | Triggers a full product price resync; the switch turns off automatically after the sync starts. Use with caution on large catalogs — a full resync pushes every product price. | Disabled by default |
| Push inventory from a specific location only (Inventory) | By default, inventory totals across all active locations are pushed to BOL. Select a location to push stock from that location only. BOL.com has a single stock level per offer, so most retailers leave this empty. | Default: all locations (totals) |
| Process only inventory items with specific SKUs (Inventory) | Push inventory only for these SKUs. The filter matches your SKUs in the app (which equal BOL.com offer references). Supports regex. Trigger an inventory resync after changing this setting. | Empty by default (all inventory) |
| Force inventory resync (Inventory) | Triggers a full inventory resync; the switch turns off automatically after the sync starts. | Disabled by default |
| Returns fulfilment method to sync (Returns) | Which fulfilment method returns to pull. FBR = fulfilled by you (returns land at your 3PL), FBB = fulfilled by BOL.com (BOL receives the return). Select All to sync both — each method uses its own status set below. | Default: FBR only (Fulfillment by Retailer) |
| FBR return statuses to ingest (Returns) | Which FBR return dispositions to pull. The default is the receipt-expecting set — goods physically coming back to your 3PL. Add others (for example, STILL_APPROVED) to mirror returns earlier; they come in as ordinary pre-receipt returns, and your 3PL still owns the receipt that advances them to received. | Default: RETURN_RECEIVED, EXCHANGE_PRODUCT, EXCESSIVE_RETURN, STILL_RECEIVED |
| FBB return statuses to ingest (Returns) | Which FBB return dispositions to pull for visibility. BOL.com receives FBB returns, never your 3PL, so this is a visibility mirror. Empty means FBB ingests nothing until you choose statuses. | Default: empty (FBB ingests nothing until statuses are chosen) |
| Report received returns back to BOL.com (Returns) | When your 3PL receives an FBR return, report the received quantity and disposition back to BOL.com. FBB returns are received by BOL.com and are never reported back. | Disabled by default |
| Exclude returns processed before this date (Returns) | Only pull returns processed after this date. | Default: integration creation date |
Flows
| Flow | Direction | Notes |
|---|---|---|
| Orders | BOL.com → Pipe17 | Polled every 5 minutes. FBR orders only by default. Line items carry the BOL.com order item ID, which the fulfillment flow requires for the round trip. BOL.com omits billing details from orders older than 30 days (GDPR), and order history is available for 3 months. |
| Refunds | BOL.com → Pipe17 | Part of order sync, not a separate flow — there is no Refunds switch. BOL.com has no separate refunds endpoint, so the app derives refunds from the order itself: any line with a cancelled quantity is recorded as a refund on the order, refreshed on every order update. |
| Fulfillments | Pipe17 → BOL.com | Shipment confirmations with tracking numbers, for FBR orders. Confirmation is asynchronous: BOL.com accepts the shipment and the app verifies the result on a later cycle, so a fulfillment showing as in flight for a few minutes is normal. BOL.com accepts one tracking number per shipment, so each fulfillment in the app becomes a separate BOL.com shipment — model split shipments as separate fulfillments. The default mapping translates common carrier codes (PostNL, DHL-DE, DHL-for-you, DPD, FedEx, bpost) to BOL.com transporter codes. A plain DHL carrier is not mapped — use DHL-DE or DHL-FOR-YOU. Other carriers can be added in a custom mapping. |
| Inventory | Pipe17 → BOL.com | Pushes stock levels to BOL.com offer stock (FBR offers only — FBB stock is managed by BOL.com). Totals across all locations by default, or a single location per the setting. The default mapping does not send the managedByRetailer flag, so BOL.com applies its own default when computing corrected stock. The flag controls how BOL.com nets open orders against the pushed amount — false: BOL.com subtracts its open orders from it; true: only orders placed after the update count. To set it explicitly, add it in a custom mapping. |
| Products | Pipe17 → BOL.com | Price updates only, applied to the matching offer. Prices are EUR, VAT-inclusive. Existing offers only — the connector does not create offers, and title, description, and images stay managed in BOL.com. This flow is price-driven: a product with no EUR price raises an exception, and a product whose price is unchanged is skipped without a call to BOL.com. Custom mappings that set other offer fields only take effect alongside a price change. |
| Returns | Bidirectional | Pulls handled returns — those BOL.com has already given a resolution — as RMAs. Returns are re-checked over a rolling 30-day window from registration; a return whose status changes later than that is not picked up again. With Report received returns back to BOL.com enabled, receipt of an FBR return at your 3PL is reported back to BOL.com with the received quantity and disposition. |
| Locations | BOL.com → Pipe17 | A single virtual location, named BOL.com - DEFAULT by default (renameable — the connector identifies it by external ID), since bol.com has no retailer-side warehouse API. |
The connector also supports integration actions to pull a specific order or return from BOL.com by ID on demand, and to backfill orders by date — useful when records need to be re-fetched without waiting for the poll cycle or adjusting filters.
Troubleshooting
-
Inventory or price updates are skipped for some SKUs
The SKU has no matching FBR offer in BOL.com. The app resolves offers by the offer's reference field, so the SKU in the app must equal the offer reference exactly. Fill in the reference on the BOL.com offer, or correct the SKU. FBB offers are excluded — BOL.com manages that stock. -
A product price push raises an exception about a missing price
The product has no EUR price. BOL.com prices are EUR and VAT-inclusive; the connector will not push a price in another currency or fall back to cost. Add a EUR price to the product and edit it to trigger a new push. -
An order changed in BOL.com but was not updated in the app
The order's status in the app is not in the Only allow order updates for orders with a matching Pipe17 status list. Orders that have progressed past the listed statuses (for example, already sent to fulfillment) are intentionally not overwritten. Add the status to the list if you want such orders updated. This does not apply to cancellations — those are always applied, and raise a Late cancellation exception so you can review the order. -
Older orders are not pulling in
BOL.com only provides order history for the past 3 months, so dates earlier than that have no effect. The date filter also matches when an order last changed, not when it was created — so to pull a past order, modify it in BOL.com to trigger its pull, use the backfill-orders-by-date integration action, or pull it by ID. -
A shipment confirmation seems stuck or was rejected
Shipment confirmation is asynchronous — BOL.com accepts the shipment and the app confirms the result a cycle later, so a few minutes in flight is normal, not a stall. If the same fulfillment was submitted twice (for example, after a timeout), the duplicate raises a harmless extra exception that is safe to dismiss — the shipment itself is fine. An actual rejection is usually an unrecognized carrier: the default mapping translates common carrier codes and passes anything else through as-is, which BOL.com rejects if it is not a valid code (note that plainDHLis not mapped — useDHL-DEorDHL-FOR-YOU). Also check that the fulfillment carries a single tracking number — BOL.com accepts one per shipment, and only the first is sent. -
Return line items do not match your products
BOL.com return payloads identify items by EAN. The connector resolves EANs to your SKUs (offer references) automatically; mismatches occur when no offer with a matching EAN exists in your BOL.com account — add or correct the offer for that EAN to resolve the line items. If every return line shows a barcode instead of a SKU, the cause is usually the API credentials rather than the catalog: the connector needs read access to offers. Check the scope on your BOL.com credentials and re-save the connection.
Need Help?
If you need additional assistance:
- Use Ask Pippen, our AI agent, located at the top of the app page.
- Submit a support request with as much relevant detail as possible. Learn how to submit a request.
We're here to help you succeed with your operations.
Comments
0 comments