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 and 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 the case of Logistics Via Bol.com.

Return structure

A return request is identified by a returnId. 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 the 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.

Retrieve returns

Retrieve returns: returns a list of handled or unhandled returns.

The retrieve returns endpoint retrieves a list of returns for the retailer, that are registered by either the customer or customer service. In API v4, you can also create your own returns which are visible through this endpoint.

The get returns endpoints allow you to filter on handled returns (true or false). Handled returns are returns that are already handled by you. Unhandled returns are returns that still require an action from your side.

In addition to handled, you can use the fulfilmentMethod 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

Retrieve return by return ID: returns the details of one single return.

The get a return by return ID call 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

Handle a return: handles a return created by the customer.

You can use this endpoint to handle a return that was received from 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, which are closely related to the supplied handling result and can be one of the following values:

  • ACCEPTED: the return is accepted

  • REJECTED: the return is rejected

  • CANCELLED: the return is cancelled

A return can only be handled once before the result becomes permanent, with the exception that a rejected processing result can still be changed to accepted if the handling result is updated to STILL_APPROVED.

Create a return

Create a return: creates a return for a customer.

Creating a return allows you to create a return on behalf of the customer. You can create a return if the customer sent the product to you without registering it. With this endpoint, you can therefore create a new return and credit the customer if 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 through email.

Return handling results

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