Skip to main content

Products

The product interface allow you to manage product data on the OTTO Market, which means to post products to be published on otto.de, to check the data you have sent and to manage and improve the visibility of the products on otto.de.

Product processing states​

Here you can find an overview of possible states, when you upload your product:

  • PENDING
    Not all uploaded product variations are finally processed yet.
  • DONE
    All uploaded product variations are processed.

During the processing the responses keep track of the states of the uploaded product variations and group them into the following result states:

  • succeeded
    Number of successfully uploaded product variations
  • failed
    Number of failed uploaded product variations
  • unchanged
    Number of uploaded product variations without data changes

Common use cases​

The API offers endpoints for different aspects of product data management:

Before You can upload Your product data, You have to collect some reference data that is essential for the product presentation on otto.de

Brands​

This endpoint gives you all the brands OTTO Market knows and can reference. You should use this endpoint to make the brand in your products fit to OTTO Market brand IDs:

GET /v4/products/brands

Categories​

This endpoint gives you all the assortment categories OTTO Market has defined, so you should use this endpoint to make the category names in your products fit to OTTO Market categories and their exact names:

GET /v4/products/categories

Create or update product variations​

Creating or updating product variations may be done with a POST operation:

POST /v4/products

The POST operation will return a state PENDING and a process id which identifies the processing of the request. This process id is delivered in the response body of the POST request as a collection of links:

{
  "state": "pending",
  ...
  "links": [
    {
      "rel": "self",
      "href": "/v4/products/update-tasks/8a9ab7ec-b1ba-4917-bffa-e1d22f2ebe1b"
    }
  ]
  ...

These links can be used in a GET operation to look at the results of the processing of the sent product data. You as a partner might send many variations in one request, so the processing could take some time, therefore we only offer an asynchronous access to the received product data.

GET /v4/products/update-tasks/{processUuid}

This summary shows the total amount of variations in the process and breaks it down to the amount of variations, which were processed successfully, failed or were send unchanged.

The GET operation of the Products endpoint can be used after processing to watch the representation of the product in the exact state sent by you.

GET /v4/products

Product Active Status​

This endpoint allows you to pull the products from otto.de, or to put them back to visibility on otto.de. For this you have the POST operation:

POST /v4/products/active-status

There is also a GET operation to view the state of products:

GET /v4/products/active-status

Marketplace Status​

This endpoint to query the status of the product variations on the OTTO marketplace. If a product variation has been processed without errors, the status includes the link to the product variation on otto.de:

GET /v4/products/marketplace-status

Example​

A typical sequence dealing with our interfaces would be:

1. You query the Brands interface and match the brand names in Your products to the names in the received brands.
2. You query the Categories interface and match the category names in Your products to the names in the received categories.
3. You use the POST endpoints from the Products interface to send Your products to Otto Market
4. You will receive 202 HTTP return code and a body like:
{
    "state": "pending",
    "message": "The process is currently in progress",
    "progress": 0,
    "total": 2,
    "pingAfter": "2020-05-13T10:40:01.815Z",
    "links": [
        {
            "rel": "self",
            "href": "/v3/products/update-tasks/09abe6ca-9c36-45bb-9cd3-a7de7f93284b"
        },
        {
            "rel": "failed",
            "href": "/v3/products/update-tasks/09abe6ca-9c36-45bb-9cd3-a7de7f93284b/failed"
        },
        {
            "rel": "succeeded",
            "href": "/v3/products/update-tasks/09abe6ca-9c36-45bb-9cd3-a7de7f93284b/succeeded"
        },
        {
            "rel": "unchanged",
            "href": "/v3/products/update-tasks/09abe6ca-9c36-45bb-9cd3-a7de7f93284b/unchanged"
        }
    ]
}
5. You execute /v3/products/update-tasks/09abe6ca-9c36-45bb-9cd3-a7de7f93284b until the state changes to "done". Usually this will happen very fast.
6. You execute /v3/products/update-tasks/09abe6ca-9c36-45bb-9cd3-a7de7f93284b/succeeded and /v3/products/update-tasks/09abe6ca-9c36-45bb-9cd3-a7de7f93284b/failed to watch the details of the processing (successfully imported products, and detailed information to failures which occurred in the product data processing).
7. You may browse /v3/products/update-tasks/09abe6ca-9c36-45bb-9cd3-a7de7f93284b/unchanged to look at the product data which You delivered with the same content as in the former product data delivery.

Rate Limiting​

The Products API serves billions of API calls every month. The following limits should create the best quality of service for all API users. Every endpoint has its own limits. Too many API calls will cause a HTTP 429 too many requests error.

Best practice​

If you get responses with a 429 Too many requests status we recommend parsing the Retry-After header of these responses. Your client then should wait until the specified amount of time has passed before making additional calls, or it may be subject to additional rate limiting. You can find a complete list of the current rate limits here.

Pagination​

Pagination is offered on the endpoints that deliver lists of data objects. It is managed using the following parameters:

  • page - Indicates the offset where the returned dataset should be collected from. Calculation: page * limit
  • limit - This sets the maximum number of data objects returned in each response. The default limit is 100.

HTML markup in free texts​

All fields with free text values (like e.g. description, bullet points, certain category-dependent attributes) do only accept some of the available HTML markup tags - every other markup will be removed,

The allowed tags are:

  • formatting tags

    <b>, <i>, <font>, <s>, <u>, <o>, <sup>, <sub>, <ins>, <del>, <strong>, <strike>, <tt>, <code>, <big>, <small>, <span>, <em>

  • block tags

    <p>, <div>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <ul>, <ol>, <li>, <blockquote>

PLEASE NOTE: Although these tags are not removed directly, it cannot be guaranteed that all formatting and block definitions will be displayed as desired on the shop detail page.

Glossary​

Variation - The variation is the basic entity that can be ordered by a customer at otto.de. It is also known as SKU or stock keeping unit. On the OTTO Market you manage your product data primarily on the variation level.

Product - The product is a collection of variations built around shared properties like brand, category, product name and dimensioning properties. The typical example is a tshirt in various colors and sizes.

Active status - The active status reflects the visibility of a variation on otto.de.

Marketplace status - The marketplace status reflects the current state of a variation regarding all validations that happen in the process of forwarding the product data to otto.de.

Category - The category is a distinguishable part of the assortment at otto.de identified by a name. It clusters the range of attributes (obligatory or optional) that can be used to describe products.

ON THIS PAGE