### Getting a Product (GET) Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=code-examples.md This example demonstrates how to retrieve product information using a GET request to the /v2/products/{id} endpoint. It includes query parameters for embedding category and unit details and shows the full request and response structure. ```APIDOC ## GET /v2/products/{id} ### Description Retrieves detailed information about a specific product, including its category and unit details. ### Method GET ### Endpoint /v2/products/{id}?embedded=category,units ### Parameters #### Query Parameters - **embedded** (string) - Optional - Specifies which related data to embed in the response. Example: `category,units` ### Request Example ```php 'category,units', ]; //The query parameters must be URL-encoded, but the "=" and "&" signs should not be encoded $uri .= '?' . http_build_query($params); // Current Unix timestamp in seconds $timestamp = time(); // Name of your partner solution $userAgent = 'test' // Define all the mandatory headers $headers = [ 'Accept: application/json', 'Shop-Client-Key: ' . $clientKey, 'Shop-Timestamp: ' . $timestamp, 'Shop-Signature: ' . signRequest('GET', $uri, '', $timestamp, $secretKey), 'User-Agent: ' . $userAgent, ]; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $uri); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $product = json_decode(curl_exec($ch), true); var_export($product); curl_close($ch); ?> ``` ### Response #### Success Response (200) - **id_product** (integer) - The unique identifier for the product. - **title** (string) - The title of the product. - **eans** (object) - An object containing the product's EANs. - **id_category** (integer) - The identifier for the product's category. - **main_picture** (string) - The URL of the product's main image. - **manufacturer** (string) - The manufacturer of the product. - **url** (string) - The URL to the product on the Kaufland website. - **category** (object) - Detailed information about the product's category. - **units** (object) - An object containing details about the product's units/offers. #### Response Example ```json { "id_product": 20574181, "title": "PHP and MySQL for Dummies", "eans": { 0: "9780470527580" }, "id_category": 53021, "main_picture": "https://media.kaufland.de/images/items/original/567ff112bb416618b057802817dfe1d2.jpg", "manufacturer": "For Dummies", "url": "https://www.kaufland.de/product/20574181/", "category": { "id_category": 53021, "name": "naturwissenschaften-medizin-informatik-und-technik-buecher", "id_parent_category": 6261, "title_singular": "Naturwissenschaften, Medizin, Informatik & Technik", "title_plural": "Naturwissenschaften, Medizin, Informatik & Technik", "level": 3, "url": "https://www.kaufland.de/naturwissenschaften-medizin-informatik-und-technik-buecher/", "shipping_category": "A", "variable_fee": "12.50", "fixed_fee": 0, "vat": "7.00" }, "units": { 0: { "id_unit": 99792311008, "id_product": 20574181, "condition": "new", "location": "DE", "warehouse": "Theresa GmbH - Lager: 1024", "amount": 1, "price": 2639, "delivery_time_min": 3, "delivery_time_max": 8, "shipping_group": null, "note": "Versand durch DHL", "seller": { "pseudonym": "Tolle Buecher" }, "shipping_rate": 0 }, 1: { "id_unit": 105194581008, "id_product": 20574181, "condition": "new", "location": "DE", "warehouse": "Kevin GmbH - Lager: 1262" "amount": 1, "price": 2890, "delivery_time_min": 2, "delivery_time_max": 6, "shipping_group" "paket", "note": "Bei Fragen helfen wir gerne.", "seller": { "pseudonym": "Buecherland" }, "shipping_rate": 430 } } ``` ``` -------------------------------- ### Get Returns - 200 OK Response Example Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=endpoints Example JSON response for a successful request to retrieve returns. Includes return data and pagination details. ```json { "data": [ { "id_return": 0, "ts_created_iso": "2021-07-24T19:26:05Z", "ts_updated_iso": "2021-07-24T19:26:05Z", "storefront": "de", "tracking_provider": "DHL", "tracking_code": "407875042681", "status": "return_requested", "fulfillment_type": "fulfilled_by_kaufland" } ], "pagination": { "offset": 30, "limit": 10, "total": 200 } } ``` -------------------------------- ### Product List Response Example (JSON) Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=endpoints Example of a successful response when retrieving a list of products. Includes product details and pagination information. ```json { "data": [ { "id_product": 2, "storefront": "de", "title": "Ein unmoralisches Angebot", "eans": [ "4010884503135" ], "id_category": 6201, "main_picture": "https://media.cdn.kaufland.de/product-images/original/668f121c18ec6e2a8eb0888c6e3c5447.jpg", "manufacturer": "", "url": "https://www.kaufland.de/product/2/", "age_rating": 12, "is_valid": true, "dangerous_goods_li_shipping": null, "danger_label_9A": null } ], "pagination": { "total": 1, "limit": 20, "offset": 0 } } ``` -------------------------------- ### Python Full Example for HMAC Signature Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=rest-api.md A complete Python example demonstrating how to use the sign_request function with specific request parameters to generate a Shop-Signature. ```python #!/usr/bin/python import hmac import hashlib import time def sign_request(method, uri, body, timestamp, secret_key): plain_text = "\n".join([method, uri, body, str(timestamp)]) digest_maker = hmac.new(secret_key.encode(), None, hashlib.sha256) digest_maker.update(plain_text.encode()) return digest_maker.hexdigest() method = "POST" uri = "https://sellerapi.kaufland.com/v2/units/" body = "" timestamp = 1411055926 # time.time() secret_key = "a7d0cb1da1ddbc86c96ee5fedd341b7d8ebfbb2f5c83cfe0909f4e57f05dd403" print(sign_request(method, uri, body, timestamp, secret_key)) # da0b65f51c0716c1d3fa658b7eaf710583630a762a98c9af8e9b392bd9df2e2a ``` -------------------------------- ### PHP Full Example for HMAC Signature Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=rest-api.md A complete PHP example demonstrating how to use the signRequest function with specific request parameters to generate a Shop-Signature. ```php 'category,units', ]; //The query parameters must be URL-encoded, but the "=" and "&" signs should not be encoded $uri .= '?' . http_build_query($params); // Current Unix timestamp in seconds $timestamp = time(); // Name of your partner solution $userAgent = 'test' // Define all the mandatory headers $headers = [ 'Accept: application/json', 'Shop-Client-Key: ' . $clientKey, 'Shop-Timestamp: ' . $timestamp, 'Shop-Signature: ' . signRequest('GET', $uri, '', $timestamp, $secretKey), 'User-Agent: ' . $userAgent, ]; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $uri); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $product = json_decode(curl_exec($ch), true); var_export($product); curl_close($ch); ``` -------------------------------- ### Success Response for Get Unit Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=endpoints Example of a successful response when retrieving unit details. This JSON structure includes comprehensive information about the unit, its product details, and fulfillment status. ```json { "data": { "status": "INCOMPLETE", "currency": "EUR", "id_unit": 1, "note": "string", "condition": "USED___ACCEPTABLE", "listing_price": 1, "minimum_price": 1, "price": 1, "id_offer": "string", "id_product": 1, "id_shipping_group": 1, "id_warehouse": 1, "amount": 1, "date_inserted_iso": "2026-06-01T08:10:00.334Z", "date_lastchange_iso": "2026-06-01T08:10:00.334Z", "handling_time": 0, "shipping_rate": 0, "storefront": "de", "transport_time_min": 1, "transport_time_max": 1, "product": { "id_product": 362524873, "storefront": "de", "title": "Apple iPhone 12 mini 64GB Schwarz", "eans": [ "0194252013212", "194252013212", "0194252012925" ], "id_category": 34401, "main_picture": "https://media.cdn.kaufland.de/product-images/2048x2048/7ddfbf37e8c5d3137179e1361c432246.jpg", "manufacturer": "Apple", "url": "https://www.kaufland.de/product/362524873/", "age_rating": 0, "is_valid": true, "dangerous_goods_li_shipping": "UN 3090", "danger_label_9A": "Nein" }, "fulfillment_type": "fulfilled_by_kaufland", "vat_indicator": "standard_rate", "eco_participation": 1, "battery_participation": 1 } } ``` -------------------------------- ### Get All Storefronts Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=endpoints Retrieve values for the 'storefront' parameter. ```HTTP GET /info/storefront ``` -------------------------------- ### Example JSON Response for Order Units Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=orders.md This is an example of the JSON response structure when retrieving order units. It includes details for multiple order units, buyer information, addresses, product details, and discounts. ```json { "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": "john.doe@example.de" }, "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 }, "discounts": [ { "discount_value": 500, "usage_type": "voucher" } ] }, { "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": "jane.doe@example.de" }, "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 }, "discounts": [] } ], "pagination": { "offset": 0, "limit": 0, "total": 0 } } ``` -------------------------------- ### Example Variant Suggestions CSV Data Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=variant-suggestions-files.md This is an example of a partial variant suggestions data file in the CSV format expected by the Kaufland marketplace. Note the semicolon separators and UTF-8 encoding. ```csv ean;parent_ean;variant_attributes;action 8945085546346;4124102788893;colour; 4124102788893;4124102788893;colour; 6484759040462;4124102788893;colour; 2493874020064;4124102788893;colour;encourage 1252445707071;4124102788893;colour;discourage 6633663891438;8514476545826;"height,colour";encourage 8514476545826;8514476545826;"height,colour";encourage 8911039691234;6867350126126;"weight,length";encourage 9066532731364;6867350126126;;discourage 6867350126126;6867350126126;;discourage 5202543304099;6867350126126;; 7862397008909;6867350126126;; ;;; ``` -------------------------------- ### Get Product by EAN Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=endpoints Retrieves a product by its EAN. ```APIDOC ## GET /products/ean/{ean} ### Description Get a product by EAN ### Method GET ### Endpoint /products/ean/{ean} ``` -------------------------------- ### GET /subscriptions Endpoint Enabled Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=releaselog.md Listing subscriptions is now enabled for all storefronts. ```http GET /subscriptions ``` -------------------------------- ### Get Product by ID Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=endpoints Retrieves a product by its unique identifier. ```APIDOC ## GET /products/{id_product} ### Description Get product by ID ### Method GET ### Endpoint /products/{id_product} ``` -------------------------------- ### Get Storefront Values Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=endpoints Retrieves all possible values for the 'storefront' parameter. ```APIDOC ## GET /info/storefront ### Description Retrieves all possible values for the 'storefront' parameter. ### Method GET ### Endpoint /info/storefront ``` -------------------------------- ### GET Request to Retrieve Order Units Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=orders.md Use this GET request to retrieve order units, filtering by status. For example, to get units that need to be sent. ```http GET https://sellerapi.kaufland.com/v2/order-units?status=need_to_be_sent ``` -------------------------------- ### Get Product Data by EAN Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=endpoints Retrieves your product data for a given EAN. ```APIDOC ## GET /product-data/{ean} ### Description Get your product data for an EAN ### Method GET ### Endpoint /product-data/{ean} ``` -------------------------------- ### Opening a ticket (POST) Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=code-examples.md This example demonstrates how to open a new ticket on an order unit using a POST request. It includes setting up credentials, defining the request body, and signing the request. ```APIDOC ## Opening a ticket (POST) ### Description This endpoint allows you to open a new ticket associated with a specific order unit. You need to provide the order unit ID, a reason for the ticket, and a message. ### Method POST ### Endpoint /v2/tickets ### Parameters #### Request Body - **id_order_unit** (array) - Required - The ID of the order unit for which to open a ticket. - **reason** (string) - Required - The reason for opening the ticket (e.g., "product_not_as_described"). - **message** (string) - Required - A detailed message explaining the issue. ### Request Example ```json { "id_order_unit": [ 1234567890 ], "reason": "product_not_as_described", "message": "Some message here" } ``` ### Response #### Success Response (201 Created) - **Location** (string) - The URL of the newly created ticket. Example: `/v2/tickets/2498572` ``` -------------------------------- ### GetOrderUnits Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=orders.md Retrieves order units directly. It is recommended to use the `status` query parameter to filter results, for example, to get all products that need to be sent to customers. ```APIDOC ## GET /order-units ### Description Retrieves a list of order units. This endpoint allows fetching order units directly, bypassing the need to go through the main orders endpoint. It is common to filter by `status`. ### Method GET ### Endpoint /v2/order-units ### Parameters #### Query Parameters - **status** (string) - Optional - Filters the order units by their status. For example, `need_to_be_sent` can be used to retrieve units that require shipment. ### Request Example `GET https://sellerapi.kaufland.com/v2/order-units?status=need_to_be_sent` ### Response #### Success Response (200) Returns an array of order units. Each order unit object contains details such as `id_order_unit`, `id_order`, timestamps, status, pricing information, buyer details, billing and shipping addresses, product information, and any applicable discounts. #### Response Example ```json { "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": "john.doe@example.de" }, "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 }, "discounts": [ { "discount_value": 500, "usage_type": "voucher" } ] } ], "pagination": { "offset": 0, "limit": 0, "total": 0 } } ``` ### Important Notes Starting March 2023, buyers have a 15-minute window to cancel order units before shipment. To prevent premature shipment, customer addresses will only be available after this cancellation period expires. In such cases, the response array will reflect this delay. ``` -------------------------------- ### Embedded Values Example Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=rest-api.md Illustrates how to use the 'embedded' GET parameter to request additional fields within an object. This allows for richer responses by including related data directly. ```APIDOC ## Embedded Values By default the API returns a default group of fields for each `Object`, but some endpoints allow optionally requesting additional fields. For example, when getting information about a single product (see [code example](https://sellerapi.kaufland.com/?page=rest-api#example-get-item-anchor) below) it's possible to embed the product's category and units in the Product object. These optional fields are controlled through the `embedded` GET parameter, which contains a comma-separated list of desired additional fields. For example, the request `GET /product/20574181?embedded=category,units` will return the product `Object` with the "category" property set to the product's category `Object` and the property "units" set to the product's `Collection` of units. ``` -------------------------------- ### Example Offer JSON for a Product Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=getting-started.md This JSON object defines the details of a product offer, including EAN, condition, pricing, stock amount, delivery times, and location. Ensure all required fields are present and correctly formatted. ```json { "ean": "4011905437873", "condition": "new", "listing_price": 4550, "minimum_price": 3990, "amount": 9, "note": "Important notes for the customer", "delivery_time_min": 3, "delivery_time_max": 8, "location": "DE" } ``` -------------------------------- ### Get Variant Suggestions Feed List Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=endpoints Get import files for variant suggestions. ```APIDOC ## GET /variant-suggestions/feed ### Description Get import files for variant suggestions. ### Method GET ### Endpoint /variant-suggestions/feed ``` -------------------------------- ### Example Full Return Information Response Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=returns.md A sample JSON response detailing a return, its units, and buyer information. ```json { "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" } } } ``` -------------------------------- ### Get Variant Suggestions Feed by ID Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=endpoints Get a specific import file for variant suggestions by its ID. ```APIDOC ## GET /variant-suggestions/feed/{id_import_file} ### Description Get a specific import file for variant suggestions by its ID. ### Method GET ### Endpoint /variant-suggestions/feed/{id_import_file} ### Parameters #### Path Parameters - **id_import_file** (string) - Required - The ID of the import file. ``` -------------------------------- ### GET /order-units Endpoint Schema Change Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=releaselog.md Removed 'gender' from 'billing_address' and 'shipping_address' within the GET /order-units endpoint. ```http GET /order-units/ ``` -------------------------------- ### Example Shared Set JSON Response Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=product-data.md This is an example of the JSON response structure when searching for shared set values. ```JSON { "data": [ { "label": "Braun", "value": "Braun" }, { "label": "Bunt", "value": "Bunt" }, { "label": "Schwarz", "value": "Schwarz" }, { "label": "Rot", "value": "Rot" }, { "label": "Orange", "value": "Orange" }, { "label": "Weiß", "value": "Weiß" }, { "label": "Hellbraun", "value": "Hellbraun" }, { "label": "Hellblau", "value": "Hellblau" }, { "label": "Silber", "value": "Silber" }, { "label": "Rosa", "value": "Rosa" }, { "label": "Blau", "value": "Blau" }, { "label": "Grau", "value": "Grau" }, { "label": "Beige", "value": "Beige" }, { "label": "Dunkelbraun", "value": "Dunkelbraun" }, { "label": "Hellgrau", "value": "Hellgrau" }, { "label": "Dunkelgrau", "value": "Dunkelgrau" }, { "label": "Grün", "value": "Grün" }, { "label": "Bronze", "value": "Bronze" }, { "label": "dunkelgrün", "value": "dunkelgrün" }, { "label": "Gold", "value": "Gold" }, { "label": "Pink", "value": "Pink" }, { "label": "Gelb", "value": "Gelb" }, { "label": "Violett", "value": "Violett" } ], "pagination": { "offset": 0, "limit": 30, "total": 23 } } ``` -------------------------------- ### Adding a Unit (POST) Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=code-examples.md This example demonstrates how to add a new unit (offer) to a product using a POST request to the Kaufland Marketplace Seller API. It includes details on request parameters, headers, and expected success response. ```APIDOC ## POST /units/ ### Description Adds a new unit (offer) to a product on the Kaufland Marketplace. Requires a listing price greater than zero. ### Method POST ### Endpoint https://sellerapi.kaufland.com/v2/units/?storefront=de ### Parameters #### Query Parameters - **storefront** (string) - Required - The storefront the unit will be created on (e.g., 'de'). #### Request Body - **ean** (string) - Required - The EAN of the product. - **condition** (string) - Required - The condition of the unit (e.g., 'NEW'). - **listing_price** (integer) - Required - The listing price in cents. Must be greater than zero. - **minimum_price** (integer) - Required - The minimum price in cents. - **amount** (integer) - Required - The available quantity of the unit. - **note** (string) - Optional - A note for the unit. - **id_shipping_group** (integer) - Required - The ID of the shipping group. - **id_warehouse** (integer) - Required - The ID of the warehouse. - **id_product** (integer) - Required - The ID of the product. - **id_offer** (string) - Required - A unique identifier for the offer. - **handling_time** (integer) - Required - The handling time in days. ### Request Example ```json { "ean": "9780470527580", "condition": "NEW", "listing_price": 4550, "minimum_price": 3990, "amount": 9, "note": "My example note", "id_shipping_group": 1, "id_warehouse": 1, "id_product": 1, "id_offer": "My own unit identifier", "handling_time": 1 } ``` ### Response #### Success Response (201) - **Location** (string) - The URL to the newly created unit. #### Response Example ``` HTTP Response Code: 201 Location: /units/151177892008/ ``` ``` -------------------------------- ### Collection Pagination Example Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=rest-api.md Demonstrates how to use 'limit' and 'offset' query parameters to paginate through collections of data. The 'pagination' object in the response provides details about the current page and total number of items. ```APIDOC ## Collection Pagination Some API requests may return very large `Collection`s of values. For example, you may have thousands of units for sale on the Kaufland marketplace, and a `GET /units` request would attempt to return all of them. To make the responses more manageable, the results will be split into smaller groups or pages. Which page is returned in the response and how many `Object`s it contains are controlled by the `limit` and `offset` GET parameters. The default and maximum `limit` are endpoint dependent and are listed for each endpoint on the [endpoint documentation page](https://sellerapi.kaufland.com/?page=endpoints). The default `offset` is always 0. Examples: - `GET /categories` will return 20 categories, since the default value of `limit` for the `/categories` endpoint is 20. - `GET /categories?limit=15` will return 15 categories. - `GET /categories?limit=10&offset=7` will return 10 categories, starting at the 8th one. Each response which returns a `Collection` contains an additional object `pagination` in the body which provides information about `offset`, `limit` & `total`. For example, in response to the request `GET /categories/?limit=25&offset=5`, the body will contain the following pagination information (assuming the total number of categories is 5530): ```json { "data": [ ... ], "pagination": { "offset": 5, "limit": 25, "total": 5530 } } ``` If you are familiar with SQL, the `offset` and `limit` query parameters behave just like the `OFFSET` and `LIMIT` SQL keywords. ``` -------------------------------- ### GET /orders/{id_order} Endpoint Schema Change Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=releaselog.md Removed 'gender' from 'billing_address' and 'shipping_address' within the GET /orders/{id_order} endpoint. ```http GET /orders/{id_order} ``` -------------------------------- ### Initialize Return Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=endpoints Initiates a new return process for a given order unit. ```APIDOC ## POST /returns/initialize ### Description Initializes a return for a specific order unit. This is the first step in the return process. ### Method POST ### Endpoint /returns/initialize ### Request Body - **data** (InitializeReturnRequest) - Required - The request body containing details to initialize the return. - **orderUnitId** (string) - Required - The ID of the order unit for which to initialize the return. - **reason** (string) - Required - The reason for the return. ### Request Example ```json { "orderUnitId": "123456789", "reason": "Item defective" } ``` ### Response #### Success Response (200) - **data** (InitializeReturn) - Details of the initialized return. - **returnId** (string) - The unique identifier for the newly created return. - **returnStatus** (string) - The initial status of the return. ``` -------------------------------- ### GET /order-units/{id_order_unit} Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=releaselog.md Added the `delivery` attribute to the `GET /order-units/{id_order_unit}` endpoint, providing pickup location specific information when requested. ```APIDOC ## GET /order-units/{id_order_unit} ### Description Retrieves details for a specific order unit. The `delivery` attribute can be embedded to include pickup location details. ### Method GET ### Endpoint `/order-units/{id_order_unit}` ### Parameters #### Query Parameters - **embedded** (string) - Optional - Allows embedding additional data, including "delivery". ### Response #### Success Response (200) - **delivery** (object | null) - Contains pickup location specific information if available. Includes fields like `pickup_location_id`, `provider`, `carrier`, `services`, and `dhl_post_number`. ``` -------------------------------- ### Create Product Data Import File Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=endpoints Adds a new import file URL for product data. ```APIDOC ## POST /product-data/import-files ### Description Add an import file URL ### Method POST ### Endpoint /product-data/import-files ``` -------------------------------- ### Full Inventory Update Request Example Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=inventory.md Demonstrates a request body with three unit updates: one successful, one with a validation error, and one with an internal server error. ```json [ { "id_unit": 12345, "unit_data": { "handling_time": 4, } }, { "id_unit": 45678, "unit_data": { "listing_price": 0, } }, { "id_unit": 68576, "unit_data": { "note": "", } } ] ``` -------------------------------- ### Subscription Response Source: https://github.com/slowptr/kaufland-marketplace-seller-api-reference/blob/main/sellerapi.kaufland.com__page=push-notifications.md Example response body after successfully subscribing to an event. It confirms the subscription details and its active status. ```json { "data": { "id_subscription": 11011, "callback_url": "https://example.com/hm_notifications.php", "fallback_email": "test@kaufland.de", "event_name": "order_new", "is_active": true, "storefront": "de" } } ```