bol.com
App · 20 actions
Run your bol.com shop: follow and ship orders, cancel items, handle returns, create offers and set their prices and stock, check competing offers, and start workflows on new orders and returns.
Actions
| Action | What it does |
|---|---|
| Cancel order item | Cancel an order item you can't deliver, or accept a customer's request to cancel it. |
| Create offer | Offer a product for sale on bol.com: its price, condition, stock and delivery time. |
| Delete offer | Take an offer off bol.com for good. |
| Get my seller account | Get the bol.com seller account the connection acts for: its name, company, VAT and KvK numbers, and its customer ratings. |
| Get offer | Get one offer with its price, stock, delivery time, and whether it is for sale in each country. |
| Get order | Get one order with its items, prices, commission, delivery dates and the customer's shipping and billing details. |
| Get process status | Check whether a shipment, cancellation or return bol.com was still processing has finished, and how. |
| Get return | Get one return with each returned item (its rmaId), the customer's reason and how it was handled. |
| Get shipment | Get one shipment with its items, carrier, tracking code and where the parcel is now. |
| Handle a return | Say how a returned item was handled, or change an earlier answer. |
| List competing offers | List every seller's offer for a product, yours included, with its price, condition and delivery dates, and which is the best offer. |
| List offers | List your offers, filtered by EAN, your reference, whether they're for sale, or when they last changed. |
| List orders | List orders, newest first: open ones, or those shipped or cancelled in the last 48 hours. |
| List returns | List customer returns, those waiting for you to handle or those already handled. |
| List shipments | List shipments from the last three months, newest first, or those of one order. |
| Register a return | Register a return a customer sent back without announcing it, and say how it was handled. |
| Set offer price | Set an offer's price. |
| Set offer stock | Set how many of an offer you have in stock. |
| Ship order items | Tell bol.com that items of an order have shipped, with the carrier and tracking code or a bol.com shipping label. |
| Update offer | Change an offer's reference, countries, pause, title, economic operator or delivery time. |
Cancel order item
Cancel an order item you can't deliver, or accept a customer's request to cancel it. Waits for bol.com to confirm it.
Inputs
- Order item ID
order_item_idtextRequired - The order item's id (orderItemId), from 'Get order' or the order trigger.
- Reason
reason_codetextRequired - Why it is cancelled. Use Requested by the customer to accept their request.One of:
OUT_OF_STOCK(Out of stock),REQUESTED_BY_CUSTOMER(Requested by the customer),BAD_CONDITION(Bad condition),HIGHER_SHIPCOST(Higher shipping cost),INCORRECT_PRICE(Incorrect price),NOT_AVAIL_IN_TIME(Not available in time),NO_BOL_GUARANTEE(No bol.com guarantee),ORDERED_TWICE(Ordered twice),RETAIN_ITEM(Keeping the item),TECH_ISSUE(Technical issue),UNFINDABLE_ITEM(Item can't be found),OTHER.
Outputs
descriptiontext- bol.com's description of it
entity_idtext- What it changed: an order item id, or a new return's id
error_messagetext- Why it failed, empty unless it did
event_typetext- What kind of change it was
finishedtrue/false- Whether bol.com has finished processing it
process_statusobject- bol.com's process status
process_status_idtext- The id to follow the change with in 'Get process status'
statustext- PENDING, SUCCESS, FAILURE or TIMEOUT
Example output
{
"description": "Cancel order item 2012345678.",
"entity_id": "2012345678",
"error_message": "",
"event_type": "CANCEL_ORDER",
"finished": true,
"process_status": {
"createTimestamp": "2026-11-02T13:00:00+01:00",
"description": "Cancel order item 2012345678.",
"entityId": "2012345678",
"errorMessage": "",
"eventType": "CANCEL_ORDER",
"links": [
{
"href": "https://api.bol.com/shared/process-status/1234567",
"method": "GET",
"rel": "self"
}
],
"processStatusId": "1234567",
"status": "SUCCESS"
},
"process_status_id": "1234567",
"status": "SUCCESS"
}Create offer
Offer a product for sale on bol.com: its price, condition, stock and delivery time. bol.com then checks it before it goes on sale.
Inputs
- EAN
eantextRequired - The product's EAN (barcode number) or ISBN.
- Price (EUR)
pricenumberRequired - The price in euros including VAT, between 1 and 9999, like 19.99.From 1 to 9999.
- Condition
conditiontextRequired - New, second-hand or refurbished.One of:
NEW,SECONDHAND(Second-hand),REFURBISHED. - State
secondhand_statetext - How used it is.Only when Condition is Second-hand. One of:
AS_NEW(As new),GOOD,REASONABLE,MODERATE. - Condition notes
condition_commenttext - Such as 'scratch on the side' (no email addresses).Only when Condition is Second-hand.
- Grade
refurbished_gradetext - The refurbished quality grade.Only when Condition is Refurbished. One of:
A(A: near-mint),B(B: light scratches),C(C: visible wear). - Margin scheme
margin_schemetrue/false - Turn on if VAT was already paid on this item, so it is sold under the margin scheme.Only when Condition is Refurbished.
- Shipped by
fulfilment_methodtextRequired - Whether you ship orders, or bol.com does from its warehouse.One of:
FBR(Shipped by you),FBB(Shipped by bol.com (Logistics via bol)). - Delivery time from
delivery_scheduletext - When you ship it: one of bol.com's delivery times, your own delivery profile, or Shipping via bol.Only when Shipped by is Shipped by you. One of:
BOL_DELIVERY_PROMISE(A bol.com delivery time),MY_DELIVERY_PROMISE(My own delivery profile),SHIPPING_VIA_BOL(Shipping via bol). - Delivery time
delivery_promisetext - How fast the customer gets it.Only when Delivery time from is A bol.com delivery time. One of:
0-1-12(Next day if ordered by 12:00),0-1-13(Next day if ordered by 13:00),0-1-14(Next day if ordered by 14:00),0-1-15(Next day if ordered by 15:00),0-1-16(Next day if ordered by 16:00),0-1-17(Next day if ordered by 17:00),0-1-18(Next day if ordered by 18:00),0-1-19(Next day if ordered by 19:00),0-1-20(Next day if ordered by 20:00),0-1-21(Next day if ordered by 21:00), and 7 more. - Delivery profile ID
delivery_profile_idtext - The id of your delivery profile. Leave empty for your default one.Only when Delivery time from is My own delivery profile.
- Stock
stock_amountnumber - How many you have in stock, 0 to 999.Only when Shipped by is Shipped by you. From 0 to 999.
- I keep the stock count myself
stock_managed_by_retailertrue/false - Turn on if you lower the stock yourself as orders come in. Off, bol.com sets aside stock for open orders so you don't oversell.
- Sell in
countrieslist - The countries to sell it in. Leave empty for your account's default country.One or more of:
NL(Netherlands),BE(Belgium). - Your reference
referencetext - Your own code for the offer, such as your SKU (up to 100 characters).
- Title for an unknown product
unknown_product_titletext - A title to find the offer by when bol.com doesn't know the EAN yet. Ignored for products bol.com knows.
- Economic operator ID
economic_operator_idtext - The id of the product's responsible economic operator in the EU, from the Seller Dashboard. The offer goes on sale only once it has one.
- Paused
on_holdtrue/false - Pause the offer so it isn't shown for sale, without deleting it.
Outputs
offer_idtext- The new offer's id
Example output
{
"offer_id": "6ff736b5-cdd0-4150-8c67-78269ee986f5"
}Delete offer
Take an offer off bol.com for good.
Inputs
- Offer
offer_idtextRequired - The offer. Pick one, or give its id from an earlier step.
Outputs
deletedtrue/false- True once it is deleted
offer_idtext- The deleted offer's id
Example output
{
"deleted": true,
"offer_id": "6ff736b5-cdd0-4150-8c67-78269ee986f5"
}Get my seller account
Get the bol.com seller account the connection acts for: its name, company, VAT and KvK numbers, and its customer ratings.
Inputs
None.
Outputs
retailerobject- The seller account
Example output
{
"retailer": {
"companyName": "Fietsentuin B.V.",
"displayName": "Fietsentuin",
"kvkNumber": "90005414",
"ratingMethod": "THREE_MONTHS",
"registrationDate": "2015-06-17",
"retailerId": "1055479",
"retailerRating": {
"deliveryTimeRating": 9.4,
"productInformationRating": 9.6,
"retailerRating": 9.1,
"serviceRating": 9.4,
"shippingRating": 9.4
},
"retailerReview": {
"approvalPercentage": 100,
"negativeReviewCount": 0,
"neutralReviewCount": 1,
"positiveReviewCount": 13,
"totalReviewCount": 14
},
"topRetailer": false,
"vatNumber": "NL123456789B01"
}
}Get offer
Get one offer with its price, stock, delivery time, and whether it is for sale in each country.
Inputs
- Offer
offer_idtextRequired - The offer. Pick one, or give its id from an earlier step.
Outputs
offerobject- The offer
Example output
{
"offer": {
"condition": {
"category": "NEW",
"comment": "",
"grade": "",
"margin": false,
"state": ""
},
"countryAvailabilities": [
{
"countryCode": "NL",
"forSale": true
}
],
"ean": "9789076174082",
"economicOperatorId": "",
"fulfilment": {
"deliveryPromise": {
"maximumDaysToCustomer": 2,
"minimumDaysToCustomer": 1,
"ultimateOrderTime": ""
},
"method": "FBR",
"profileId": "",
"schedule": "BOL_DELIVERY_PROMISE"
},
"lastModifiedDateTime": "2026-11-02T08:34:41+01:00",
"offerId": "6ff736b5-cdd0-4150-8c67-78269ee986f5",
"onHoldByRetailer": false,
"pricing": {
"bundlePrices": [
{
"quantity": 1,
"unitPrice": 19.99
}
]
},
"product": {
"bolProductId": "9200000045327288"
},
"reference": "SKU-1001",
"stock": {
"amount": 6,
"correctedStock": 5,
"managedByRetailer": false
},
"unknownProductTitle": ""
}
}Get order
Get one order with its items, prices, commission, delivery dates and the customer's shipping and billing details.
Inputs
- Order ID
order_idtextRequired - The order's id, from 'List orders', a trigger or an earlier step.
Outputs
orderobject- The order
Example output
{
"order": {
"billingDetails": {
"city": "Utrecht",
"company": "",
"countryCode": "NL",
"deliveryPhoneNumber": "",
"email": "2ixm3kr4rrbxl4zcsyxtfh5zt7lqsg@verkopen.bol.com",
"extraAddressInformation": "",
"firstName": "Billie",
"houseNumber": "1",
"houseNumberExtension": "",
"kvkNumber": "",
"language": "nl",
"orderReference": "",
"pickupPointName": "",
"salutation": "FEMALE",
"streetName": "Dorpstraat",
"surname": "Jansen",
"vatNumber": "",
"zipCode": "1111ZZ"
},
"orderId": "A2K8290LP8",
"orderItems": [
{
"additionalServices": [],
"cancellationRequest": false,
"commission": 3.15,
"discounts": [],
"fulfilment": {
"distributionParty": "RETAILER",
"exactDeliveryDate": "",
"expiryDate": "2026-11-07",
"latestDeliveryDate": "2026-11-04",
"method": "FBR",
"timeFrameType": "REGULAR"
},
"latestChangedDateTime": "2026-11-02T12:39:48+01:00",
"offer": {
"offerId": "6ff736b5-cdd0-4150-8c67-78269ee986f5",
"reference": "SKU-1001"
},
"orderItemId": "2012345678",
"product": {
"ean": "9789076174082",
"title": "De steen der wijzen"
},
"quantity": 1,
"quantityCancelled": 0,
"quantityShipped": 0,
"totalPrice": 19.99,
"unitPrice": 19.99
}
],
"orderPlacedDateTime": "2026-11-02T12:39:48+01:00",
"pickupPoint": false,
"shipmentDetails": {
"city": "Utrecht",
"company": "",
"countryCode": "NL",
"deliveryPhoneNumber": "",
"email": "2ixm3kr4rrbxl4zcsyxtfh5zt7lqsg@verkopen.bol.com",
"extraAddressInformation": "",
"firstName": "Billie",
"houseNumber": "1",
"houseNumberExtension": "",
"kvkNumber": "",
"language": "nl",
"orderReference": "",
"pickupPointName": "",
"salutation": "FEMALE",
"streetName": "Dorpstraat",
"surname": "Jansen",
"vatNumber": "",
"zipCode": "1111ZZ"
}
}
}Get process status
Check whether a shipment, cancellation or return bol.com was still processing has finished, and how.
Inputs
- Process status ID
process_status_idtextRequired - The process_status_id an earlier bol.com step gave.
Outputs
descriptiontext- bol.com's description of it
entity_idtext- What it changed: an order item id, or a new return's id
error_messagetext- Why it failed, empty unless it did
event_typetext- What kind of change it was
finishedtrue/false- Whether bol.com has finished processing it
process_statusobject- bol.com's process status
process_status_idtext- The id to follow the change with in 'Get process status'
statustext- PENDING, SUCCESS, FAILURE or TIMEOUT
Example output
{
"description": "Confirm shipment for order item 2012345678.",
"entity_id": "2012345678",
"error_message": "",
"event_type": "CONFIRM_SHIPMENT",
"finished": true,
"process_status": {
"createTimestamp": "2026-11-02T13:00:00+01:00",
"description": "Confirm shipment for order item 2012345678.",
"entityId": "2012345678",
"errorMessage": "",
"eventType": "CONFIRM_SHIPMENT",
"links": [
{
"href": "https://api.bol.com/shared/process-status/1234567",
"method": "GET",
"rel": "self"
}
],
"processStatusId": "1234567",
"status": "SUCCESS"
},
"process_status_id": "1234567",
"status": "SUCCESS"
}Get return
Get one return with each returned item (its rmaId), the customer's reason and how it was handled.
Inputs
- Return ID
return_idtextRequired - The return's id, from 'List returns' or the return trigger.
Outputs
returnobject- The return
Example output
{
"return": {
"fulfilmentMethod": "FBR",
"registrationDateTime": "2026-11-04T11:06:48+01:00",
"returnId": "15897410",
"returnItems": [
{
"customerDetails": {
"city": "Utrecht",
"company": "",
"countryCode": "NL",
"deliveryPhoneNumber": "",
"email": "2ixm3kr4rrbxl4zcsyxtfh5zt7lqsg@verkopen.bol.com",
"extraAddressInformation": "",
"firstName": "Billie",
"houseNumber": "1",
"houseNumberExtension": "",
"kvkNumber": "",
"language": "nl",
"orderReference": "",
"pickupPointName": "",
"salutation": "FEMALE",
"streetName": "Dorpstraat",
"surname": "Jansen",
"vatNumber": "",
"zipCode": "1111ZZ"
},
"ean": "9789076174082",
"expectedQuantity": 1,
"handled": true,
"orderId": "A2K8290LP8",
"processingResults": [
{
"handlingResult": "RETURN_RECEIVED",
"processingDateTime": "2026-11-05T10:55:37+01:00",
"processingResult": "ACCEPTED",
"quantity": 1
}
],
"returnReason": {
"customerComments": "Smaller than I expected",
"detailedReason": "Niet naar verwachting",
"mainReason": "Niet naar verwachting"
},
"rmaId": "31234567",
"title": "De steen der wijzen",
"trackAndTrace": "3SBOL0987654322",
"transporterName": "PostNL"
}
]
}
}Get shipment
Get one shipment with its items, carrier, tracking code and where the parcel is now.
Inputs
- Shipment ID
shipment_idtextRequired - The shipment's id, from 'List shipments' or the shipment trigger.
Outputs
shipmentobject- The shipment
Example output
{
"shipment": {
"billingDetails": {
"city": "Utrecht",
"company": "",
"countryCode": "NL",
"deliveryPhoneNumber": "",
"email": "2ixm3kr4rrbxl4zcsyxtfh5zt7lqsg@verkopen.bol.com",
"extraAddressInformation": "",
"firstName": "Billie",
"houseNumber": "1",
"houseNumberExtension": "",
"kvkNumber": "",
"language": "nl",
"orderReference": "",
"pickupPointName": "",
"salutation": "FEMALE",
"streetName": "Dorpstraat",
"surname": "Jansen",
"vatNumber": "",
"zipCode": "1111ZZ"
},
"order": {
"orderId": "A2K8290LP8",
"orderPlacedDateTime": "2026-11-02T12:39:48+01:00"
},
"pickupPoint": false,
"shipmentDateTime": "2026-11-02T15:55:37+01:00",
"shipmentDetails": {
"city": "Utrecht",
"company": "",
"countryCode": "NL",
"deliveryPhoneNumber": "",
"email": "2ixm3kr4rrbxl4zcsyxtfh5zt7lqsg@verkopen.bol.com",
"extraAddressInformation": "",
"firstName": "Billie",
"houseNumber": "1",
"houseNumberExtension": "",
"kvkNumber": "",
"language": "nl",
"orderReference": "",
"pickupPointName": "",
"salutation": "FEMALE",
"streetName": "Dorpstraat",
"surname": "Jansen",
"vatNumber": "",
"zipCode": "1111ZZ"
},
"shipmentId": "541757635",
"shipmentItems": [
{
"commission": 3.15,
"fulfilment": {
"distributionParty": "RETAILER",
"latestDeliveryDate": "2026-11-04",
"method": "FBR"
},
"offer": {
"offerId": "6ff736b5-cdd0-4150-8c67-78269ee986f5",
"reference": "SKU-1001"
},
"orderItemId": "2012345678",
"product": {
"ean": "9789076174082",
"title": "De steen der wijzen"
},
"quantity": 1,
"quantityShipped": 1,
"unitPrice": 19.99
}
],
"shipmentReference": "BOX-77",
"transport": {
"shippingLabelId": "",
"trackAndTrace": "3SBOL0987654321",
"transportEvents": [
{
"eventCode": "AT_TRANSPORTER",
"eventDateTime": "2026-11-02T17:21:07+01:00"
}
],
"transportId": "312778947",
"transporterCode": "TNT"
}
}
}Handle a return
Say how a returned item was handled, or change an earlier answer. Waits for bol.com to confirm it.
Inputs
- Return item (rmaId)
rma_idtextRequired - The returned item's rmaId, from 'Get return'.
- Handled as
handling_resulttextRequired - How it was handled. Received and approved, and approved after all, refund the customer through bol.com.One of:
RETURN_RECEIVED(Received and approved (customer refunded)),EXCHANGE_PRODUCT(Exchanged or replaced),RETURN_DOES_NOT_MEET_CONDITIONS(Doesn't meet the conditions (rejected)),REPAIR_PRODUCT(You'll repair it),CUSTOMER_KEEPS_PRODUCT_PAID(Customer keeps it and pays),STILL_APPROVED(Approved after all, after a rejection (customer refunded)). - Quantity returned
quantity_returnednumberRequired - How many of the item came back.From 1 to 9999.
Outputs
descriptiontext- bol.com's description of it
entity_idtext- What it changed: an order item id, or a new return's id
error_messagetext- Why it failed, empty unless it did
event_typetext- What kind of change it was
finishedtrue/false- Whether bol.com has finished processing it
process_statusobject- bol.com's process status
process_status_idtext- The id to follow the change with in 'Get process status'
statustext- PENDING, SUCCESS, FAILURE or TIMEOUT
Example output
{
"description": "Confirm shipment for order item 2012345678.",
"entity_id": "31234567",
"error_message": "",
"event_type": "HANDLE_RETURN_ITEM",
"finished": true,
"process_status": {
"createTimestamp": "2026-11-02T13:00:00+01:00",
"description": "Confirm shipment for order item 2012345678.",
"entityId": "2012345678",
"errorMessage": "",
"eventType": "CONFIRM_SHIPMENT",
"links": [
{
"href": "https://api.bol.com/shared/process-status/1234567",
"method": "GET",
"rel": "self"
}
],
"processStatusId": "1234567",
"status": "SUCCESS"
},
"process_status_id": "1234567",
"status": "SUCCESS"
}List competing offers
List every seller's offer for a product, yours included, with its price, condition and delivery dates, and which is the best offer. Gets one page of 50.
Inputs
- EAN
eantextRequired - The product's EAN (barcode number) or ISBN.
- Country
country_codetext - Only offers for sale in this country.One of:
NL(Netherlands),BE(Belgium). - Best offer only
best_offer_onlytrue/false - Only the offer bol.com shows first in each country.
- Condition
conditiontext - Only offers in this condition. Defaults to new.One of:
NEW(New (default)),ALL(Any condition),AS_NEW(As new),GOOD,REASONABLE,MODERATE,BAD,REFURBISHED_A(Refurbished, grade A),REFURBISHED_B(Refurbished, grade B),REFURBISHED_C(Refurbished, grade C). - Page
pagenumber - Which page of 50 to get, up to 200. Defaults to the first.From 1 to 200.
Outputs
countnumber- How many are on this page
may_have_moretrue/false- True when the page was full, so the next page may have more
offerslist- The offers
pagenumber- The page number read
Example output
{
"count": 1,
"may_have_more": false,
"offers": [
{
"bestOffer": true,
"condition": "NEW",
"countryCode": "NL",
"fulfilmentMethod": "FBB",
"maxDeliveryDate": "2026-11-08",
"minDeliveryDate": "2026-11-07",
"offerId": "228b6d06-2067-4cef-8447-c21d0c233e61",
"price": 18.5,
"retailerId": "1055479",
"ultimateOrderTime": "23:59"
}
],
"page": 1
}List offers
List your offers, filtered by EAN, your reference, whether they're for sale, or when they last changed. Gets one page; to see more, run it again with the next cursor it gives.
Inputs
- EANs
eanslist - Only offers for these EANs.
- Your reference
referencetext - Only the offer with this reference of yours.
- For sale
for_saletext - Only offers for sale, or only those that aren't.One of:
true(For sale),false(Not for sale). - Changed since
modified_sincedate and time - Only offers changed (by you or bol.com) since then.
- Page size
page_sizenumber - How many to get, 1 to 100.From 1 to 100.
- Next page cursor
cursortext - The 'next_cursor' from an earlier page, for the page after it.
Outputs
countnumber- How many are on this page
next_cursortext- The cursor for the next page, empty on the last
offerslist- The offers
Example output
{
"count": 1,
"next_cursor": "",
"offers": [
{
"condition": {
"category": "NEW",
"comment": "",
"grade": "",
"margin": false,
"state": ""
},
"countryAvailabilities": [
{
"countryCode": "NL",
"forSale": true
}
],
"ean": "9789076174082",
"economicOperatorId": "",
"fulfilment": {
"deliveryPromise": {
"maximumDaysToCustomer": 2,
"minimumDaysToCustomer": 1,
"ultimateOrderTime": ""
},
"method": "FBR",
"profileId": "",
"schedule": "BOL_DELIVERY_PROMISE"
},
"lastModifiedDateTime": "2026-11-02T08:34:41+01:00",
"offerId": "6ff736b5-cdd0-4150-8c67-78269ee986f5",
"onHoldByRetailer": false,
"pricing": {
"bundlePrices": [
{
"quantity": 1,
"unitPrice": 19.99
}
]
},
"product": {
"bolProductId": "9200000045327288"
},
"reference": "SKU-1001",
"stock": {
"amount": 6,
"correctedStock": 5,
"managedByRetailer": false
},
"unknownProductTitle": ""
}
]
}List orders
List orders, newest first: open ones, or those shipped or cancelled in the last 48 hours. Gets one page of 50; to see more, run it again with the next page.
Inputs
- Shipped by
fulfilment_methodtext - Orders you ship yourself, ones bol.com ships, or both. Defaults to those you ship.One of:
FBR(Shipped by you (default)),FBB(Shipped by bol.com (Logistics via bol)),ALL(Both). - Status
statustext - Which orders to include. Defaults to open orders.One of:
OPEN(Open (default)),SHIPPED(Shipped in the last 48 hours),ALL(All, including handled in the last 48 hours). - Changed in the last minutes
changed_within_minutesnumber - Only orders that are new or changed in this many minutes, up to 60.From 1 to 60.
- Changed on
changed_ondate - Only orders last changed on this day, up to three months ago.
- Page
pagenumber - Which page of 50 to get. Defaults to the first.From 1 to 10000.
Outputs
countnumber- How many are on this page
may_have_moretrue/false- True when the page was full, so the next page may have more
orderslist- The orders
pagenumber- The page number read
Example output
{
"count": 1,
"may_have_more": false,
"orders": [
{
"orderId": "A2K8290LP8",
"orderItems": [
{
"cancellationRequest": false,
"ean": "9789076174082",
"fulfilmentMethod": "FBR",
"fulfilmentStatus": "OPEN",
"latestChangedDateTime": "2026-11-02T12:39:48+01:00",
"orderItemId": "2012345678",
"quantity": 1,
"quantityCancelled": 0,
"quantityShipped": 0
}
],
"orderPlacedDateTime": "2026-11-02T12:39:48+01:00"
}
],
"page": 1
}List returns
List customer returns, those waiting for you to handle or those already handled. Gets one page of 50; to see more, run it again with the next page.
Inputs
- Handled
handledtext - Returns still to handle, or ones already handled.One of:
false(Waiting for you to handle),true(Already handled). - Shipped by
fulfilment_methodtext - Only those you ship yourself, or only those bol.com ships.One of:
FBR(Shipped by you),FBB(Shipped by bol.com (Logistics via bol)). - Page
pagenumber - Which page of 50 to get. Defaults to the first.From 1 to 10000.
Outputs
countnumber- How many are on this page
may_have_moretrue/false- True when the page was full, so the next page may have more
pagenumber- The page number read
returnslist- The returns
Example output
{
"count": 1,
"may_have_more": false,
"page": 1,
"returns": [
{
"fulfilmentMethod": "FBR",
"registrationDateTime": "2026-11-04T11:06:48+01:00",
"returnId": "15897410",
"returnItems": [
{
"ean": "9789076174082",
"expectedQuantity": 1,
"handled": false,
"orderId": "A2K8290LP8",
"processingResults": [],
"returnReason": {
"customerComments": "Smaller than I expected",
"detailedReason": "Niet naar verwachting",
"mainReason": "Niet naar verwachting"
},
"rmaId": "31234567"
}
]
}
]
}List shipments
List shipments from the last three months, newest first, or those of one order. Gets one page of 50; to see more, run it again with the next page.
Inputs
- Shipped by
fulfilment_methodtext - Only those you ship yourself, or only those bol.com ships.One of:
FBR(Shipped by you),FBB(Shipped by bol.com (Logistics via bol)). - Order ID
order_idtext - Only this order's shipments. Leave 'Shipped by' empty when you give one.
- Page
pagenumber - Which page of 50 to get. Defaults to the first.From 1 to 10000.
Outputs
countnumber- How many are on this page
may_have_moretrue/false- True when the page was full, so the next page may have more
pagenumber- The page number read
shipmentslist- The shipments
Example output
{
"count": 1,
"may_have_more": false,
"page": 1,
"shipments": [
{
"order": {
"orderId": "A2K8290LP8",
"orderPlacedDateTime": "2026-11-02T12:39:48+01:00"
},
"shipmentDateTime": "2026-11-02T15:55:37+01:00",
"shipmentId": "541757635",
"shipmentItems": [
{
"ean": "9789076174082",
"orderItemId": "2012345678"
}
],
"shipmentReference": "BOX-77",
"transport": {
"transportId": "312778947"
}
}
]
}Register a return
Register a return a customer sent back without announcing it, and say how it was handled. The customer is emailed. Waits for bol.com to confirm it and gives the new return's id.
Inputs
- Order item ID
order_item_idtextRequired - The order item's id (orderItemId), from 'Get order' or the order trigger.
- Quantity returned
quantity_returnednumberRequired - How many of the item came back.From 1 to 9999.
- Handled as
handling_resulttextRequired - How it was handled. Received and approved, and approved after all, refund the customer through bol.com.One of:
RETURN_RECEIVED(Received and approved (customer refunded)),EXCHANGE_PRODUCT(Exchanged or replaced),RETURN_DOES_NOT_MEET_CONDITIONS(Doesn't meet the conditions (rejected)),REPAIR_PRODUCT(You'll repair it),CUSTOMER_KEEPS_PRODUCT_PAID(Customer keeps it and pays).
Outputs
descriptiontext- bol.com's description of it
entity_idtext- What it changed: an order item id, or a new return's id
error_messagetext- Why it failed, empty unless it did
event_typetext- What kind of change it was
finishedtrue/false- Whether bol.com has finished processing it
process_statusobject- bol.com's process status
process_status_idtext- The id to follow the change with in 'Get process status'
return_idtext- The new return's id, once bol.com has made it
statustext- PENDING, SUCCESS, FAILURE or TIMEOUT
Example output
{
"description": "Confirm shipment for order item 2012345678.",
"entity_id": "15897411",
"error_message": "",
"event_type": "CREATE_RETURN_ITEM",
"finished": true,
"process_status": {
"createTimestamp": "2026-11-02T13:00:00+01:00",
"description": "Confirm shipment for order item 2012345678.",
"entityId": "2012345678",
"errorMessage": "",
"eventType": "CONFIRM_SHIPMENT",
"links": [
{
"href": "https://api.bol.com/shared/process-status/1234567",
"method": "GET",
"rel": "self"
}
],
"processStatusId": "1234567",
"status": "SUCCESS"
},
"process_status_id": "1234567",
"return_id": "15897411",
"status": "SUCCESS"
}Set offer price
Set an offer's price. It replaces any volume discounts with this one price.
Inputs
- Offer
offer_idtextRequired - The offer. Pick one, or give its id from an earlier step.
- Price (EUR)
pricenumberRequired - The price in euros including VAT, between 1 and 9999, like 19.99.From 1 to 9999.
Outputs
offer_idtext- The offer's id
sentobject- What was sent, with the countries kept as they were
updatedtrue/false- True once bol.com took the change
Example output
{
"offer_id": "6ff736b5-cdd0-4150-8c67-78269ee986f5",
"sent": {
"countryAvailabilities": [
{
"countryCode": "NL"
}
],
"pricing": {
"bundlePrices": [
{
"quantity": 1,
"unitPrice": 17.99
}
]
}
},
"updated": true
}Set offer stock
Set how many of an offer you have in stock. Only for offers you ship yourself; bol.com counts the stock it ships.
Inputs
- Offer
offer_idtextRequired - The offer. Pick one, or give its id from an earlier step.
- Stock
stock_amountnumberRequired - How many you have in stock, 0 to 999.From 0 to 999.
- I keep the stock count myself
stock_managed_by_retailertrue/false - Turn on if you lower the stock yourself as orders come in. Off, bol.com sets aside stock for open orders so you don't oversell.
Outputs
offer_idtext- The offer's id
sentobject- What was sent, with the countries kept as they were
updatedtrue/false- True once bol.com took the change
Example output
{
"offer_id": "6ff736b5-cdd0-4150-8c67-78269ee986f5",
"sent": {
"countryAvailabilities": [
{
"countryCode": "NL"
}
],
"stock": {
"amount": 4,
"managedByRetailer": false
}
},
"updated": true
}Ship order items
Tell bol.com that items of an order have shipped, with the carrier and tracking code or a bol.com shipping label. Waits for bol.com to confirm it.
Inputs
- Order item IDs
order_item_idslistRequired - The order items shipped together, all from one order (orderItemId in 'Get order' or the order trigger).
- Quantity
quantitynumber - How many of a single item shipped, for a partial shipment. Leave empty to ship everything still open.From 1 to 9999.
- Carrier
transporter_codetext - Who carries the parcel. Leave empty if you bought a bol.com shipping label.One of:
TNT(PostNL),TNT-EXTRA(PostNL extra@home),TNT_BRIEF(PostNL Briefpost),TNT-EXPRESS(TNT Express),DHL,DHL_DE(DHL Germany),DHL-GLOBAL-MAIL(DHL Global Mail),DHL-SD(DHL Same Day),DHLFORYOU,DPD-NL(DPD Nederland), and 22 more. - Tracking code
track_and_tracetext - The carrier's tracking code for the parcel.
- Shipping label ID
shipping_label_idtext - The id of a shipping label bought from bol.com, instead of a carrier and tracking code.
- Shipment reference
shipment_referencetext - Your own reference for the shipment (up to 90 characters).
Outputs
descriptiontext- bol.com's description of it
entity_idtext- What it changed: an order item id, or a new return's id
error_messagetext- Why it failed, empty unless it did
event_typetext- What kind of change it was
finishedtrue/false- Whether bol.com has finished processing it
process_statusobject- bol.com's process status
process_status_idtext- The id to follow the change with in 'Get process status'
statustext- PENDING, SUCCESS, FAILURE or TIMEOUT
Example output
{
"description": "Confirm shipment for order item 2012345678.",
"entity_id": "2012345678",
"error_message": "",
"event_type": "CONFIRM_SHIPMENT",
"finished": true,
"process_status": {
"createTimestamp": "2026-11-02T13:00:00+01:00",
"description": "Confirm shipment for order item 2012345678.",
"entityId": "2012345678",
"errorMessage": "",
"eventType": "CONFIRM_SHIPMENT",
"links": [
{
"href": "https://api.bol.com/shared/process-status/1234567",
"method": "GET",
"rel": "self"
}
],
"processStatusId": "1234567",
"status": "SUCCESS"
},
"process_status_id": "1234567",
"status": "SUCCESS"
}Update offer
Change an offer's reference, countries, pause, title, economic operator or delivery time. Anything left empty stays as it is.
Inputs
- Offer
offer_idtextRequired - The offer. Pick one, or give its id from an earlier step.
- Your reference
referencetext - Your own code for the offer, such as your SKU (up to 100 characters).
- Paused
on_holdtrue/false - Pause the offer so it isn't shown for sale, without deleting it.
- Sell in
countrieslist - The countries to sell it in. Leave empty for your account's default country.One or more of:
NL(Netherlands),BE(Belgium). - Title for an unknown product
unknown_product_titletext - A title to find the offer by when bol.com doesn't know the EAN yet. Ignored for products bol.com knows.
- Economic operator ID
economic_operator_idtext - The id of the product's responsible economic operator in the EU, from the Seller Dashboard. The offer goes on sale only once it has one.
- Delivery time from
delivery_scheduletext - Where the delivery time comes from: one of bol.com's, your own delivery profile in the Seller Dashboard, or Shipping via bol.One of:
BOL_DELIVERY_PROMISE(A bol.com delivery time),MY_DELIVERY_PROMISE(My own delivery profile),SHIPPING_VIA_BOL(Shipping via bol). - Delivery time
delivery_promisetext - How fast the customer gets it.Only when Delivery time from is A bol.com delivery time. One of:
0-1-12(Next day if ordered by 12:00),0-1-13(Next day if ordered by 13:00),0-1-14(Next day if ordered by 14:00),0-1-15(Next day if ordered by 15:00),0-1-16(Next day if ordered by 16:00),0-1-17(Next day if ordered by 17:00),0-1-18(Next day if ordered by 18:00),0-1-19(Next day if ordered by 19:00),0-1-20(Next day if ordered by 20:00),0-1-21(Next day if ordered by 21:00), and 7 more. - Delivery profile ID
delivery_profile_idtext - The id of your delivery profile. Leave empty for your default one.Only when Delivery time from is My own delivery profile.
Outputs
offer_idtext- The offer's id
sentobject- What was sent, with the countries kept as they were
updatedtrue/false- True once bol.com took the change
Example output
{
"offer_id": "6ff736b5-cdd0-4150-8c67-78269ee986f5",
"sent": {
"countryAvailabilities": [
{
"countryCode": "NL"
}
],
"reference": "SKU-1002"
},
"updated": true
}