Managing Product Data

Items

Product data and inventory data data are kept separate in the real.de Onlineshop API. Since multiple marketplace sellers can offer the same product for sale, we have a single set of product data per item, and multiple units (or offers) attached to the product data. In our system, we call the product data for a single product an item. Inventory data for a single item 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 real.de Onlineshop 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 informati on 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 items using the /items/ endpoint and giving it a query string. If you have the ID of a specific item, you can get it using the /items/{id_item} REST endpoint. And if you want to see all the units attached to the item, you can add the ?embedded=units query string.

Categories

On the real.de Onlineshop site, every item must belong to a category. The real.de Onlineshop has a multi-level category tree with over 5,000 categories in it, but items 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, you can send this request: GET https://www.real.de/api/v1/categories/50551/

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://www.real.de/api/v1/categories/?id_parent=1

Searching for categories

To search for categories with a certain 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://www.real.de/api/v1/categories/?q=fernseher

Automatic category suggestions

There are two ways to have the real.de Onlineshop automatically suggest a category for your items. 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 item, and it will place the item 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 an item, you can instead ask the real.de Onlineshop API to suggest a category based on an item's data. You do this by sending the JSON data for an item to the /category/decide/ endpoint, and 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://www.real.de/api/v1/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 5 most likely categories for your item, like this:

[
	{
		"id_category": 50551,
		"name": "kratzbaeume",
		"id_parent_category": 50541,
		"title_singular": "Kratzbaum",
		"title_plural": "Kratzbäume",
		"level": 5,
		"url": "https://www.real.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.real.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.real.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.real.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.real.de/rutschautos/",
		"shipping_category": "D",
		"variable_fee": 12.5,
		"fixed_fee": 0,
		"vat": 19,
		"real_main_category_id": 0
	}
]

Attributes

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

There are three kinds of attributes:

General Attributes

Every item can and should have these attributes attached to it. Whenever you send product data to the real.de Onlineshop, you should include as much of this data as you can.

Category-Specific real.de Onlineshop Attributes

There are some attributes that make sense for some items, 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 an item are determined by which category the item is in.

To get the available attributes for the items in a given category, use the /categories/{id_category}/ REST endpoint and include the embedded query parameter with both attributes options: optional_attributes,mandatory_attributes.

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

GET https://www.real.de/api/v1/categories/43011/?embedded=optional_attributes,mandatory_attributes

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.real.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"
		}
	],
	"mandatory_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:

Attribute types

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

User-Defined Attributes

Finally, you may send attributes to the real.de Onlineshop that the system does not know about yet. You can include any attribute name and value in the Product Data CSV files that you send to the real.de Onlineshop. 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 item. For more details, see the User-Defined Attributes section of the Product Data CSV files page.

Uploading Product Data

There are two ways to upload your product data to the real.de Onlineshop: 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/{ean}/ 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 real.de Onlineshop 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 have already uploaded data for the given product, and 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 7350068240393 and the title Daniel Wellington 0507DW St. Mawes Rosegold Damenuhr. It has a description, manufacturer, gender target, and color. In your system it's in the category Uhren, so you would also provide this information. The JSON object for your product would then look like this:

{
	"ean": [
		"7350068240393"
	],
	"category": [
		"Uhren"
	],
	"title": [
		"Daniel Wellington 0507DW St. Mawes Rosegold Damenuhr"
	],
	"description": [
		"Uhr dame DW CLASSIC ST.MAWES ROSE 0507DW. Offerte. Mode. Wasserbeständigkeit 30. Farben braun. Farben golden. Farben weiß. Form Runde. Bewegung Japanisches Quarzwerk. Analog / Digital analog. Gehäusematerial Vergoldet Stahl. Schlusskurs Dornschließe. Bügel-Material Sonstige Materialien."
	],
    "additional_attributes": [
		"manufacturer": [
			"Daniel Wellington"
		],
		"gender target": [
			"Damen"
		],
		"Armbandfarbe": [
			"Braun"
		],
		"Ziffernblattfarbe": [
			"Weiß",
			"Gold"
		]
	]
}

After you send the data to the real.de Onlineshop 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/ 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 an item description from your product data, you will have to provide an inventory unit to be able to see the item on the real.de Onlineshop 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 real.de Onlineshop, 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 real.de Onlineshop. 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 real.de Onlineshop 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 /import-files/ endpoint in the REST API. The body of the request should contain JSON with the URL and type of the file set to PRODUCT_FEED. In our example, we would send this JSON:
    {
    	"uri": "http://www.example.com/my_products.csv",
    	"type": "PRODUCT_FEED"
    }
    
  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 /import-files/seller/ REST API endpoint to get a list of all of your import files and what status they are in. If product_feed_async_done of a file is set to 1, that means it has been successfully imported into the real.de Onlineshop site.
  5. Once your product data has been imported, upload your inventory data. Doing this is described on the Managing Inventory page.

Deleting Items

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

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