API v3 – Returns

DISCLAIMER: As of the 16th of January, we recommend you to use the most recent version for returns (version 4). Version 3 will remain working but doesn’t support multi-item returns. Please take a look at version 4 as described on https://developers.bol.com/api-v4-returns.


The Returns API is responsible for all return related actions that have to do with the (physical aspects of) customer returns. It will provide detailed information on returns registered by a customer or customer service and will handle the feedback provided by retailers or warehouses on received returns. A return (identified by a rma-id) can have only one or return-item. A seller can handle a return by sending feedback on the received return. When supplying feedback a handling result, which will say something about the state in which the return was received, needs to be sent; several handling results are available.

Bol.com offers several different endpoints for returns management. Starting with a summarized list of return id’s to reduce the load of each request. To view detailed information of a specific return, the get single return can be used. Using parameters it’s possible to retrieve handled and unhandled returns.


Get returns

The get returns endpoint (https://api.bol.com/retailer/public/redoc/v3#operation/get-returns) retrieves a list of returns for the retailer, that are registered by either the customer or customer service. With the handled-indicator filtering can be applied showing handled or unhandled returns. The fulfilment-method can be used to either filter on FBB (LvB) returns or FBR returns. A handled return is a return for which feedback (with a handling result) has been received. Once feedback is received it will be processed and almost immediately will change the return to ‘handled’.


Get return by rma id

The get a return by rma id (https://api.bol.com/retailer/public/redoc/v3#operation/get-return) retrieves return information for a specific rma-id.


Handle a return

You can use this endpoint (https://api.bol.com/retailer/public/redoc/v3#operation/handle-return) to handle a return that was received form the sender. As a seller you can specify how the state of the return should be registered and depending on the handling result supplied the customer will get his/her money back (or not -> see refunded column). After a return is handled by the seller the supplied handling result will be stored and processed. This will eventually lead to one or more processing results. A processing result is closely related to the supplied handling result. A processing result can contain:

  • ACCEPTED, meaning the return is accepted
  • REJECTED, meaning the return is rejected
  • CANCELLED, meaning the return is cancelled


Handling results explained

Is used by Handling result Meaning Processing result Refunded through bol.com?
Bol.com and retailer RETURN_RECEIVED Return is received as expected and approved. ACCEPTED Yes
Bol.com and retailer EXCHANGE_PRODUCT In consultation with the customer, the product will be exchanged or replaced. ACCEPTED No
Bol.com and retailer RETURN_DOES_NOT_MEET_CONDITIONS Return did not met the expectation/condition. REJECTED No
Bol.com and retailer REPAIR_PRODUCT You will take the lead in repairing the product for the customer. ACCEPTED No
Bol.com and retailer CUSTOMER_KEEPS_PRODUCT_PAID Customer is allowed to keep the product. CANCELLED No
Bol.com and retailer STILL_APPROVED* In consultation with the customer, the return is still approved after an initial rejection. With this handling result, you can still refund the customer. ACCEPTED Yes
Bol.com CUSTOMER_KEEPS_PRODUCT_FREE_OF_CHARGE Customer is allowed to keep the product with no costs. ACCEPTED Yes
Bol.com RETURN_ITEM_LOST Somewhere on it’s way back to the seller the return item was lost ACCEPTED Yes
Bol.com EXPIRED The time between registering a return and sending it back took more than 21 days. The return is therefore cancelled. CANCELLED No
Bol.com EXCESSIVE_RETURN Feedback with more quantity than ordered was supplied. ACCEPTED No
Bol.com STILL_RECEIVED The return was reported lost but was still received. ACCEPTED No
Bol.com CANCELLED_BY_CUSTOMER The customer decided to cancel his/her return CANCELLED No
Bol.com FAILED_TO_CREATE_SHIPPING_LABEL The transporter failed to create a shipping label. The return is therefore cancelled. CANCELLED No

* This handling result is only accepted when the announced return was initially rejected by the partner (using handling result 2, 3, 4 or 5 from the table above).


Processing results

Field indicating whether a return item was accepted or not. Possible values: ACCEPTED, REJECTED and CANCELLED. This field is closely related to HandlingResult.


Return reasons

During registration of a return item a customer can enter a reason why the item is returned. This return reason is optional and a customer can choose to leave this field empty.

If a customer specifies the reason why the item is returned, one of the following return reasons can be selected:

Reason Details
INCORRECT_PRODUCT_INFORMATION Incorrect information on website
WRONG_SIZE_ORDERED Customer ordered wrong size
WRONG_ARTICLE_RECEIVED Wrong item delivered to customer
ARTICLE_DAMAGED Article was damaged when received
ARTICLE_BROKEN Article is not working or is broken
ARTICLE_DELIVERY_TOO_LATE Item not delivered in time
ARTICLE_INCOMPLETE Part(s) missing for the item
WRONG_ARTICLE_ORDERED Customer ordered wrong article
OTHER If no other reason is applicable