Returns

Version 3 of the Retailer API has been deprecated. Please migrate to the v4 API as soon as possible.

IMPORTANT: As of the 16th of January 2020, 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.

Returns API

Retrieve returns: returns a list of registered returns.
Retrieve a return: returns a single return based on its rmaId.
Handle return: confirm receipt of returned goods and update the return status.

Introduction

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.

Retrieve returns

The get returns endpoint 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.

Retrieve return by `rma-id`

The get a return by rma id 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

Table 1. Available handling results and effects
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.	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.	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:

Table 2. Available return reasons
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