Managing Returns

If you have enabled automatic returns in your real.de Onlineshop settings, customers will start the return process and automatically receive a shipping label when they want to return an item. This will create a return entry in the real.de Onlineshop system, which you can retrieve and update.

Initialize a return for order units

In order to initialize a return for one or multiple order units send a POST request to the /returns endpoint. A return can be initializes only for order units of one order.

Note: Only sellers who are using the real return service can use this method.

For example, to initialize a return for two order units:

POST https://www.real.de/api/v1/returns

Request body:

{
    "id_order_unit": [
		314567849801,
		314567849803,
		314567849803,
	],
    "reason": "defect",
    "note": "Scratch on the display"
  }

The note must contain at least 5 character.

Allowed values for the field reason are:

Retrieving Return Information

To retrieve the returns from your sales, you can use the /returns/seller/ endpoint in the REST API.

Finding all open returns

Example: getting all of the open returns from all of your customers

GET https://www.real.de/api/v1/returns/seller/?status=return_requested,label_generated,package_sent, package_received

Response:

[
	{
		"id_return": 77501,
		"ts_created": "2014-10-23 00:56:22",
		"ts_updated": "2014-11-06 16:32:15",
		"tracking_provider": "DHL",
		"tracking_code": "00340433836099527354",
		"status": "package_received"
	},
	{
		"id_return": 77461,
		"ts_created": "2014-10-22 21:24:30",
		"ts_updated": "2014-10-22 21:25:05",
		"tracking_provider": "DHL",
		"tracking_code": "00340433836099370622",
		"status": "label_generated"
	},
	{
		"id_return": 77451,
		"ts_created": "2014-10-22 20:40:53",
		"ts_updated": "2014-10-22 20:41:05",
		"tracking_provider": "DHL",
		"tracking_code": "00340433836099333948",
		"status": "label_generated"
	},
	{
		"id_return": 77441,
		"ts_created": "2014-10-22 20:09:17",
		"ts_updated": "2014-10-22 20:10:05",
		"tracking_provider": "DHL",
		"tracking_code": "00340433836099304757",
		"status": "label_generated"
	}
]

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://www.real.de/api/v1/returns/seller/?tracking_code=12345678901234567890

Retrieving Full Return Information

To update a return's status, you need to get the id_return_unit. Use GET /returns/{id_return}/?embedded=units,buyer to get full information.

Response:

{
	"id_return": 3800,
	"ts_created": "2016-05-07 23:10:36",
	"ts_updated": "2016-05-09 11:17:02",
	"tracking_provider": "DHL",
	"tracking_code": "00340434161221754211",
	"status": "label_generated",
	"units": {
		[
			{
				"id_return_unit": 4134,
				"id_return": 3800,
				"id_order_unit": 2312312451,
				"ts_created": "2016-05-07 22:00:14",
				"status": "need_to_be_returned",
				"note": "Leider nicht die richtige Größe.",
				"reason": "return"
			}
		]
	},
	"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.

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://www.real.de/api/v1/return-units/234223423/accept/

Rejecting a return

Sometimes, you might need to reject a return. For example, if you the package you received did not contain the correct item. 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://www.real.de/api/v1/return-units/234223423/reject/

Request body:

{
	"message": "The customer sent the wrong item"
}

Note: this will automatically open a new claim on the related offer unit and add a claim message with the content of the message field that you send in the request.

Repairing a return

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://www.real.de/api/v1/return-units/234223423/repair/

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://www.real.de/api/v1/return-units/234223423/clarify/

Request body:

{
	"message": "The returned item is incomplete. Please resend any missing components."
}

Note: this will automatically open a new claim on the related offer unit and add a claim message with the content of the message field that you send in the request.