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.