API Integration for Sellers

Become an OTTO Market partner (seller)

Follow these steps:

• Go visit otto.market
• Inform yourself about our benefits
• Register as a partner
• Get access to our partner portal "OTTO Partner Connect (OPC)"
• Provide all necessary documents and data & sign the contract
• Request your API user on OPC
• Get yourself familiar with the Developer's Guide
• Have a look at the first Use-Cases
• Learn how to test our interfaces within the sandbox section
• Make your first API Calls in the production environment

OTTO Market API Developer's Guide

The Developer's Guide is targeted at developers and people with technical background who are already a partner (seller) of OTTO Market or are interested in becoming a partner. The aim is to help you as a partner of OTTO Market to connect to and to work with the OTTO Market API. It describes some common implementation patterns and helps you to understand how processes work. Detailed information about the concrete interfaces can be accessed by clicking onto the single tabs.

Authentication Options for OTTO Market API

Overview

To access the OTTO Market API, you'll first need to determine whether you're accessing it directly for your own use or authorizing access to a service partner to act on your behalf. If you're accessing the API directly, authentication is required, and you'll need to obtain an access token. However, if you're authorizing a service partner, you'll need to install and authorize a service partner app within your OTTO account.

Authentication methods vary depending on your approach. Below, you'll find a brief introduction to the different authentication options for accessing the various API endpoints tailored to these scenarios.

Scopes

Scopes 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.

In addition to the interfaces in your app overview, each interface must also be listed as a scope in the token request.

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
Shipping Profiles	shipping-profiles
Availability	availability
Returns Warehouse Read	returns-warehouse-read
Returns Warehouse Write	returns-warehouse-write

Content declaration of available scopes

Products

The product interfaces allow sellers 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.

Shipping Profiles

This interface allows sellers to create, modify, and manage their shipping profiles.

Read more about the technical possibilities here.

Availability

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

Read more about the technical possibilities here.

Orders

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

Read more about the technical possibilities here.

Shipments

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

Shipments - Read more about the technical possibilities here.

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

Returns

This scope enables the seller 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 enable the seller 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.

Returns Warehouse

This scope lets sellers manage return warehouse addresses and carriers. The Return Warehouse Read scope allows sellers to view their addresses and carrier details, while the Return Warehouse Write scope enables sellers to create and update those addresses and carriers.

Read more about the technical possibilities here.

Accessing the API on My Own Behalf as a Seller (Partner)

If you have your own IT department capable of developing interfaces for the OTTO Market API, you can create self-apps in the OTTO Partner Connect (OPC) portal and obtain a client ID and client secret for authentication via the client credential flow. This flow should be used by all OTTO Market Partners when establishing a connection with the API hosted by their organization. Refer to the following section for detailed information on creating self-apps and using the client credential flow.

Steps to Access API as an OTTO Market Partner using self-apps with the client credential flow

As an OTTO Partner, follow these steps to leverage the OTTO Market API:

1. Log in to OTTO Partner Connect (OPC) portal.
2. If necessary, please assign yourself the user right “API-Zugriff” in the user administration and log in again so that the API access is authorized.
3. Navigate to the API access ("API-Zugriff") section, where you'll find Sandbox and Live environments.
4. Choose the environment where you want to create an app and click "Neue App erstellen" to proceed.
5. Provide a name for your app and select at least one scope that your app will need access to. Click "App erstellen" to proceed.
6. Your app has been successfully created, and you'll be redirected to the credentials tab.

Note:

• There's a limit to the number of apps you can create. If you reach this limit, you must delete an old one before creating a new one.
• The client secret for the app is displayed only once. If you miss or forget it, you'll need to rotate the client secret.

Access Token Generation:

Implement the Client Credentials Flow to generate an access token, granting you access to the OTTO Market API.

• The Host header should be either sandbox.api.otto.market or api.otto.market.
• The request body should be application/x-www-form-urlencoded.

Example cURL command:

curl --request POST \
  --url 'https://api.otto.market/v1/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id={CLIENT_ID} \
  --data client_secret={CLIENT_SECRET} \
  --data 'scope=orders products'

If your request is successful, the API server responds with an access token in a JSON object that looks like this:

{
  "access_token": "eyJhbGciOiJSUzI1NiISNCXIgiLCJSZWNla[...omitted for brevity...]",
  "expires_in": 1800,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 1666271301,
  "scope": "orders products"
}

Note: Please bear in mind that there is no refresh token when obtaining an access token using the client credential grant type. The client needs to use its credentials, i.e., client ID and client secret, to obtain a new token once the access token has expired or is about to expire.

Accessing the API as a Service Partner on Behalf of a Seller (Partner)

Installing and Authorizing OTTO Market Apps as a Seller (Partner)

For OTTO Market Partners needing to install and authorize OTTO Market apps created by service partners, follow these steps:

1. Log in to OTTO Partner Connect (OPC) portal.
2. Click on the link provided by the Service Partner or visit their homepage.
3. Grant consent for the app to access the specified scopes displayed in the consent screen. Failure to grant consent will prevent app installation and access to your data.

Note: All specified scopes must be granted access; partial access is not permitted. 4. Once consent is granted, the app is installed and can be used. It will also be displayed in the "Installed Apps" tab on the service partner page ("Servicepartner").

Revoke Consent

To revoke consent, navigate to the overview of your installed apps on the service partner page ("Servicepartner"). Hover over the app name and click "Zugriff entziehen" to confirm revocation. Uninstalling the app revokes its access to your data. Of course, you can re-install the app if you want to.

Creating and Authorizing OTTO Market Apps as a Service Partner

For information on creating and authorizing OTTO Market apps as a service partner, refer to the Service Partner Program section.