Returns

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

We recommend you to use the most recent API version for returns. Version 3 will remain working until its retirement but doesn’t support multi-item returns. Please take a look at returns for version 4 as described here.

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 an rmaId - can have only one 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 IDs to reduce the load of each request. Get single return can be used to view detailed information of a specific return. It is possible to retrieve handled and unhandled returns using the available parameters.

Retrieve returns

Retrieve returns: returns a list of registered returns.

The get returns endpoint retrieves a list of returns for the retailer that are registered by either the customer or customer service. The handled-indicator applies filtering to show 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 `rmaId`

Retrieve a return: returns a single return based on its rmaId.

Get a return by rma id retrieves return information for a specific rmaId.

Handle a return

Handle return: confirm receipt of returned goods and update the return status.

You can use this endpoint 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.

The Refunded column shows whether the customer was refunded through bol.com.

Once a return has been 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: the return is accepted
REJECTED: the return is rejected
CANCELLED: 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