Managing Orders

Overview

On the real.de Onlineshop site, a checkout is equivalent to one total purchase from a customer. In a single checkout, the customer can buy multiple items from multiple sellers, although they only went through the checkout process one time. When this happens, the real.de Onlineshop system automatically creates a separate order for each seller in the checkout.

Each order is composed of one or more order units, each corresponding to a unit. If the same unit gets ordered several times, several order units are created. These diagrams show the structure of two different orders:

As you can see in the diagrams, each checkout has one or more orders and each order has one or more order units. Similarly, each order unit is connected to a unit (also called an offer), which in turn is connected to a seller.

Retrieving Orders

You can retrieve your orders by sending GET requests to the /orders/seller/ endpoint. This endpoint will give you only those orders for which you are the seller. If a customer has orders from multiple sellers in a single checkout, you will not be able to see the orders from the other sellers.

So, to get your recent orders, you can send this request:

GET https://www.real.de/api/v1/orders/seller/

In the response you will get an array of order IDs, like this:

[
	{
		"seller_units_count": 2,
		"id_order": "MHRYPC1",
		"ts_created": "2016-05-31 13:59:23",
        "ts_units_updated": "2019-07-19 17:24:05"
	},
	{
		"seller_units_count": 1,
		"id_order": "M8CXTB1-2",
		"ts_created": "2016-05-06 23:07:41",
        "ts_units_updated": "2018-10-01 17:24:05"
	},
	{
		"seller_units_count": 1,
		"id_order": "MWUATB1-2",
		"ts_created": "2016-05-05 13:20:49",
        "ts_units_updated": "2016-05-05 17:24:05"
	},
	{
		"seller_units_count": 1,
		"id_order": "MTTUTB1-2",
		"ts_created": "2016-05-02 06:25:20",
        "ts_units_updated": "2016-07-20 17:24:05"
	}
]

You also get the total number of units that were bought in each order, in the seller_units_count property.

To get the units in each order, you must query the orders individually via the /orders/{id_order}/ endpoint.

Retrieving Order Units

You can also retrieve your order units directly, without going through the orders, by sending GET requests to the /order-units/seller/ REST API endpoint. Usually you will want to add the status query parameter. For example, to get all of the items that you need to send to customers, you can send this request:

GET https://www.real.de/api/v1/order-units/seller/?status=need_to_be_sent

In the response you will get an array of order units, like this:

[
	{
		"id_order_unit": 314567828995811,
		"id_order": "MBXGYR",
		"ts_created": "2013-12-01 22:37:27",
		"ts_updated": "2013-12-01 22:37:28",
		"status": "need_to_be_sent",
		"cancel_reason": null,
		"price": 4615,
		"id_offer": "286419401",
		"revenue_gross": 3928,
		"revenue_net": 3301,
		"note": "Your personal note for this unit - it is displayed to the customer on the product page.",
		"unit_condition": "new",
		"delivery_time": "b",
		"delivery_time_expires": "2013-12-04 22:37:28",
		"shipping_rate": "0"
		"buyer": {
			"id_buyer": 24972423,
			"email": "john.doe@example.de"
		},
		"claim": null,
		"billing_address": {
			"first_name": "John",
			"last_name": "Doe",
			"gender": "male",
			"company_name": "",
			"street": "Bonnerstraße",
			"house_number": "73",
			"postcode": "53117",
			"city": "Bonn",
			"phone": "02289001",
			"country": "DE"
		},
		"shipping_address": {
			"first_name": "John",
			"last_name": "Doe",
			"gender": "male",
			"company_name": "",
			"street": "Bonnerstraße",
			"house_number": "73",
			"postcode": "53117",
			"city": "Bonn",
			"phone": "02289001",
			"country": "DE"
		},
		"invoice": {
			"number": "R0516-2211451",
			"type": "invoice_buyer",
			"url": "https://www.real.dev/dynamic/files/invoices/18729484/?key=f2d1454426c530f648e9"
		},
		"item": {
			"id_item": 4294967296,
			"title": "Such an awesome title for an item",
			"eans": {
					0: "4024144772148"
			},
			"id_category": 45181,
			"main_picture": "https://media.real.de/images/items/original/a5b07911e5859c2fc6c7a2852d2da33f.jpg",
			"manufacturer": "DuckProducer",
			"url": "https://www.real.de/product/58097801/"
		}
	},
	{
		"id_order_unit": 314567828995812,
		"id_order": "MBXGYX",
		"ts_created": "2013-12-01 22:37:27",
		"ts_updated": "2013-12-01 22:37:28",
		"status": "need_to_be_sent",
	    "cancel_reason": null,
    	"price": 5615,
		"id_offer": "386419401",
		"revenue_gross": 4928,
		"revenue_net": 4301,
		"note": "Your personal note for this unit - it is displayed to the customer on the product page.",
		"unit_condition": "new",
		"delivery_time": "a",
		"delivery_time_expires": "2013-12-04 22:37:28",
		"shipping_rate": "0"
		"buyer": {
			"id_buyer": 24972424,
			"email": "jane.doe@example.de"
		},
		"claim": {
			"id_claim": 10101,
			"id_order_unit": 314567828995812,
			"id_buyer": 24972424,
			"ts_created": "2013-12-15 22:39:28",
			"ts_updated": "2013-12-15 22:40:28",
			"status": "opened",
			"open_reason" "product_not_delivered",
			"callback_phone": "02289001",
			"is_seller_responsible": true
		},
		"billing_address": {
			"first_name": "Jane",
			"last_name": "Doe",
			"gender": "female",
			"company_name": "",
			"street": "Bonnerstraße",
			"house_number": "73",
			"postcode": "53117",
			"city": "Bonn",
			"phone": "02289001",
			"country": "DE"
		},
		"shipping_address": {
			"first_name": "Jane",
			"last_name": "Doe",
			"gender": "male",
			"company_name": "",
			"street": "Bonnerstraße",
			"house_number": "73",
			"postcode": "53117",
			"city": "Bonn",
			"phone": "02289001",
			"country": "DE"
		},
		"invoice": {
			"number": "R0516-2211452",
			"type": "invoice_buyer",
			"url": "https://www.real.dev/dynamic/files/invoices/18729484/?key=f2d1454426c530f648e8"
		},
		"item": {
			"id_item": 4294967296,
			"title": "Such an awesome title for an item",
			"eans": {
				0: "4024144772148"
			},
			"id_category": 45181,
			"main_picture": "https://media.real.de/images/items/original/a5b07911e5859c2fc6c7a2852d2da33f.jpg",
			"manufacturer": "DuckProducer",
			"url": "https://www.real.de/product/58097801/"
		}
	}
]

You can then use the id_order_unit property of each item in the array to do a separate request to the /order-units/{id_order_unit}/ endpoint to get the full information for a single order unit.

Note: if a customer orders multiple items from you, they will be listed individually as separate order units. To find all the items you need to send to each customer, you will have to combine all of the order units that have the same id_order.

Note: the result is limited by default - please read how to handle pagination.

Marking Orders as Sent

After shipping the item(s), you have to send a PATCH request to the /order-units/{id_order_unit}/send/ endpoint, with the carrier_code and tracking_number in the body. For example, for the above order unit, you would sent this request:

PATCH https://www.real.de/api/v1/order-units/314567828995811/send/

With this as the request body:

{
	"carrier_code": "DHL",
	"tracking_number": "12345678901234567890"
}

The list of allowed values for the carrier_code field is available on the Inventory CSV files page. You may also specify multiple tracking numbers by separating them with a comma ,:

{
	"carrier_code": "DHL",
	"tracking_number": "12345678901234567890,09876543210987654321"
}

Marking Orders as In Fulfilment

This is only relevant for sellers, who have obliged to confirm fulfilment. After starting to prepare the item(s), you have to send a PATCH request to the /order-units/{id_order_unit}/fulfil/ endpoint. For example, for the above order unit, you would sent this request:

PATCH https://www.real.de/api/v1/order-units/314567828995811/fulfil/

Canceling Orders

If you must cancel an order, you can do so through the REST API. You have to send a PATCH request to the /order-units/{id_order_unit}/cancel/ endpoint, with a valid reason in the body.

Example:

PATCH https://www.real.de/api/v1/order-units/314567828995811/cancel/

Request body:

{
	"reason": "NoInventory",
}

The allowed values for the reason field are available on the Inventory CSV Files page.

Send a refund for a particular order unit

In order to send a refund to a customer, you should send a PATCH request to /order_units/{id_order_unit}/refund/. In the body of the request, you have to specify the amount in Eurocents and the reason for the refund.

Example:

PATCH https://www.real.de/api/v1/order_units/314567843241527/refund/

Request body:

{
	"amount": 2999,
	"reason": "delivery_delay"
}

Allowed values for the field reason are: