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:

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 has these attributes.

Category-Specific real.de Onlineshop Attributes: these attributes are specific to the real.de Onlineshop
category that the item 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 real.de Onlineshop system.

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.

ean The EAN(s) of the item. Generally there is only one EAN per item, but some have multiples.

title The title or name of the item.

description A detailed description of the item. This field can contain HTML.

short_description A short description of the item. This field should not contain HTML.

picture One or more pictures.

list_price The manufacturer's suggested retail price (MSRP) of the item.

category The name of the category the item is in.

mpn The manufacturer part number of the item.

additional_attributes For Including other item attributes e.g. color, manufacturer.

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_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 real.de Onlineshop
website.

is_multiple_allowed True if the attribute can contain multiple values. For example,
a single item 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.

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.

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 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:

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:

Upload the CSV file to a publicly-accessible web server. Let's say you upload it to
http://www.example.com/my_products.csv.

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:

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.

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.