Managing Returns
If you have enabled automatic returns in your Kaufland account settings, customers can start the return process and automatically receive a shipping label when they want to return a product. This will create a return entry in the Kaufland marketplace system, which you can retrieve and update.
Initialize a return for order units
You, as a seller, can also initialize a return for one or multiple order units sending a POST
request to
the /returns
endpoint.
A return can be initialized only for order units of one order at a time.
Note: Only sellers who are using the Kaufland.de or DHL return services can use this method.
For example, to initialize a return for three order units:
POST https://sellerapi.kaufland.com/v2/returns
Request body:
[
{
"id_order_unit": 314567849801,
"reason": "defect",
"note": "Scratch on the display"
},
{
"id_order_unit": 314567849802,
"reason": "wrong_size",
"note": "Product is too big"
},
{
"id_order_unit": 314567849803,
"reason": "no_reason",
"note": "Customer wants to return without reason"
}
]
The note must contain at least 5 characters and a maximum of 100.
Allowed values for the field reason
are:
accidentally_ordered
: Order has been placed accidentallybad_quality
: The delivered order unit had a bad qualitybetter_price
: Got better price for this productdefect
: The delivered order unit is defectdelivered_damaged
: Product is damageddislike
: Dislike the productmisleading_description
: Product description is misleadingmissing_parts
: Missing parts of the productno_reason
: There is no reason for the returntoo_late
: The order unit was delivered too latewrong_article
: The delivered order unit was incorrectwrong_size
: The delivered order unit had the wrong size
Note: We prevent this action for return units fulfilled by Kaufland and respond with a HTTP 403 error code. Read more about FBK.
A successful response includes the newly created return entity:
{
"data": {
"id_return": 3800,
"ts_created_iso": "2016-05-07T23:10:36Z",
"ts_updated_iso": "2016-05-09T11:17:02Z",
"storefront": "de"
"tracking_provider": "DHL",
"tracking_code": "00340434161221754211",
"status": "label_generated",
"return_units": {
[
{
"id_return_unit": 4134,
"id_return": 3800,
"id_order_unit": 314567849801,
"ts_created_iso": "2016-05-07T22:00:14Z",
"status": "need_to_be_returned",
"note": "Scratch on the display",
"reason": "defect",
"storefront": "de"
},
{
"id_return_unit": 4135,
"id_return": 3800,
"id_order_unit": 314567849802,
"ts_created_iso": "2016-05-07T22:00:14Z",
"status": "need_to_be_returned",
"note": "Product is too big.",
"reason": "wrong_size",
"storefront": "de"
},
{
"id_return_unit": 4136,
"id_return": 3800,
"id_order_unit": 314567849803,
"ts_created_iso": "2016-05-07T22:00:14Z",
"status": "need_to_be_returned",
"note": "Customer wants to return without reason",
"reason": "no_reason",
"storefront": "de"
},
]
}
}
}
Retrieving Return Information
To retrieve the returns from your sales, you can use the /returns
endpoint in the REST API.
Finding all open returns
Example: getting all of the open returns from all of your customers
GET https://sellerapi.kaufland.com/v2/returns?status=return_requested&status=label_generated&status=package_sent&status=package_received
Response:
{
"data": [
{
"id_return": 77501,
"ts_created_iso": "2014-10-23T00:56:22Z",
"ts_updated_iso": "2014-11-06T16:32:15Z",
"tracking_provider": "DHL",
"tracking_code": "00340433836099527354",
"status": "package_received",
"storefront": "de"
},
{
"id_return": 77461,
"ts_created_iso": "2014-10-22T21:24:30Z",
"ts_updated_iso": "2014-10-22T21:25:05Z",
"tracking_provider": "DHL",
"tracking_code": "00340433836099370622",
"status": "label_generated",
"storefront": "de"
},
{
"id_return": 77451,
"ts_created_iso": "2014-10-22T20:40:53Z",
"ts_updated_iso": "2014-10-22T20:41:05Z",
"tracking_provider": "DHL",
"tracking_code": "00340433836099333948",
"status": "label_generated",
"storefront": "de"
},
{
"id_return": 77441,
"ts_created_iso": "2014-10-22T20:09:17Z",
"ts_updated_iso": "2014-10-22T20:10:05Z",
"tracking_provider": "DHL",
"tracking_code": "00340433836099304757",
"status": "label_generated",
"storefront": "de"
}
],
"pagination": {
"offset": 0,
"limit": 0,
"total": 0
}
}
Note: the result is limited by default - please read how to handle pagination.
Searching by tracking code
Often you will receive a package in the mail and you will want to retrieve the return for that package. To do
this, search for the package by tracking_code
.
Example:
GET https://sellerapi.kaufland.com/v2/returns?tracking_code=12345678901234567890
Note: By default this endpoint only returns which need to be fulfilled by the seller. To get returns fulfilled by Kaufland an appropriate filter parameter needs to be applied. Read more about FBK.
Retrieving Full Return Information
To get full information on a return use GET /returns/{id_return}?embedded=return_units&embedded=buyer
.
This will provide you with the id_return_unit
of each return unit within the return.
This ID is needed to update a return's status.
Response:
{
"data": {
"id_return": 3800,
"ts_created_iso": "2016-05-07T23:10:36Z",
"ts_updated_iso": "2016-05-09T11:17:02Z",
"storefront": "de"
"tracking_provider": "DHL",
"tracking_code": "00340434161221754211",
"status": "label_generated",
"return_units": {
[
{
"id_return_unit": 4134,
"id_return": 3800,
"id_order_unit": 2312312451,
"ts_created_iso": "2016-05-07T22:00:14Z",
"status": "need_to_be_returned",
"note": "Sadly not the right size.",
"reason": "wrong_size",
"storefront": "de"
}
]
},
"buyer": {
"id_buyer": 3124124,
"email": "john.doe@example.de"
}
}
}
Updating a Return's Status
After you receive a package that a customer has sent, you can either accept or reject the return. Normally you will accept the return.
Note: We prevent the updating of return units fulfilled by Kaufland and respond with a HTTP 403 error code. Read more about FBK.
Accepting a return
To accept a return, first get the correct return unit, possibly by searching by tracking number (see above).
Then, send a PATCH
request to the /return-units/{id_return_unit}/accept
endpoint.
Example:
PATCH https://sellerapi.kaufland.com/v2/return-units/234223423/accept
Rejecting a return
Sometimes, you might need to reject a return. For example, if the package you received did not contain the
correct product. To reject a package, you need to send a PATCH
request to the
/return-units/{id_return_unit}/reject
endpoint with a message
explaining why you could not accept the return.
Example:
PATCH https://sellerapi.kaufland.com/v2/return-units/234223423/reject
Request body:
{
"message": "The customer sent the wrong product"
}
Note: this will automatically open a new ticket on the related order unit and add a ticket message with the content of
the message
field that you send in the request.
Repairing a return
Even if the return period has expired, if the unit is still within it's warranty period you can accept a return for repairing.
To repair a return, first get the correct return unit, possibly by searching by tracking number (see above).
Then, send a PATCH
request to the /return-units/{id_return_unit}/repair
endpoint.
Example:
PATCH https://sellerapi.kaufland.com/v2/return-units/234223423/repair
Once the unit is repaired you will send it back to the customer.
Clarifying a return
If you cannot process a return unit due to some issue, then you can clarify the return unit. To clarify a package,
you need to send a PATCH
request to the /return-units/{id_return_unit}/clarify
endpoint
with a message indicating what needs to be done in order for you to be able to further process the return unit.
Example:
PATCH https://sellerapi.kaufland.com/v2/return-units/234223423/clarify
Request body:
{
"message": "The returned product is incomplete. Please resend any missing components."
}
Note: this will automatically open a new ticket on the related order unit and add a ticket message with the content of
the message
field that you send in the request.