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.
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).
Field indicating whether a return item was accepted or not. Possible values: ACCEPTED, REJECTED and CANCELLED. This field is closely related to HandlingResult.
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:
|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|