Managing Product Data

Products

Product data and inventory data are kept separate in Kaufland marketplace API. Since multiple marketplace sellers can offer the same product for sale, we have a single set of product data per product, and multiple units (or offers) attached to the product data. Inventory data for a single product from a single seller is called a unit. You can visualize all the data for a single product like this:

The description for a product is created by combining information from multiple sources: product information services, marketplace sellers, manufacturers, and members of the Kaufland marketplace product data management team. We take all of these inputs and do our best to create a helpful and attractive product description from all of the information we have. We achieve this by keeping track of which information we get from each source and combining the source-specific data into a single, publicly-visible product description. This means that it's possible that some of the product data you upload will not be selected for the final product description.

With the REST API, you can search for products using the /products/ endpoint and giving it a query string. If you have the ID of a specific product, you can get it using the /products/{id_product} REST endpoint. And if you want to see all the units attached to the product, you can add the ?embedded=units query string. You can also get a product by an EAN at /products/ean/{ean}.

Note: since Kaufland is expanding its Kaufland marketplace to other countries, many of the product data endpoints need either a storefront parameter or a locale parameter.
  • - storefront parameter (e.g. de) refers to a specific country (e.g. Germany) of the Kaufland marketplace. When doing a query e.g. for a certain product using /products/search endpoint you must specify in which countries marketplace you are searching. The reason is that the products might look different in every country, due to blacklisting, specific country legal regulations, different naming conventions and translations. All allowed storefronts can be found using this endpoint /info/storefront.
  • - locale parameter (e.g. de-DE) enables providing product data for different languages (e.g. German). All allowed locales can be found using this endpoint /info/locale.

Categories

On the Kaufland marketplace, every product must belong to a category. The Kaufland marketplace has a multi-level category tree with over 5,000 categories in it, but products can only be in leaf categories in the tree. At the top level of the tree, we have the root category, which is guaranteed to have id_category = 1. Below that, we have 13 major product areas, as you can see here:

Getting category info

If you have a category's ID, you can get all of the available info for it using the /categories/{id_category}/ REST endpoint. For example, to get information about category #50551 for the German storefront de, you can send this request: GET https://sellerapi.kaufland.com/categories/50551?storefront=de.

Listing child categories

If you have a category's ID, you can get its children by using the /categories/ endpoint and passing the id_parent query parameter. For example, this request will return the 13 major product areas shown above: GET https://sellerapi.kaufland.com/categories/?id_parent=1.

Searching for categories

To search for categories with a specific name, you can use the /categories/ endpoint and pass the q query parameter. For example, to find all categories relating to TVs, you could make this request: GET https://sellerapi.kaufland.com/categories?q=fernseher&storefront=de.

Automatic category suggestions

There are two ways to have the Kaufland marketplace automatically suggest a category for your products. The first way is to send Product Data CSV files without a category specified. In this case, the system will do its best to automatically find the best category for your product, and it will place the product in that category. More details about this are available on the Product Data CSV Files page.

The second way to get automatic category suggestions is through an explicit API request. Instead of manually finding the best category for a product, you can ask the Kaufland marketplace API to suggest a category based on a product's data. You do this by sending the JSON data for a product to the /category/decide/ endpoint. You will get an array of categories back, ordered by the probability of being correct (the first item in the array is the most probable). For example, you could send this request for a cat scratching post:
Request: POST https://sellerapi.kaufland.com/categories/decide/
Body: 

{
	"item": {
		"title": "Trixie Kratzbaum Palamos 109 cm anthrazit, 43787",
		"description": "
Kratzbaum \"Palamos\" Kratzbäume
 
 • Für Katzen jeden Alters geeignet
 • Mit Plüsch-Bezug
 • Stämme mit Natursisal umwickelt
 • Schützen Möbel und Teppiche vor den natürlichen Kratzgewohnheiten der Katzen
 
 • H: 109 cm
 • 1 Bodenplatte, 39 x 39 cm
 • 5 Stämme, Ø: 9 cm, 1x 10 cm, 2x 32 cm , 2x 39 cm
 • 1 Höhle mit Plüscheinlage, 35 x 35 x 24 cm
 • 3 Liegeplatten, 1x 39 x 39 cm, 2x 29 x 29 cm
 • Mit Spielzeug am Gummiband
 • Anthrazit
 Kratzbäume
- Für Katzen jeden Alters geeignet - Mit Plüsch-Bezug - Stämme mit Natursisal umwickelt - Schützen Möbel und Teppiche vor den natürlichen Kratzgewohnheiten der Katzen
- H: 109 cm - 1 Bodenplatte, 39 x 39 cm - 5 Stämme, Ø: 9 cm, 1 x 10 cm, 2 x 32 cm , 2 x 39 cm - 1 Höhle mit Plüscheinlage, 35 x 35 x 24 cm - 3 Liegeplatten, 1 x 39 x 39 cm, 2 x 29 x 29 cm - Mit Spielzeug am Gummiband - Anthrazit",
		"manufacturer": "Trixie Heimtierbedarf"
	},
	"price": 5280
}

You will get a JSON response with an array of the five most likely categories for your product, like this: 

[
	{
		"id_category": 50551,
		"name": "kratzbaeume",
		"id_parent_category": 50541,
		"title_singular": "Kratzbaum",
		"title_plural": "Kratzbäume",
		"level": 5,
		"url": "https://www.kaufland.de/kratzbaeume/",
		"shipping_category": "D",
		"variable_fee": 8.5,
		"fixed_fee": 0,
		"vat": 19,
		"real_main_category_id": 0
	},
	{
		"id_category": 40641,
		"name": "gummibaender",
		"id_parent_category": 23041,
		"title_singular": "Gummiband",
		"title_plural": "Gummibänder",
		"level": 5,
		"url": "https://www.kaufland.de/gummibaender/",
		"shipping_category": "D",
		"variable_fee": 12.5,
		"fixed_fee": 0,
		"vat": 19,
		"real_main_category_id": 0
	},
	{
		"id_category": 18391,
		"name": "kettenkaesten",
		"id_parent_category": 16921,
		"title_singular": "Kettenkasten",
		"title_plural": "Kettenkästen",
		"level": 4,
		"url": "https://www.kaufland.de/kettenkaesten/",
		"shipping_category": "D",
		"variable_fee": 12.5,
		"fixed_fee": 0,
		"vat": 19,
		"real_main_category_id": 0
	},
	{
		"id_category": 17541,
		"name": "einstiegsleisten",
		"id_parent_category": 16851,
		"title_singular": "Einstiegsleiste",
		"title_plural": "Einstiegsleisten",
		"level": 4,
		"url": "https://www.kaufland.de/einstiegsleisten/",
		"shipping_category": "D",
		"variable_fee": 12.5,
		"fixed_fee": 0,
		"vat": 19,
		"real_main_category_id": 0
	},
	{
		"id_category": 11771,
		"name": "rutschautos",
		"id_parent_category": 9631,
		"title_singular": "Rutschauto",
		"title_plural": "Rutschautos",
		"level": 5,
		"url": "https://www.kaufland.de/rutschautos/",
		"shipping_category": "D",
		"variable_fee": 12.5,
		"fixed_fee": 0,
		"vat": 19,
		"real_main_category_id": 0
	}
]

Attributes

Every product consists of a set of attributes and their values. Each attribute describes one or more pieces of information about a product. For example, the title attribute contains the name or title of a product and the picture attribute contains a collection of pictures of the product. There are both required attributes and optional attributes. When you submit product data, each product must have a value for all required attributes, but optional attributes can be missing.

There are three kinds of attributes:

  • General Attributes: every product has these attributes.
  • Category-Specific Kaufland marketplace Attributes: these attributes are specific to the Kaufland marketplace category that the product is in.
  • User-Defined Attributes: these are attributes that you maintain in your inventory system that may or may not have an equivalent attribute in the Kaufland marketplace system.

To see a list of all general and category-specific attributes, use the endpoint /attributes/.

General Attributes

Every product can and should have these attributes attached to it. Whenever you send product data to the Kaufland marketplace, you should include as much of this data as possible.

  • ean The EAN(s) of the product. Generally, there is only one EAN per product, but some have multiples.
  • title The title or name of the product.
  • description A detailed description of the product. This field can contain HTML.
  • short_description A short description of the product. This field should not contain HTML.
  • picture One or more pictures.
  • list_price The manufacturer's suggested retail price (MSRP) of the product.
  • category The name of the category the product is in.
  • mpn The manufacturer part number of the product.
  • additional_attributes For Including other product attributes e.g. color, manufacturer.

Category-Specific Kaufland marketplace Attributes

Some attributes make sense for some products, but not others. For example, the Bicycles category has the colour, bicycle_size, and bicycle_frame_size attributes, but not the film_genre attribute. Which attributes are available for a product are determined by which category the product is in.

To get the available attributes for the products in a given category, use the /categories/{id_category}/ REST endpoint and include the embedded query parameter with both attributes options: optional_attributes,required_attributes. The embedded query parameter also can have values parent,children which will include in the response parent or children category respectively.

Example: list the attributes for the Bicycles category for German with this request:

GET https://sellerapi.kaufland.com/categories/43011?embedded=optional_attributes&embedded=required_attributes&storefront=de.

This will return a JSON description of the category and its attributes: 

{
	"id_category": 43011,
	"name": "fahrraeder",
	"id_parent_category": 12261,
	"title_singular": "Fahrrad",
	"title_plural": "Fahrräder",
	"level": 4,
	"url": "https://www.kaufland.de/fahrraeder/",
	"shipping_category": "D",
	"variable_fee": 8.5,
	"fixed_fee": 0,
	"vat": 19,
	"real_main_category_id": 70,
	"optional_attributes": [
		{
			"id_attribute": 11,
			"name": "target",
			"title": "Zielgruppen",
			"is_multiple_allowed": true,
			"type": "Text"
		},
		{
			"id_attribute": 41,
			"name": "description",
			"title": "Beschreibung",
			"is_multiple_allowed": true,
			"type": "Text"
		},
		{
			"id_attribute": 51,
			"name": "mpn",
			"title": "Herstellernummer",
			"is_multiple_allowed": false,
			"type": "TinyText"
		},
		{
			"id_attribute": 61,
			"name": "picture",
			"title": "Bild",
			"is_multiple_allowed": true,
			"type": "Picture"
		},
		{
			"id_attribute": 71,
			"name": "list_price",
			"title": "UVP",
			"is_multiple_allowed": false,
			"type": "Si_Eurocent"
		},
		{
			"id_attribute": 231,
			"name": "short_description",
			"title": "Kurzbeschreibung",
			"is_multiple_allowed": false,
			"type": "SmallText"
		},
		{
			"id_attribute": 351,
			"name": "colour",
			"title": "Farbe",
			"is_multiple_allowed": true,
			"type": "Text"
		},
		{
			"id_attribute": 1981,
			"name": "bicycle_size",
			"title": "Fahrradgröße",
			"is_multiple_allowed": false,
			"type": "Text"
		},
		{
			"id_attribute": 1991,
			"name": "bicycle_frame_size",
			"title": "Rahmenhöhe",
			"is_multiple_allowed": false,
			"type": "Si_Meter"
		},
		{
			"id_attribute": 3081,
			"name": "additional_categories",
			"title": "Zusätzliche Kategorien",
			"is_multiple_allowed": true,
			"type": "Text"
		}
	],
	"required_attributes": [
		{
			"id_attribute": 1,
			"name": "ean",
			"title": "EAN",
			"is_multiple_allowed": true,
			"type": "Ean"
		},
		{
			"id_attribute": 21,
			"name": "manufacturer",
			"title": "Hersteller",
			"is_multiple_allowed": false,
			"type": "Text"
		},
		{
			"id_attribute": 31,
			"name": "title",
			"title": "Titel",
			"is_multiple_allowed": false,
			"type": "ShortText"
		},
		{
			"id_attribute": 3071,
			"name": "category",
			"title": "Kategorie",
			"is_multiple_allowed": false,
			"type": "Text"
		}
	]
}

Each attribute has several properties:

  • id_attribute The internal ID of the attribute. Since an attribute can exist in multiple categories, this ID identifies an attribute across categories.
  • name The English name of the attribute. You should use this name when submitting product data.
  • title The German name of the attribute. This name is displayed to the user on the Kaufland marketplace website.
  • is_multiple_allowed True if the attribute can contain multiple values. For example, a single product can (and should!) have multiple pictures.
  • type The type of value that the attribute accepts. Most attributes accept any text value, but some have formatting descriptions. See the Attribute types section for a description of the types with formatting restrictions.

If you want to check a specific attribute you can use the REST endpoint and the attribute name (/attributes/by-name/{name}) or the attribute ID (/attributes/{id_attribute}).

Attribute types

Most attributes accept free text for their values, but some types of attributes have formatting restrictions that you should be aware of:

  • Si_* Any attribute type that starts with "Si_" is a numeric value in the International System of Units. When you submit a value for these attributes, it must contain a number and a unit suffix (e.g. Si_Meter could have any of the following values: 1m; 2,5m; 200.432,43m; 250mm; 7km.
  • Bool A boolean value. Accepts the following values: true, false, 0, 1, T, F, yes, no, Y, N, ja, nein.
  • Float A decimal number. The decimal separator should be a comma (,) and, if specified, the thousands separator should be a period (.).
  • Int A whole number without any decimal values.
  • Ean A valid EAN.
  • Date A date in the format d.m.Y, e.g. 23.10.2014.
  • Picture A publicly-accessible URL from which an image file can be downloaded. Acceptable image file types are jpg, png, and gif.
  • TinyText A text string with a maximum length of 256 characters.
  • ShortText A text string with a maximum length of 512 characters.
  • SmallText A text string with a maximum length of 1024 characters.
  • Text A text string with a maximum length of 65,535 characters.

User-Defined Attributes

Finally, you may send attributes to the Kaufland marketplace that the system does not know about yet. You can include any attribute name and value in the Product Data CSV file or provide it via the API endpoint for product data. It is a good idea to send all of the attribute information you have, since we can use this data in the future to expand the number and types of attributes we display for each product. For more details, see the User-Defined Attributes section of the Product Data CSV files page.

Shared sets

Besides the mentioned types of attributes, there's the concept of what we called Shared Sets. Shared sets are notable types of values, like colour or material. These are shared enumerations, lists of values. The goal is the normalization of data. So, in the case of the Shared Set colour, instead of saving for every item with the color „yellow“ the value yellow to that item, the value yellow is in the shared set list for colour and has an id which gets referenced by that item attribute colour.

So, how can we search within those lists of values? Some of the lists can have a daunting amount of possible values (the example presented above, colour), so we provide an API endpoint to get possible, valid values of a given attribute similar to a provided query string. This search endpoint also allows to specify other languages (within our usual allowed locales). This way,

Example: knowing that the id for the color attribute is 351, list the first 30 possible or related values for the colour "Braun" for German with this request:

GET https://sellerapi.kaufland.com/v2/attributes/351/shared-set?locale=de-DE&q=Braun&limit=30&offset=0.

This will return a JSON list of the different values: 

{
    "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
    }
}

In addition to the search endpoint, we have recently added a new endpoint that provides a URL to download a CSV file. This file will contain all shared set values for a specified attribute ID and locale, similar to how the search endpoint is used.

Example: To get the URL for downloading all shared set values for the color attribute with ID 351 in the German locale, use the following request:

GET https://sellerapi.kaufland.com/v2/attributes/351/shared-set-values?locale=de-DE.

Note: for non-translatable shared sets, the same file will be returned regardless of the locale specified.

This endpoint returns a signed URL for a CSV file that contains the list of shared set values for a specific attribute ID. The CSV format will be:

Note: the signed URL is valid for 6 days. 

LABEL;VALUE
Schwarz;Schwarz
Grau;Grau
Weiß;Weiß
Braun;Braun
Beige;Beige
Rot;Rot
Grün;Grün
Gelb;Gelb
Orange;Orange
Blau;Blau
Türkis;Türkis
Rosa;Rosa
Violett;Violett
Silber;Silber
Gold;Gold
Bronze;Bronze
Transparent;Transparent
Pink;Pink
Bunt;Bunt
Kupfer;Kupfer
Taupe;Taupe
milchig;milchig
Hellgrau;Hellgrau
Dunkelgrau;Dunkelgrau
Hellblau;Hellblau
Dunkelblau;Dunkelblau
Ocker;Ocker
Hellbraun;Hellbraun
Lila;Lila
dunkelgrün;dunkelgrün
bordeaux;bordeaux
Dunkelbraun;Dunkelbraun
Naturbelassen;Naturbelassen
Hellgelb;Hellgelb
Dunkelgelb;Dunkelgelb
Hellrot;Hellrot
Dunkelrot;Dunkelrot
Hellorange;Hellorange
Dunkelorange;Dunkelorange
Hellrosa;Hellrosa
Dunkelrosa;Dunkelrosa
Hellviolett;Hellviolett
Dunkelviolett;Dunkelviolett
Limette;Limette
Cyan;Cyan
Magenta;Magenta
Kastanienbraun;Kastanienbraun
Olive;Olive
Blaugrün;Blaugrün
Marine;Marine
Fuchsia;Fuchsia
Himmelblau;Himmelblau
Aqua;Aqua
Koralle;Koralle
Petrol;Petrol
Königsblau;Königsblau

Uploading Product Data

There are two ways to upload your product data to the Kaufland marketplace: via the REST API or via CSV files. The REST API is good for uploading data for a few products, but you must send one HTTP request per product. CSV files are good for uploading data for many products, since you can batch update all of the products in a single file.

The Product Data REST Endpoint

The /product-data/ REST API endpoint allows you to upload product data for a single product. You send a JSON representation of the product as a JSON object, where the property names are your attribute names and the values are arrays of your values for the corresponding attributes. To add data for a new product that doesn't yet exist on the Kaufland marketplace platform, or to send improvements to the data for an existing product, send the JSON object in a PUT request. If you have never uploaded data for the given product, we will create a new product description associated with your account, which will get combined with data from other sources into the main description for the product. If you have already uploaded data for the given product, subsequent PUT requests will completely replace your uploaded data for the product. If you have already uploaded data for the given product, and you only want to change a subset of the data, you can send a PATCH request. This will overwrite the attributes you send and leave the rest of the attributes alone.

For example, you have a product with the EAN 4009750243800 and the title Chocolat. It has a description and in your system it's in the category Filme, so you would also provide this information. The JSON object for your product would then look like this: 

{
  "ean": [
    "4009750243800"
  ],
  "attributes": {
    "title": [
      "Chocolat"
    ],
    "description": [
      "In einem verschlafenen Städtchen in Frankreich im Jahr 1959. ...Doch am Ende zählt nur eins: Die pure Lust am Leben!"
    ],
    "category": [
      "Filme"
	]
  }
}

After you send the data to the Kaufland marketplace server, it is first checked with some heuristics to see if the data can be accepted. In some cases, the values you send will have to be manually reviewed by someone in our category management team. If this happens it can take some time, so you can check the status of your provided data via the /product-data/status/{ean} endpoint. The property update_status of the JSON object in the response will initially have the status PENDING. When automatic or manual checks are in process it returns the IN_PROGRESS status. If everything goes well and your data was successfully imported into your product description, the product will have the SUCCESS status. Otherwise, it will have the FAIL status. If the product data is in FAIL state, you can get information about the reason why the import failed in the update_fail_reason property.

Note: When we have successfully created a product description from your product data, you will have to provide an inventory unit to be able to see the product on the Kaufland marketplace site.
Note: For better compatibility and faster review of your data you can provide our attribute names to us. See the attributes section for more information.

Uploading Product Data via CSV File

The second method for uploading product data is with a CSV file. To send the CSV file to the Kaufland marketplace, you must first make it available for download on the public Internet via HTTP or HTTPS, then send the URL to the file to the Kaufland marketplace. We will download and process the file asynchronously, check the validity of the data in the file, then merge it into our system. Please notice that for the upload of product feed data there is a limit of 30 feeds per day, so please combine data for multiple products in one CSV file if possible.

Here are the steps necessary to import a CSV file into the Kaufland marketplace site:

  1. Create a product data CSV file (described on the Product Data CSV Files page).
  2. Upload the CSV file to a publicly-accessible web server. Let's say you upload it to http://www.example.com/my_products.csv.
  3. Send a POST request to the /product-data/import-file endpoint in the REST API. The body of the request should contain JSON with the URL. In our example, we would send this JSON: 
    {
	"url": "http://www.example.com/my_products.csv",
}
  4. Wait. Since each product data descriptor file may have to be manually checked by a person, it could be hours or days until your data is checked and merged into the system. You can check the current status of your file by using the /product-data/import-file REST API endpoint to get a list of all of your import files and what status they are in. If async_import_done of a file is set to 1, that means it has been successfully imported into the Kaufland marketplace site.
  5. Once your product data has been imported, upload your inventory data. Doing this is described on the Managing Inventory page.

Deleting Products

Because the Kaufland marketplace is a marketplace with many sellers, it's not possible to delete a product from the system. Even if you stop offering a product for sale, other sellers could still be selling it, so the product itself is never removed. Instead, you should remove all of your units for the product by sending DELETE requests to the /units/{id_unit}/ REST API endpoint.

However, it is possible to remove your product description data from the Kaufland marketplace. Sending a DELETE request to the /units/{id_unit}/ endpoint will remove your product data. The publicly-visible product description will then be updated to only include data from other sources.