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 accidentally
bad_quality: The delivered order unit had a bad quality
better_price: Got better price for this product
defect: The delivered order unit is defect
delivered_damaged: Product is damaged
dislike: Dislike the product
misleading_description: Product description is misleading
missing_parts: Missing parts of the product
no_reason: There is no reason for the return
too_late: The order unit was delivered too late
wrong_article: The delivered order unit was incorrect
wrong_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": "[email protected]"
		}
	}
}

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.