API Guidelines

Process workflow

Given below is an overview of all interfaces available on the OTTO Marketplace, linked to common use cases, which you should implement to organize the business at the OTTO Marketplace. Here you can find further information.

Preparing the sales process

The interfaces Products, ShippingProfiles and Availability assist you to get your first product online on the OTTO Marketplace.
This use case involves key steps, including authenticating to access the server, selecting valid brands and categories, posting the product details, and checking update tasks and marketplace status for errors. Additionally, it shows you how to create and manage shipping profiles, update product delivery information, and set product quantities to ensure your product becomes available for purchase.

Orders & Returns Management

The interfaces Orders, Shipments, Returns, Receipts and ReturnShipments help you to set up your Orders and Returns Management on the OTTO Marketplace.
This use case includes steps such as authenticating to access the server, regularly checking for new orders, shipping the order, processing returns and get the current state of return shipments. Additionally, it covers fetching receipts for ensuring smooth order fulfillment management.

Aftersales Management

The interfaces PriceReductions and Receipts are designed to manage your aftersales actions.
This use case informs about how to apply price reductions to shipped products if there are issues with the product or if the customer is dissatisfied. It includes steps such as authenticating to access the server, view previously applied price reductions and fetch partial refund receipts.

General Changelog

For a comprehensive list of updates, including legal changes, version upgrades, and breaking changes, please refer to our official Changelog, sorted chronologically.

Feedback

We are very interested in learning how to enhance our API-Documentation for you and would love to hear from you! Send Feedback.

Get Support

If you have any questions, remarks or if you need support, please don't hesitate to contact us and we will get back to you as soon as possible.

• As a partner the quickest way to get support is to open a new ticket in OTTO Partner Connect via the Partner Helpdesk choosing the sub-category "Technische Schnittstellen".
• As a service partner please create a case to our OTTO Market team.

Access to the API

Environment	Base URL
Sandbox	https://sandbox.api.otto.market
Production	https://api.otto.market

Scopes

Scopes corresponds to OAuth scopes. They are used for providing fine-grained access control to the OTTO Market APIs. Scopes need to be used via the authorization in the client credential flow or the authorization code flow.

Scopes for OTTO Market APIs

The below table gives mapping of displayed scope names in UI to the scope names to be used for fetching token

Display Name	Scope Name (To be used in fetching token)
Products	products
Orders	orders
Receipts	receipts
Returns	returns
Price Reduction	price-reduction
Shipments	shipments
Quantities	quantities
Shipping Profiles	shipping-profiles
Availability	availability

Content declaration of available scopes

Products

The product interfaces allow partners to manage their product data in the OTTO Market, which means to send products for publishing on OTTO.de, to view the sent data, and to manage the visibility of the products on otto.de.

Read more about the technical possibilities here.

Quantities - depcrecated and will be shut down to the end of March 25. Use the Availability Interface for updating quantities.

Once the products have been successfully transmitted using the products scope, only the quantities are missing to make the products available to the end customer on otto.de. For this purpose the Quantity Interface allows partners and service partners to update the available quantity for a specific SKU.

Refer to the Availability V1 interface instead.

Shipping Profiles

With this interface you can create, change and manage shipping profiles of the otto market partners.

Read more about the technical possibilities here.

Availability

Once the products have been successfully transmitted using the products scope, your need to send quantities to make the products available to the end customer on otto.de. As well you need to connect the sku to existing shipping profiles for the delivery information. For this purpose the Availability Interface allows partners and service partners to update necessary information to make a SKU available on otto.de.

Read more about the technical possibilities here.

Orders

This interface allows partners and service partners to view orders and associated position items. It also allows to send cancellations on order and position item level.

Read more about the technical possibilities here.

Shipments

This interface should be used to report that shipments have been handed over to the carrier for final delivery to the customer. You can also get access to Return-Shipments for retrieving track and trace data for returns from the customer to the partner warehouse.

Shipments - Read more about the technical possibilities here. Return-Shipments - Read more about the technical possibilities here.

Returns

This scope enables the user to manage returns. This includes retrieving a list of announced returns, accepting and declining returns.

Read more about the technical possibilities here.

Receipts

OTTO Market provides receipts to the customers to document financial processes. The scopes enables users to download these documents as a PDF or a JSON.

Read more about the technical possibilities here.

Price Reduction

This endpoint enables sellers to apply price reductions to shipped products if the customer is unsatisfied and asks for a partial refund instead of returning the product completely.

Read more about the technical possibilities here.

Calling an Endpoint

All endpoints are secured via authorization. You add the HTTP Authorization -Header with value Bearer ey... and will get access.

curl -X GET \
  https://api.otto.market/v2/orders \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5jdhstdheSldUIiwia2lkIiA6ICI4T1d6MjhuZ01GbHBURDl5TGtxQkRHMThuYXZNVFgyTWtqNVhkY0RITDBZIn0.eyJqdGkiOiI5OTM1NDk3OS1iNDdhLTQ3MzctOWYyMy0yNTMyMmI5MGVmYmMiLCJleHAiOjE1NTM3NjQ4NjMsIm5iZiI6MCwiaWF0IjoxNTUzNzYxMjYzLCJpc3MiOiJodHRwczovL2VzYi13cy5vdHRvLmRlL3NlYy1hcGkvYXV0aC9yZWFsbXMvcGFydG5lci1hcGktdGVzdCIsImF1ZCI6ImFjY291bnQiLCJzdWIiOiI0MWUwNGQ1OS0xMTk0LTRiYjMtODhkYS1hYjRmNTk2NDkwZGUiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJwYXJ0bmVyLWFwaSIsImF1dGhfdGltZSI6MCwic2Vzc2lvbl9zdGF0ZSI6IjliNjk1ZDA1LTY5YzQtNDkwZS1hZGIzLTc2YWE5NmJmZjA0YyIsImFjciI6IjEiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwYXJ0bmVyIjoiMTAwMDYyNCIsIm5hbWUiOiJTb3VsZXdheSIsInByZWZlcnJlZF91c2VybmFtZSI6IjEwMDA2MjQiLCJnaXZlbl9uYW1lIjoiU291bGV3YXkifQ.SleUexNdapaY5RmrVTbKRMiVpRrbNLjIUi7fILsW1hkpqQbX4IQRaSufSt98Ar0OkEmIvZvYPpGVecmjwYvD3YQzBmlcdU0V544Y0h8y01RyxZAYGZbRXfA1kOsFDucnrClCcj1JIaQMU4629wU9OM_SdQaLvfTA2l5prma94RekdWR3S-6DzXqJDtHrrcYS8BsfohkuLdi1U8vPUjwee9lsY3RTa9YZVekH4hFVWMl0Pbwub8jwum6zRjTu-ZAiLhZSnl8mSaMtrJFmkzRi3-s9eN7k0lnLKWGt7JuqZ_vbiJT8ZhHvPur4eLrY02ehF6-lwSUyjWMCzCi5TjBgYg'

The expected result has an HTTP 200 code with a probably empty list.

Rate Limiting

A high volume of calls on API services at any given time would increase server resource consumption. If the load is due to an unauthorized intrusion it would be a chaos. Thus, rate limiting becomes extremely important.

In general authenticated API calls are limited for each partner to 20 requests per second. Exceeding the rate limit results in a HTTP 429 "too many requests" error. For some endpoints the rate limit is lower to ensure the best quality for all API users. Please see below:

Endpoint path	HTTP method	Max requests per time unit
/products	GET	10 per second
/products	POST	20 per second
/products/active-status	GET	10 per second
/products/active-status	POST	3600 per day
/products/marketplace-status	GET	10 per second
/products/categories	GET	10 per second
/products/brands	GET	10 per second
/v1/token	POST	10 per second for each IP
other endpoints	POST & GET	20 per second

When you are a service partner: you can find specific rate limits here for the process Installation of app by an OTTO Partner.

User Based API Throttling

A general method of limiting usage of API resource is to allocate a pre-configured static or dynamic quota for a consumer. The API rate limiting is done on the basis of partner-id. A particular partner-id can make 20 requests per second.

Best Practice

Please divide your requests over the day and avoid sending all data at once. Make use of the individual limits for the interfaces. This helps preventing our systems from clogging and ensures a flawless experience for everyone.

Timeouts and Defaults

Name	Value	Description
request timeout	10s	The maximum HTTP request timeout for all interfaces
limit	128	The default for limit query parameter. See Paging. The default limit can be overwritten in specific interfaces.

Common Patterns

Interface Definition

Our REST interface definitions are basically using swagger.io. All interface definitions can be automatically used by you to generate necessary API objects and similar in your chosen implementation language. In order to remain technically extensible and up-to-date, individual interfaces may have been described in new or different definition schemes. We are constantly trying to keep all interfaces technically up to date.

Versioning

The OTTO Market API uses different versions for the single endpoints. The version number is included in the URL path. Semantic versioning scheme is used, but only the major version. Breaking changes are only introduced in new major versions. API version is required in all urls.

Endpoints may introduce new optional fields at any time in the request and any new fields in the response. The client must skip all unknown fields.

For every endpoint, a changelog exists which displays the latest released changes and the upcoming unreleased changes. Additionally, an overall Changelog exists with the most exciting changes about the API in general.

Supporting old versions

The OTTO Partner API continues to support old versions of an API for 6 months from the time of public announcement for the new version of a given API. It is recommanded to check regularly. This can be be automated by checking HTTP headers for the attribute SunsetHeader, which indicates when versions go offline.

Best-practice

Regurlarly check for the SunsetHeader and act as soon as the attribute appears by updating your integration to the new version within the presented time frame.

example:

Warning: v2 is deprecated. Please migrate to v3
Sunset: Sun, 01 Nov 2020 00:00:00 GMT
Deprecation: Wed, 11 Nov 2018 23:59:59 GMT
Link: <https://api.otto.market/v3/orders>; rel="successor-version"

Header

Some common headers should be set by clients:

1. Set the X-Request-Timestamp header according to the ISO-8601 standard. You can use this regex pattern: ^\d4-(0\d|1[0-2])-([0-2]\d|3[01])T(2[0-3]|[01]\d):[0-5]\d:[0-5]\d(.\d+)?([+-](2[0-3]|[01]\d):[0-5]\d|Z)$
2. Set Accept to the desired response format e.g. application/json
3. Set the Content-Type header to define the used format in the request body, only applicable if you send a request body

HTTP Methods

The interfaces describe which HTTP methods are allowed and how to use them. Our basic concern is that basically all HTTP Methods are allowed in the standardized way. Note that these methods should behave as specified by their standardized meaning (idempotency). The following is a description of a few special features, relevant facts or ways to use some of the HTTP methods.

Click to expand for details

POST

POST will update specific fields and returns the result like a GET would do (error response is independent).

PUT

PUT will create or replace the whole entity independent of an existing entity.

PATCH

PATCH will update specific fields and not return data like a GET would do (error response is independent). PATCH body is structured in the same way as PUT and POST (entity body). All fields added into your body will be updated, other fields will not be affected.

example:

{
  "username" : "myusername",
  "email" : null
}

HTTP Status Codes

We are using standardized HTTP status code with a body only if needed (it also just can be empty), but details about that you can find at the concrete interface implementation.

Verb	Description
HEAD	Can be issued against any resource to get just the HTTP header info.
GET	Used for retrieving resources.
POST	Used for creating resources.
PATCH	Used for updating resources with partial JSON data. For instance, an Issue resource has title and body attributes. A PATCH request may accept one or more of the attributes to update the resource. PATCH is a relatively new and uncommon HTTP verb, so resource endpoints also accept POST requests.
PUT	Used for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero.
DELETE	Used for deleting resources.

Error Message Style

Error messages are returned as content type "application/json;charset=utf-8" in the following format:

{
  "errors": [
    {
      "path": "/orders/1000331",
      "title":  "Invalid Attribute",
      "code": "490",
      "detail": "First name must contain at least three characters.",
      "detail-structured": {...},
      "jsonpath": "[@.orderid=='12345']/invoiceAddress/firstname",
      "logref": "key to find in the log"
    }
  ],
  "warnings": [
      {
        "path": "/orders/1000331",
        "title":  "Warning Attribute",
        "code": "WRONG_SPELLING",
        "detail": "Last name should start with big letter.",
        "detail-structured": {...},
        "jsonpath": "[@.orderid=='12345']/invoiceAddress/lastname",
        "logref": "key to find in the log"
      }
    ]
}

Field	Mandatory	Description
path	yes	called REST path
title	yes	short description of the error
code	no	internal error code (number or enum) of your application / domain (do not use the HTTP status codes)
detail	no	long description of the error, perhaps technical details
detail-structured	no	technical details in JSON structure
jsonpath	no	JSON field in request which caused the error
logref	no	reference key to find more stuff in the log (as example traceId)

Pagination

Interfaces may return a list with resources (orders, shipments...) and a way to navigate these lists. Please pay attention to the response pattern to identify how to handle lists. There are two common ways list handling is implemented. One way to retrieve the next entry of a list is by using links for navigation the entries. The other is by providing list pages to iterate through lists.

For pagination, the basic query parameter "limit" (e.g. ?limit=10) can be used to define the maximum amount of resulting entities returned per call. The interface itself can reduce the limit lower than your client limit.

An example entity using links (not pages) to navigate would be:

{
  resources: [
    {
      ...data of the entity if all or some information will be provided directly...,
      links: [
        {
          href: "/v1/orders/1234",  <--- Link to single partner order
          rel: "self"
        }
      ]
    }
  ],
  links: [
    {
      href: "/v1/orders?idGt=1234", <--- Link to next list of ressources. If not present, no more records exist, currently
      rel: "next"
    }
  ]
}

Bulk requests

Attention: When sending bulk requests to any /products API endpoint, it will be processed asynchronously at the backend.

Synchronous Answer

Synchronously will be delivered an endpoint to check the asynchronous processing state.

HTTP STATUS 202 (Accepted)
{
    "task": {
        "href": "/interface/foo/123",
        "id": "123"
    }
}

Check the State of an Endpoint

The client can follow the href to check the state of processing.

Best-practice:

As long as the state = pending the attribute pingAfter dictates when to send a new request.

An example entity would be:

{
  "state": "pending",
  "message": "is running boy",
  "progress": "35",
  "total": "100",
  "pingAfter": "2019-05-01T13:25:12+0200",
  "links": [
    {
      "rel": "self",
      "href": "/foo/bar/123"
    },
    {
      "rel": "failed",
      "href": "/foo/bar/123/failed"
    },
    {
      "rel": "succeeded",
      "href": "/foo/bar/123/succeeded"
    }
  ]
}

Fetching files like PDF and CSV

Clients don't have to know the filetype that will be returned from a resource. Resources serving files will have the appropriate file extension in the URL as shown in the example below.

Request Headers

GET /SomeInvoice.pdf HTTP/1.1
Accept: */*

Clients can find out the mime-type from the Content-Type header that will be sent in the response (e.g. application/pdf for PDF files and application/csv for CSV files).

Response Headers

HTTP/1.1 200 OK
Content-Length: 514493
Content-Type: application/pdf

Common fields

Common fields like time, currency, country codes etc need to follow the standard ISO guidelines unless mentioned otherwise. The fields must report the format they are following on the docs.

Some standard formats:

• Time: Accept in any time zone in ISO-8601 format and always reply in UTC.

  Example: YYYY-MM-DD and hh:mm:ss.sss: 2020-03-12 and 22:33:34.400

• Currency: ISO-4217.

  Example: EUR for Euros, GBP for British Pound Sterling.

• Country code: ISO-3166-1 alpha-3

  Example: DEU for Germany, NOR for Norway.