Returns

Introduction

The Returns resource inside the Retailer API allows you to manage all return related activities that are concerned with the (physical aspects of) customer returns. It provides detailed information on returns that are registered by a customer or customer service, allows you to process returns or to create a return on behalf of the customer. Within the return related data, you can find feedback that was provided by you or one of our warehouses (in case of Logistics via bol.com).

Return endpoints

The following endpoints exist:

  • Get returns, that provides you a list off open returns. You can filter your returns on fulfilment method (FBR/FBB) or on handled (true/false)
  • Get a return by return id, that provides you the details of one single return
  • Create a return, that allows you to create a return on behalf of the customer
  • Handle a return, that allows you to handle an already registered return

Return structure

A return request is identified by a return-id. 1 return can contain 1 or more return item(s), that are identified by an rma-id. Actions that you perform on the API are always on a specific item within a return.This means that you will always provide feedback on rma-id level, and not on return-id. If you create a new return, the API will automatically create a return-id and an rma-id for you.

Get returns

The get returns endpoint retrieves a list of returns for the retailer, that are registered by either the customer or customer service. In version 4, you can also create your own returns. These are also visible through this endpoint. The get returns endpoints allows you to filter on handled returns (true/false). Handled returns are returns that are already handled by you. Unhandled returns are returns that still require an action from your side.
Next to handled, you can use the fulfilment-method parameter to either filter on FBB (LvB) returns or FBR returns. Once feedback is received on a specific return-item, it will be processed and change the return status to ‘handled’.

Get return by return id

The get a return by return id allows you to retrieve all the details of a single return. A single return can contain 1 or more return items, that are identified by a return id.

Handle a return

You can use this endpoint to handle a return that was received form the sender. Be advised that handling a return is always per single return item (using an rma-id). As a partner you can specify how the state of the return must be registered and depending on the handling result supplied the customer will receive his/her money back. This action will eventually lead to one or more processing results. A processing result is closely related to the supplied handling result and can either be:

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

 

Create a return

Creating a return allows you to create a return on behalf of the customer. You can create a return in case the customer sent the product to you, without registering it itself. With this endpoint, you can therefore create a new return and credit the customer in case the return was properly received. By creating a return, it will also become visible for the customer itself.

In order to create a return, you need to supply the order-item-id (that you will find on the package), the amount of quantity that has been returned by the customer, and the way you want to handle this return. In case you want to handle items differently, you can create 1 or more return requests. Please be aware that you can never create more returns than the amount the customer originally ordered.

When creating a return, the customer will receive feedback on this through e-mail.

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).

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
bol.com Development Center