Managing Orders

Overview

On the Kaufland marketplace, a checkout is equivalent to one total purchase from a customer. In a single checkout, the customer can buy multiple products from multiple sellers, although they only went through the checkout process one time. When this happens, the Kaufland marketplace 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 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://sellerapi.kaufland.com/v2/orders

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

{
	"data": [
		{
			"order_units_count": 2,
			"id_order": "MHRYPC1",
			"ts_created_iso": "2016-05-31T13:59:23Z",
			"ts_units_updated_iso": "2019-07-19T17:24:05T"
			"is_marketplace_deemed_supplier": false,
			"storefront": "de"
		},
		{
			"order_units_count": 1,
			"id_order": "M8CXTB1",
			"ts_created_iso": "2016-05-06 23:07:41",
			"ts_units_updated_iso": "2018-10-01T17:24:05Z"
			"is_marketplace_deemed_supplier": false,
			"storefront": "de"
		},
		{
			"order_units_count": 1,
			"id_order": "MWUATB1",
			"ts_created_iso": "2016-05-05 13:20:49",
			"ts_units_updated_iso": "2016-05-05T17:24:05Z"
			"is_marketplace_deemed_supplier": true,
			"storefront": "de"
		},
		{
			"order_units_count": 1,
			"id_order": "MTTUTB1",
			"ts_created_iso": "2016-05-02 06:25:20",
			"ts_units_updated_iso": "2016-07-20T17:24:05Z"
			"is_marketplace_deemed_supplier": false,
			"storefront": "de"
		}
	],
	"pagination": {
		"offset": 0,
		"limit": 0,
		"total": 0
	}
}

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

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

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

Note: By default this endpoint only returns orders which need to be fulfilled by the seller. To get orders fulfilled by Kaufland an appropriate filter parameter needs to be applied. Read more about FBK.

Retrieving Order Units

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

GET https://sellerapi.kaufland.com/v2/order-units?status=need_to_be_sent

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

{
	"data": [
		{
			"id_order_unit": 314567828995811,
			"id_order": "MBXGYR",
			"ts_created_iso": "2013-12-01T22:37:27Z",
			"ts_updated_iso": "2013-12-01T22:37:28Z",
			"is_marketplace_deemed_supplier": false,
			"status": "need_to_be_sent",
			"cancel_reason": null,
			"price": 4615,
			"id_offer": "286419401",
			"revenue_gross": 3928,
			"revenue_net": 3301,
			"vat": 19,
			"note": "Your personal note for this unit - it is displayed to the customer on the product page.",
			"unit_condition": "new",
			"storefront": "de",
			"delivery_time_min": 1,
			"delivery_time_max": 3,
			"delivery_time_expires_iso": "2013-12-01T22:37:27Z",
			"shipping_rate": 0
			"buyer": {
				"id_buyer": 24972423,
				"email": "[email protected]"
			},
			"billing_address": {
				"first_name": "John",
				"last_name": "Doe",
				"company_name": "",
				"street": "Bonnerstraße",
				"house_number": "73",
				"postcode": "53117",
				"city": "Bonn",
				"additional_field": "1. OG",
				"phone": "02289001",
				"country": "DE"
			},
			"shipping_address": {
				"first_name": "John",
				"last_name": "Doe",
				"company_name": "",
				"street": "Bonnerstraße",
				"house_number": "73",
				"postcode": "53117",
				"city": "Bonn",
				"additional_field": "1. OG",
				"phone": "02289001",
				"country": "DE"
			},
			"product": {
				"id_product": 4294967296,
				"title": "Such an awesome title for an product",
				"eans": {
						0: "4024144772148"
				},
				"id_category": 45181,
				"main_picture": "https://media.kaufland.de/images/items/original/a5b07911e5859c2fc6c7a2852d2da33f.jpg",
				"manufacturer": "DuckProducer",
				"url": "https://www.kaufland.de/product/58097801/",
				"real_mgb_article_number": "",
				"age_rating": 0,
				"is_valid": true,
				"dangerous_goods_li_shipping": null,
				"danger_label_9A": null
			}
		},
		{
			"id_order_unit": 314567828995812,
			"id_order": "MBXGYX",
			"ts_created_iso": "2013-12-01T22:37:27Z",
			"ts_updated_iso": "2013-12-01T22:37:28Z",
			"is_marketplace_deemed_supplier": false,
			"status": "need_to_be_sent",
			"cancel_reason": null,
			"price": 5615,
			"id_offer": "386419401",
			"revenue_gross": 4928,
			"revenue_net": 4301,
			"vat": 19,
			"note": "Your personal note for this unit - it is displayed to the customer on the product page.",
			"unit_condition": "new",
			"storefront": "de",
			"delivery_time_min": 1,
			"delivery_time_max": 3,
			"delivery_time_expires_iso": "2013-12-01T22:37:27Z",
			"shipping_rate": 0
			"buyer": {
				"id_buyer": 24972424,
				"email": "[email protected]"
			},
			"billing_address": {
				"first_name": "Jane",
				"last_name": "Doe",
				"company_name": "",
				"street": "Bonnerstraße",
				"house_number": "73",
				"postcode": "53117",
				"city": "Bonn",
				"additional_field": "1. OG",
				"phone": "02289001",
				"country": "DE"
			},
			"shipping_address": {
				"first_name": "Jane",
				"last_name": "Doe",
				"company_name": "",
				"street": "Bonnerstraße",
				"house_number": "73",
				"postcode": "53117",
				"city": "Bonn",
				"additional_field": "1. OG",
				"phone": "02289001",
				"country": "DE"
			},
			"product": {
				"id_product": 4294967296,
				"title": "Such an awesome title for an product",
				"eans": {
					0: "4024144772148"
				},
				"id_category": 45181,
				"main_picture": "https://media.kaufland.de/images/items/original/a5b07911e5859c2fc6c7a2852d2da33f.jpg",
				"manufacturer": "DuckProducer",
				"url": "https://www.kaufland.de/product/58097801/",
				"real_mgb_article_number": "",
				"age_rating": 0,
				"is_valid": true,
				"dangerous_goods_li_shipping": null,
				"danger_label_9A": null
			}
		}
	],
	"pagination": {
		"offset": 0,
		"limit": 0,
		"total": 0
	}
}

Important:

Starting from March 2023, buyers will be provided with a 15-minutes time window for easy cancelling order_units even before they are shipped. In order to prevent premature shipment by sellers, customer addresses will be available only after expiration of that time period.

In this case the array of order units in the response will then show status = "open" and all customer addresses will be null. Therefore, sellers will not be able to mark order units as sent until the order status changes from "open" to "need to be sent". This status change will be automatically done by us 15 minutes after order creation. To be on safe side we recommend a security margin of one minute, so that addresses can be reliable accessed after 16 minutes.

[
		{
			"id_order_unit": 314567828995811,
			...
			"status": "open",
			"billing_address": null
			"shipping_address": null
			...
		}
]

Note: Starting from March 2023, due to our cancellation prior to shipment program, addresses will be available only 15+1 minutes after checkout completion.

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

You can then use the id_order_unit property of each entity 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 products from you, they will be listed individually as separate order units. To find all the products you need to send to each customer, you will have to combine all of the order units that have the same id_order.

Note: By default this endpoint only returns order units which need to be fulfilled by the seller. To get order units fulfilled by Kaufland an appropriate filter parameter needs to be applied. Read more about FBK.

Retrieving Delivery (Pick-up & Drop-off) details

As of June 2023, we're introducing a new embedded attribute to the Order Unit endpoint to provide pickup location specific information.

Please note, this attribute will only be included in the response when explicitly requested as an embedded field, ensuring backwards compatibility with existing implementations. Moreover, it only becomes relevant once a seller has activated the pickup location delivery option through their shipping group configuration.

The delivery object is a new addition aimed at offering more nuanced and flexible delivery options, starting with pickup location deliveries.


{
    "id_order_unit": 314567828995811,
    ...
    "delivery": {
         "pickup_location": {
             "pickup_location_id": "260",
             "provider": "Packeta",
             "carrier": "Packeta",
             "services": "",
             "dhl_post_number": null
         }
     }
    ...
}

Attributes

delivery: Object | undefined
For now, the attribute delivery supports only pickup location deliveries.
The attribute is only responded when explicitly requested as an embedded field.
GET /order-units/{id_order_unit}?embedded=delivery
delivery.pickup_location: Object | null
The pickup_location field is null when the order unit is not delivered to pickup location.
Otherwise the object houses the details necessary for facilitating pickup location deliveries. It is composed of the following attributes:
delivery.pickup_location.pickup_location_id: String
The unique identifier for the pickup location. (Also known as branch ID) For Packeta this is going to be a numeric string, but for other carriers it may have a different format.
delivery.pickup_location.provider: String
Identifies the provider of the pickup location (e.g., DHL for Packstations).
delivery.pickup_location.carrier: String
Specifies the carrier responsible for delivering the order to the pickup location. In some instances, the carrier may be different from the provider.
delivery.pickup_location.services: String
Describes the delivery services associated with the pickup location delivery (e.g., inpost_locker_standard for deliveries to InPost pickup locations).
delivery.pickup_location.dhl_post_number: String | null
This field contains the DHL post number (Postnummer) for deliveries to DHL Packstations. This field is nullable and will only contain data for DHL deliveries.

In the future, we plan to expand the delivery object to include additional delivery solutions. We encourage sellers to begin familiarising themselves with this new addition to ensure a smooth transition as we introduce these new features.

Marking Orders as Sent

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

PATCH https://sellerapi.kaufland.com/v2/order-units/314567828995811/send

With this as the request body:

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

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

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

Note: We prevent this action for order units fulfilled by Kaufland and respond with a HTTP 403 error code. Read more about FBK.

Marking Orders as In Fulfilment

This is only relevant for sellers, who have obliged to confirm fulfillment. After starting to prepare the product(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://sellerapi.kaufland.com/v2/order-units/314567828995811/fulfil

Note: We prevent this action for order units fulfilled by Kaufland and respond with a HTTP 403 error code. Read more about FBK.

Canceling Orders

If you must cancel an order, you can do so through the 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://sellerapi.kaufland.com/v2/order-units/314567828995811/cancel

Request body:

{
	"reason": "NoInventory",
}

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

Note: We prevent this action for order units fulfilled by Kaufland and respond with a HTTP 403 error code. Read more about FBK.

Cancellation prior to shipment

In order to provide an easy cancellation process in the first 15 minutes after checkout the feature cancellation prior to shipment will be introduced. Introduction of this feature leads to changes in the way we process orders internally and may require some changes in your api client. The process becomes mandatory starting from 1.3.2023.

With the new feature cancellation prior to shipment in the first 15 minutes after checkout the shipping of order units will be prevented by holding back customer addresses in order to provide an easy cancellation process during this time window.

The process for cancellation prior to shipment:

Order units are created with status open when a customer places an order by completing the checkout process. For orders in this status addresses will not be visible when requesting order units form the API, to prevent sellers from premature shipment. So please ensure your API client is not depending requesting order unit addresses in the first 15+1 minutes after checkout. The one minute security margin allows our system for automatically updating the order_unit status.

15 minutes after order creation each order_unit will be automatically be forwarded from status open to status need_to_be_sent if the order has not been cancelled. This process will take less then one minute and results in us sending the order_unit_status_changed push notification. From this time on all order_units will contain the complete and correct customer addresses. Order_units then can be marked as sent using the process described on this page.

Customers will have the opportunity to cancel any order in the first 15 minutes after checkout by hitting a cancel button in the customer account area. Since during this time shipping of order units is prevented the stock can be recovered and the offer is free to be sold again.

How to implement on client side:

On receiving the order_created push notification seller inventory should be updated in order to reflect the order and prevent over selling.

After receiving the order_new/order_unit_new push notification the order_units will be available via seller API, however addresses will not included for the first 15+1 minutes after checkout. Here 15 minutes is the cancellation time window for customer and we recommend one minute security margin. Please make sure seller api does not rely on fetching addresses from the order_unit endpoint during this time period.

There are two recommended ways to fetch addresses from the order_units API endpoint:

1. Periodically calling the seller API order_units endpoint after order creation and check for availability of addresses. Once addresses are received the process of sending the order_units can be performed.

2. Calling the seller API order units endpoint once after receiving the order_unit_status_changed push notification if the status changed from open into need_to_be_send. After this push notification is received the customer addresses will reliably be available in the payload.

When implementing this solution before March 2023 please keep it backwards compatible by making sure that you do not rely on the event being sent. You can have a fallback to fetch addresses from order_units endpoint 15+1 minutes after order placement.

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 Cents and the reason for the refund.

Example:

PATCH https://sellerapi.kaufland.com/v2/order-units/314567843241527/refund

Request body:

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

Allowed values for the field reason are:

defect: The delivery had a defect
delivery_damage: The order unit was damaged during delivery
delivery_delay: There was a delay in delivery
incomplete_delivery: The delivery was incomplete
incorrect_delivery: The delivery was incorrect
other_refund: Some other refund reason
refund_postage_fee: The refund is for postage fee
refund_return_postage_fee: The refund is for the postage fee of the return