{"openapi":"3.0.3","info":{"version":"1.0.0","title":"OTTO Market API","x-logo":{"url":"https://nonlive.portal.otto.market/static/assets/images/otto_market_logo_borderless.svg","backgroundColor":"#ffffff"},"description":"# Home\nWelcome to OTTO Market API Documentation.\nOn this page you will find all information on how to use the API for your business.\nPlease scroll to the top if you´re looking for the OpenAPI specification to download.\n\n## Become an OTTO Market partner (seller)\nFollow these steps:\n- Go visit [otto.market](https://www.otto.market)\n- Inform yourself about our benefits\n- Register as a partner\n- Get access to our partner portal \"OTTO Partner Connect (OPC)\"\n- Provide all necessary documents and data & sign the contract\n- Request your API user on OPC\n- Get yourself familiar with the [Developer's Guide](https://api.otto.market/docs#section/OTTO-Market-API-Developer's-Guide)\n- Have a look at the first [Use-Cases](https://api.otto.market/docs#section/Use-Cases)\n- Learn how to test our interfaces within the [sandbox section](https://api.otto.market/docs#section/Sandbox)\n- Make your first API Calls in the production environment\n\n## Become an OTTO Market service partner (developer)\nFollow these steps:\n\n- Go visit [servicepartner.otto.market](https://servicepartner.otto.market/)\n- Inform yourself about the process of integration\n- Register as a developer\n- Get access to our partner portal \"OTTO Partner Connect (OPC)\" as developer\n- Provide all necessary documents and data to get further access\n- Get yourself familiar with the [Developer Program](https://api.otto.market/docs#section/Developer-Program)\n- Have a look at the first [Use-Cases](https://api.otto.market/docs#section/Use-Cases)\n- Learn how to test our interfaces within the [sandbox section](https://api.otto.market/docs#section/Sandbox)\n- Request [production access](https://api.otto.market/docs#section/Developer-Program/Access-to-Production) within the \"OTTO Partner Connect (OPC)\"\n- Create your first OTTO Market App and connect your first seller\n\n## Process Workflow\n\nGiven below is the overall process workflow of all services within OTTO Market and calls you should at least implement to organize the business at the OTTO Market.\n\nFor more detailed information, please also have a look into our section [Use-Cases](https://api.otto.market/docs#section/Use-Cases).\n\nThe first use-case [How to list your first product](https://api.otto.market/docs#section/Use-Cases/How-to-list-your-first-product) will help you to understand the dependencies between the interfaces Products, Shipping-Profiles and Availability.\nThe second use-case [Manage an order from start to finish](https://api.otto.market/docs#section/Use-Cases/Manage-an-order-from-start-to-finish) give more detailed information about the order management process and the dependencies between the interfaces Orders, Shipments, Receipts and Returns.\nThe third use-case [Manage your after-sales action](https://api.otto.market/docs#section/Use-Cases/Manage-your-after-sales-actions) informs about all the touch points with the OTTO customer after the shipment took place. In the use-case the interface Price-Reductions will be handled.\n\n $\"Process$ \n\n## General Changelog\nThis changelog will contain information about important changes. Most important things are legal\nissues, version upgrades and not backward compatible changes.\nNewest information will be placed on top of the table.\n\n| Date | Interface | Classification | Description |\n|------------|-----------------------------------------------------------------------------|----------------|-----------------------------------------------------------------------------------------------------------------------------------------|\n| 2024-08-08 | [Shipping Profiles](../docs#tag/ShippingProfiles-V1) | New API | Added ShippingProfiles API |\n| 2024-08-08 | [Availability](../docs#tag/Availability-V1) | New API | Added Availability API. The API replaces the Quantities-V2, which ist supported until 31st of March, 2025 and new functions according to delivery information is added.|\n| 2024-08-01 | [Products](../docs#tagProducts-V4) | New Version | Version 4 is now live. We plan to go offline with Version 3 (v3) by 2025-02-03 |\n| 2024-03-18 | [Returns](../docs#tag/Returns-V3) | New Version | Version 3 (v3) is now live. We plan to go offline with Version 2 (v2) by 30th September, 2024. |\n| 2023-07-03 | [OTTO Market Developer Program](https://servicepartner.otto.market/en/home.html) | Published | The OTTO Market Developer Program is now available to the public |\n| 2023-01-11 | [Receipts](../docs#tag/Receipts-V3) | New Version | Version 3 is now live. We plan to go offline with Version 2 (v2) by 2023-07-11 |\n| 2022-09-22 | [Products](../docs#tagProducts-V3) | New Version | Version 3 is now live. We plan to go offline with Version 2 (v2) by 2023-03-31 |\n| 2022-05-25 | General | Documentation | Starting 2022-11-01 redundant domains to access OTTO Market API doc will be decomissioned. Please use access docs using api.otto.market |\n| 2022-03-17 | [Quantities](../docs#tag/Quantities-V2) | Sandbox | Version 2 of /quantities is now available in the sandbox environment. |\n| 2022-01-19 | [Price reductions](../docs#tag/Price-Reductions-V1) | New API | Added price reduction APIs |\n| 2021-11-26 | [Products](../docs#tag/Products-V2) | Sandbox | Version 2 of /products is now available in the sandbox environment. |\n| 2021-04-30 | [Orders](../docs#tag/Orders-V4) | New Version | Version 4 is now live. We plan to go offline with Version 3 (v3) by 2021-10-31 |\n| 2021-04-06 | [Products](../docs#tag/Products-V2) | New Version | Version 2 is now live. We plan to go offline with Version 1 (v1) earliest by 01.11.2021. |\n| 2020-04-14 | [Receipts](../docs#tag/Receipts-V2) | New Version | Version 2 is now live. We plan to go offline with Version 1 (v1) earliest by 14th October,2020. |\n| 2020-04-20 | [Orders](../docs#tag/Orders-V4) | New Version | Version 3 is now live. We plan to go offline with Version 2 (v2) earliest by 01.11.2020. |\n| 2019-09-01 | [Orders](../docs#tag/Orders-V4) | New Version | Version 1 will be outdated in some time. Please change to version 2, if it is marked as ready. |\n| 2022-02-28 | [Price Reductions](../docs#tag/Price-Reductions-V1) | New Version | Version 1 is now live. |\n\n## Feedback\n\nWe are very interested in learning how to enhance our API-Documentation for you and would love to hear from you!\n[Send Feedback.](https://account.otto.market/s/feedback?category=Feedback&Unterkategorie=)\n\n## Get Support\nIf 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.\n\n- As a **partner** the quickest way to get support is to open a new ticket in [OTTO Partner Connect](https://account.otto.market/s/ticketanlegen) via the Partner Helpdesk choosing the sub-category \"Technische Schnittstellen\".\n- As a **service partner** please [create a case](https://account.otto.market/s/ticketanlegen?category=Supportrequest&Unterkategorie=technicalInterfaces) to our OTTO Market team.\n\n## Access to the API\n\n| Environment | Base URL |\n|-------------|---------------------------------|\n| Sandbox | https://sandbox.api.otto.market |\n| Production | https://api.otto.market |\n\n# OTTO Market API Developer's Guide\nThe 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.\nThe aim is to help you as a partner of OTTO Market to connect to and to work with the OTTO Market API.\nIt describes some common implementation patterns and helps you to understand how processes work.\nDetailed information about the concrete interfaces can be accessed by clicking onto the single tabs.\n\n## Authentication Options for OTTO Market API\n\n### Overview\n\nTo 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.\n\nAuthentication 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.\n\n### Accessing the API on My Own Behalf as a Seller (Partner)\n\nIf 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.\n\n#### Steps to Access API as an OTTO Market Partner using self-apps with the client credential flow\n\nAs an OTTO Partner, follow these steps to leverage the OTTO Market API:\n\n1. Log in to [OTTO Partner Connect (OPC)](https://portal.otto.market/) portal.\n2. If necessary, please assign yourself the user right “API-Zugriff” in the [user administration](https://portal.otto.market/settings/Nutzerverwaltung) and log in again so that the API access is authorized.\n3. Navigate to the [API access (\"API-Zugriff\")](https://portal.otto.market/settings/API) section, where you'll find Sandbox and Live environments.\n4. Choose the environment where you want to create an app and click \"Neue App erstellen\" to proceed.\n5. Provide a name for your app and select at least one scope that your app will need access to. Click \"App erstellen\" to proceed.\n6. Your app has been successfully created, and you'll be redirected to the credentials tab.\n\n**Note:**\n- 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.\n- The client secret for the app is displayed only once. If you miss or forget it, you'll need to rotate the client secret.\n\n**Access Token Generation:**\n\nImplement the Client Credentials Flow to generate an access token, granting you access to the OTTO Market API.\n\n- The Host header should be either `sandbox.api.otto.market` or `api.otto.market`.\n- The request body should be `application/x-www-form-urlencoded`.\n\nExample cURL command:\n```bash\ncurl --request POST \\\n --url 'https://api.otto.market/v1/token' \\\n --header 'Content-Type: application/x-www-form-urlencoded' \\\n --data grant_type=client_credentials \\\n --data client_id={CLIENT_ID} \\\n --data client_secret={CLIENT_SECRET} \\\n --data 'scope=orders products'\n```\n\nIf your request is **successful**, the API server responds with an **access token** in a JSON object that looks like this:\n\n```\n{\n \"access_token\": \"eyJhbGciOiJSUzI1NiISNCXIgiLCJSZWNla[...omitted for brevity...]\",\n \"expires_in\": 1800,\n \"refresh_expires_in\": 0,\n \"token_type\": \"Bearer\",\n \"not-before-policy\": 1666271301,\n \"scope\": \"orders products\"\n}\n```\n\n**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.\n
\n\n### Accessing the API as a Service Partner on Behalf of a Seller (Partner)\n\n#### Installing and Authorizing OTTO Market Apps as a Seller (Partner)\n\nFor OTTO Market Partners needing to install and authorize OTTO Market apps created by service partners, follow these steps:\n\n1. Log in to [OTTO Partner Connect (OPC)](https://portal.otto.market) portal.\n2. Click on the link provided by the Service Partner or visit their homepage.\n3. 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.\n\n**Note:**\nAll specified scopes must be granted access; partial access is not permitted.\n4. 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\")](https://portal.otto.market/settings/Servicepartner).\n\n#### Revoke Consent\n\nTo revoke consent, navigate to the overview of your installed apps on the [service partner page (\"Servicepartner\")](https://portal.otto.market/settings/Servicepartner). Hover over the app name and click \"Zugriff entziehen\" to confirm revocation.\nUninstalling the app revokes its access to your data. Of course, you can re-install the app if you want to.\n\n
\n\n### Creating and Authorizing OTTO Market Apps as a Service Partner\n\nFor information on creating and authorizing OTTO Market apps as a service partner, refer to the [Developer Program](/docs#section/Developer-Program) section.\n\n## Scopes\n\nScopes corresponds to [OAuth scopes](https://oauth.net/2/scope/). 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.\n\n### Scopes for OTTO Market APIs\nThe below table gives mapping of displayed scope names in UI to the scope names to be used for fetching token\n\n| Display Name | Scope Name (To be used in fetching token) |\n|-------------------|-------------------------------------------|\n| Products | products |\n| Orders | orders |\n| Receipts | receipts |\n| Returns | returns |\n| Price Reduction | price-reduction |\n| Shipments | shipments |\n| Quantities | quantities |\n| Shipping Profiles | shipping-profiles |\n| Availability\t | availability |\n\n### Content declaration of available scopes\n\n#### Products\n\nThe 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.\n\nRead more about the technical possibilities [here](https://api.otto.market/docs#tag/Products-V4).\n\n#### Quantities - depcrecated and will be shut down to the end of March 25. Use the Availability Interface for updating quantities.\n\nOnce 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.\n\nRead more about the technical possibilities [here](https://api.otto.market/docs#tag/Quantities-V2).\n\n#### Shipping Profiles\n\nWith this interface you can create, change and manage shipping profiles of the otto market partners.\n\nRead more about the technical possibilities [here](https://api.otto.market/docs#tag/ShippingProfiles-V1).\n\n#### Availability\n\nOnce 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.\nAs well you need to connect the sku to existing shipping profiles for the delivery information.\nFor this purpose the Availability Interface allows partners and service partners to update necessary information to make a SKU available on otto.de.\n\nRead more about the technical possibilities [here](https://api.otto.market/docs#tag/Availability-V1).\n\n#### Orders\n\nThis 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.\n\nRead more about the technical possibilities [here](https://api.otto.market/docs#tag/Orders-V4).\n\n#### Shipments\n\nThis 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.\n\nShipments - Read more about the technical possibilities [here](https://api.otto.market/docs#tag/Shipments-V1).\nReturn-Shipments - Read more about the technical possibilities [here](https://api.otto.market/docs#tag/ReturnShipments-V1).\n\n#### Returns\n\nThis scope enables the user to manage returns. This includes retrieving a list of announced returns, accepting and declining returns.\n\nRead more about the technical possibilities [here](https://api.otto.market/docs#tag/Returns-V3).\n\n#### Receipts\n\nOTTO Market provides receipts to the customers to document financial processes. The scopes enables users to download these documents as a PDF or a JSON.\n\nRead more about the technical possibilities [here](https://api.otto.market/docs#tag/Receipts-V2).\n\n#### Price Reduction\n\nThis 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.\n\nRead more about the technical possibilities [here](https://api.otto.market/docs#tag/Price-Reductions-V1).\n\n\n## Calling an Endpoint\nAll endpoints are secured via authorization. You add the HTTP Authorization\n-Header with value Bearer ey... and will get access.\n```\ncurl -X GET \\\n https://api.otto.market/v2/orders \\\n -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5jdhstdheSldUIiwia2lkIiA6ICI4T1d6MjhuZ01GbHBURDl5TGtxQkRHMThuYXZNVFgyTWtqNVhkY0RITDBZIn0.eyJqdGkiOiI5OTM1NDk3OS1iNDdhLTQ3MzctOWYyMy0yNTMyMmI5MGVmYmMiLCJleHAiOjE1NTM3NjQ4NjMsIm5iZiI6MCwiaWF0IjoxNTUzNzYxMjYzLCJpc3MiOiJodHRwczovL2VzYi13cy5vdHRvLmRlL3NlYy1hcGkvYXV0aC9yZWFsbXMvcGFydG5lci1hcGktdGVzdCIsImF1ZCI6ImFjY291bnQiLCJzdWIiOiI0MWUwNGQ1OS0xMTk0LTRiYjMtODhkYS1hYjRmNTk2NDkwZGUiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJwYXJ0bmVyLWFwaSIsImF1dGhfdGltZSI6MCwic2Vzc2lvbl9zdGF0ZSI6IjliNjk1ZDA1LTY5YzQtNDkwZS1hZGIzLTc2YWE5NmJmZjA0YyIsImFjciI6IjEiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwYXJ0bmVyIjoiMTAwMDYyNCIsIm5hbWUiOiJTb3VsZXdheSIsInByZWZlcnJlZF91c2VybmFtZSI6IjEwMDA2MjQiLCJnaXZlbl9uYW1lIjoiU291bGV3YXkifQ.SleUexNdapaY5RmrVTbKRMiVpRrbNLjIUi7fILsW1hkpqQbX4IQRaSufSt98Ar0OkEmIvZvYPpGVecmjwYvD3YQzBmlcdU0V544Y0h8y01RyxZAYGZbRXfA1kOsFDucnrClCcj1JIaQMU4629wU9OM_SdQaLvfTA2l5prma94RekdWR3S-6DzXqJDtHrrcYS8BsfohkuLdi1U8vPUjwee9lsY3RTa9YZVekH4hFVWMl0Pbwub8jwum6zRjTu-ZAiLhZSnl8mSaMtrJFmkzRi3-s9eN7k0lnLKWGt7JuqZ_vbiJT8ZhHvPur4eLrY02ehF6-lwSUyjWMCzCi5TjBgYg'\n```\n\nThe expected result has an HTTP 200 code with a probably empty list.\n\n## Rate Limiting\nA 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.\n\nIn general authenticated API calls are limited for each partner to 20 requests per second.\nExceeding the rate limit results in a HTTP 429 \"too many requests\" error.\nFor some endpoints the rate limit is lower to ensure the best quality for all API users. Please see below:\n\n|Endpoint path|HTTP method|Max requests per time unit|\n|:-|:-|:-|\n|/products|GET|10 per second|\n|/products|POST|20 per second|\n|/products/active-status|GET|10 per second|\n|/products/active-status|POST|3600 per day|\n|/products/marketplace-status|GET|10 per second|\n|/products/categories|GET|10 per second|\n|/products/brands|GET|10 per second|\n|/v1/token|POST|10 per second for each IP|\n|other endpoints|POST & GET|20 per second|\n\n### User Based API Throttling\nA 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.\n\n### Best Practice\nPlease 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.\n\n## Timeouts and Defaults\n| Name | Value | Description |\n|-----------------|-------|-----------------------------------------------------------------------------------------------------------------|\n| request timeout | 10s | The maximum HTTP request timeout for all interfaces |\n| limit | 128 | The default for limit query parameter. See Paging. The default limit can be overwritten in specific interfaces. |\n\n## Common Patterns\n### Interface Definition\nOur REST interface definitions are basically using swagger.io.\nAll interface definitions can be automatically used by you to generate necessary API objects and similar in\nyour chosen implementation language.\nIn order to remain technically extensible and up-to-date, individual interfaces may have been\ndescribed in new or different definition schemes. We are constantly trying to keep all interfaces\ntechnically up to date.\n\n### Versioning\nThe OTTO Market API uses different versions for the single endpoints. The version number is included in the URL path.\n[Semantic versioning](https://semver.org/) scheme is used, but only the major version. Breaking changes are only introduced in new major versions. API version is required in all urls.\n\nEndpoints 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.\n\nFor 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.\n\n### Supporting old versions\nThe 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.\nIt is recommanded to check regularly. This can be be automated by checking HTTP headers for the attribute `SunsetHeader`, which indicates when versions go offline.\n\n#### Best-practice\nRegurlarly 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.\n\n__example:__\n```\nWarning: v2 is deprecated. Please migrate to v3\nSunset: Sun, 01 Nov 2020 00:00:00 GMT\nDeprecation: Wed, 11 Nov 2018 23:59:59 GMT\nLink: ; rel=\"successor-version\"\n```\n\n## Header\nSome common headers should be set by clients:\n\n1. Set the X-Request-Timestamp header according to the [ISO-8601](https://tools.ietf.org/html/rfc3339#section-5.6) standard. You can use this regex pattern: ^\\d{4}-(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)$\n2. Set Accept to the desired response format e.g. application/json\n3. Set the Content-Type header to define the used format in the request body, only applicable if you send a request body\n\n## HTTP Methods\nThe interfaces describe which HTTP methods are allowed and how to use them.\nOur basic concern is that basically all HTTP Methods are allowed in the [standardized way](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol).\nNote that these methods should behave as specified by their\n[standardized meaning (idempotency)](http://restcookbook.com/HTTP%20Methods/idempotency/).\nThe following is a description of a few special features, relevant facts or ways to use some of the HTTP methods.\n

Click to expand for details

\n\n### POST\nPOST will update specific fields **and** returns the result like a GET would do (error response is independent).\n\n### PUT\nPUT will create or replace the whole entity independent of an existing entity.\n\n### PATCH\nPATCH will update specific fields **and** not return data like a GET would do (error response is independent).\nPATCH body is structured in the same way as PUT and POST (entity body).\nAll fields added into your body will be updated, other fields will not be affected.\n\n__example:__\n```\n{\n \"username\" : \"myusername\",\n \"email\" : null\n}\n```\n

\n\n## HTTP Status Codes\nWe are using [standardized HTTP status code](https://www.restapitutorial.com/httpstatuscodes.html)\nwith a body only if needed (it also just can be empty), but details about that you can find at the\nconcrete interface implementation.\n\n| Verb | Description |\n|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| HEAD | Can be issued against any resource to get just the HTTP header info. |\n| GET | Used for retrieving resources. |\n| POST | Used for creating resources. |\n| 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. |\n| PUT | Used for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero. |\n| DELETE | Used for deleting resources. |\n\n## Error Message Style\nError messages are returned as content type \"application/json;charset=utf-8\" in the following format:\n```\n{\n \"errors\": [\n {\n \"path\": \"/orders/1000331\",\n \"title\": \"Invalid Attribute\",\n \"code\": \"490\",\n \"detail\": \"First name must contain at least three characters.\",\n \"detail-structured\": {...},\n \"jsonpath\": \"[@.orderid=='12345']/invoiceAddress/firstname\",\n \"logref\": \"key to find in the log\"\n }\n ],\n \"warnings\": [\n {\n \"path\": \"/orders/1000331\",\n \"title\": \"Warning Attribute\",\n \"code\": \"WRONG_SPELLING\",\n \"detail\": \"Last name should start with big letter.\",\n \"detail-structured\": {...},\n \"jsonpath\": \"[@.orderid=='12345']/invoiceAddress/lastname\",\n \"logref\": \"key to find in the log\"\n }\n ]\n}\n```\n\n| Field | Mandatory | Description |\n|-------------------|-----------|------------------------------------------------------------------------------------------------------|\n| path | yes | called REST path |\n| title | yes | short description of the error |\n| code | no | internal error code (number or enum) of your application / domain (do not use the HTTP status codes) |\n| detail | no | long description of the error, perhaps technical details |\n| detail-structured | no | technical details in JSON structure |\n| jsonpath | no | JSON field in request which caused the error |\n| logref | no | reference key to find more stuff in the log (as example traceId) |\n\n## Pagination\nInterfaces 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.\n\nFor 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.\n\nAn example entity using links (not pages) to navigate would be:\n```\n{\n resources: [\n {\n ...data of the entity if all or some information will be provided directly...,\n links: [\n {\n href: \"/v1/orders/1234\", <--- Link to single partner order\n rel: \"self\"\n }\n ]\n }\n ],\n links: [\n {\n href: \"/v1/orders?idGt=1234\", <--- Link to next list of ressources. If not present, no more records exist, currently\n rel: \"next\"\n }\n ]\n}\n```\n\n## Bulk requests\nAttention: When sending bulk requests to any /products API endpoint, it will be processed asynchronously at the backend.\n\n### Synchronous Answer\nSynchronously will be delivered an endpoint to check the asynchronous processing state.\n```\nHTTP STATUS 202 (Accepted)\n{\n \"task\": {\n \"href\": \"/interface/foo/123\",\n \"id\": \"123\"\n }\n}\n```\n\n### Check the State of an Endpoint\nThe client can follow the href to check the state of processing.\n\n#### Best-practice:\nAs long as the `state = pending` the attribute `pingAfter` dictates when to send a new request.\n\nAn example entity would be:\n```\n{\n \"state\": \"pending\",\n \"message\": \"is running boy\",\n \"progress\": \"35\",\n \"total\": \"100\",\n \"pingAfter\": \"2019-05-01T13:25:12+0200\",\n \"links\": [\n {\n \"rel\": \"self\",\n \"href\": \"/foo/bar/123\"\n },\n {\n \"rel\": \"failed\",\n \"href\": \"/foo/bar/123/failed\"\n },\n {\n \"rel\": \"succeeded\",\n \"href\": \"/foo/bar/123/succeeded\"\n }\n ]\n}\n```\n\n### Fetching files like PDF and CSV\n\nClients don't have to know the filetype that will be returned from a resource.\nResources serving files will have the appropriate file extension in the URL as shown in the example below.\n\n**Request Headers**\n```\nGET /SomeInvoice.pdf HTTP/1.1\nAccept: */*\n```\n\nClients 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).\n\n**Response Headers**\n\n ```\nHTTP/1.1 200 OK\nContent-Length: 514493\nContent-Type: application/pdf\n```\n\n## Common fields\nCommon 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.\n\n### Some standard formats:\n- Time: Accept in any time zone in ISO-8601 format and always reply in UTC.\n\n Example: `YYYY-MM-DD` and `hh:mm:ss.sss`: `2020-03-12` and `22:33:34.400`\n- Currency: ISO-4217.\n\n Example: `EUR` for Euros, `GBP` for British Pound Sterling.\n- Country code: ISO-3166-1 alpha-3\n\n Example: `DEU` for Germany, `NOR` for Norway.\n\n\n# Best Practices\n\n*In the following you can find some best practices for working with our OTTO Market API which will help you to build up a better connection to our marketplace!*\n\n1. Stay within the rate limits\n2. Send data in Batch and fetch data as a list\n3. Take action when getting back http 4** errors\n4. Consider the two-step validation process for creating products\n5. Consider the \"Unchanged\" status during product update or creation\n6. Make sure product intentifier stay the same\n7. Maintain the most relevant attributes for your products\n8. Keep information provided by OTTO up to date\n9. Consider the content requirements for product data\n10. Utilize the MOIN as an identifier for further processes\n11. Use Announced Orders for stock reservation\n12. Consider the delivery type in the shipments\n\n## Stay within the rate limits\n\nEach endpoint of the API has its own rate limits. These limits were set with the aim of ensuring optimal utilization of the server's available resources, maintaining the best quality for all API users, and facilitating the fastest possible processing of requests. Additionally, rate limiting errors can prevent important data from being entered into the system, leading to data discrepancies. Please take into account the rate limits when making your requests and adjust them accordingly if you receive HTTP 429 errors. You can find a complete list of the current rate limits [here](https://api.otto.market/docs#section/OTTO-Market-API-Developer's-Guide/Rate-Limiting).\n\n## Send data in Batch and fetch data as a list\n\nTo manage the load, it is advisable if the relevant endpoint makes it possible to send the data in bulk. Each endpoint has a different limit which must be considered. Please make the best possible use of the limit to reduce the number of requests. Some endpoints will perform your request asynchronously when sending data in bulk - for more information about bulk requests have a look [here](https://api.otto.market/docs#section/OTTO-Market-API-Developer's-Guide/Bulk-requests).\nIf you want to retrieve data from the OTTO Market API, you should favor a list retrieval. Various parameters are available for retrieving the list in order to filter the list and achieve the desired result. Please make sure that you fetch all pages - for more information about the pagination have a look [here](https://api.otto.market/docs#section/OTTO-Market-API-Developer's-Guide/Pagination).\nIn some cases, you can also perform a direct retrieval for individual SKUs. However, you should only do this selectively and always use the list retrieval for regular retrievals.\n\n## Take action when getting back http 4** errors\n\nFor each request you are sending to the OTTO Market API, you will receive a http code. Please make sure that for each client error (http codes 4**) you have a monitoring on your end and take action to reduce the amount of http 4** errors.\nEach client error is caused by incorrect data in the request or payload and needs to be fixed before a retry will be forced. The best way is to show the error codes on your end and only send the data again, after the data were fixed.\n\n\n## Consider the two-step validation process for creating products\n\nProduct uploads go through a two-step validation process. Errors from the first validation stage can be viewed through the import error report ([GET /products/update-tasks](https://api.otto.market/docs#tag/Products-V3/operation/Products-V3__progressByProcessId)) and indicate a general product upload issue based on the body request schema. Errors from the second validation stage (otto.de) are embedded in the marketplace status ([GET /products/marketplace-status](https://api.otto.market/docs#tag/Products-V3/operation/Products-V3__getMarketPlaceStatusList)), and resolving these errors directly generates an offer on otto.de.\n\nPlease also note that the API is asynchronous and you need to get the results via the /products/update-tasks endpoint. This means that the 202: Accepted response you receive after sending a request indicates that we have received your request, but it does not guarantee that we have processed it.\n\n## Consider the \"Unchanged\" status during product update or creation\n\nWhen managing product data, also consider retrieving and taking into account the results for \"unchanged\". Data sets that are found in the unchanged status of the import will be discarded by us. The reason is that exactly the same records have been sent without changes. However, this does not mean that the data sets were processed successfully as data sets that previously had errors and were sent again without any changes will also end up in the \"unchanged\" status. Find more information about the topic [here](https://api.otto.market/docs#tag/Products-V3/operation/Products-V3__unchangedByProcessId).\n\n## Make sure product identifier stay the same\n\nThe combination of **productReference** and **SKU** for one specific EAN cannot be changed once it has been successfully created in OTTO systems. However, if either of the two identifiers needs to be modified, it is necessary to first deactivate either the affected SKU or all SKUs associated with a productReference via the Active-Status endpoint ([POST /products/active-status/](https://api.otto.market/docs#tag/Products-V3/operation/Products-V3__updateActiveStatus) active=false).\nAfter deactivating the SKU, the correct product data must be resubmitted. In case you´ve only updated the productReference and the SKU(s) stay the same, it is important to reactivate the affected SKU(s) via the Active-Status endpoint ([POST /products/active-status/](https://api.otto.market/docs#tag/Products-V3/operation/Products-V3__updateActiveStatus) active=true). If the SKUs have changed, they will be treated as new SKUs and will start with active=true status.\n\n## Maintain the most relevant attributes for your products\n\nThe assignment of products to filters and specific shopping paths on otto.de is based on the maintained attributes/features in the product data. For this purpose, the provided category list ([GET /products/categories](https://api.otto.market/docs#tag/Products-V3/operation/Products-V3__getCategoryGroups)) offers indications of the relevance and importance of each attribute/feature. Highly important attributes/features are marked with **relevance=HIGH**. Additionally, the **featureRelevance** indicates the specific use of each attribute (e.g., LEGAL, FILTER, SEARCH, NAVIGATION,...) Please note: All attributes with featureRelevance = LEGAL are mandatory and needs to be maintained.\nYou can also find information about attributes relevant for the variant building on otto.de. The right attributes will be shown withing the **variationThemes**.\nIt is highly recommended to maintain as much attributes with relevance=HIGH to higher your visibility on otto.de.\n\n## Keep information provided by OTTO up to date\n\nAs changes to categories, attributes, and default values can occur, it is important to always have an up-to-date version of the category list ([GET /products/categories](https://api.otto.market/docs#tag/Products-V3/operation/Products-V3__getCategoryGroups)). This ensures that only valid categories, attributes, and allowed values are transmitted. Similarly, the brand list ([GET /products/brands](https://api.otto.market/docs#tag/Products-V3/operation/Products-V3__getBrands)) should be kept up to date. Regularly retrieving these lists, ideally on a daily basis, ensures their accuracy and minimizes the potential for errors.\n\n## Consider the content requirements for product data\n\nDuring the product transfer, certain mandatory fields (such as SKU, EAN, category, brandid - see \"required\" in the request body schema of the [POST /products/](https://api.otto.market/docs#tag/Products-V3/operation/Products-V3__createOrUpdateProductVariations) endpoint and attributes marked within the category list with featureRelevance=LEGAL must be provided.\nAdditionally, specific formats for attributes/features must be adhered to. Furthermore, the defined formats for attributes/features and the technical requirements for media data (see below) must be considered. Compliance with the content requirements is essential for successful product upload, and conducting a pre-validation for these attributes/features helps minimize potential errors during the product transfer.\n\nTechnical requirements for media data:\n\n\t• File formats: \n\t\t○ Images: JPG, PNG\n\t\t○ Documents: PDF\n\t• Minimum dimensions for images: 500x1000 px (including color tiles and energy labels)\n\t• File name: No special characters or umlauts\n\t• Color space: RGB - Color spaces such as CMYK are not supported\n\t• Maximum image side for image: 4500 px\n • Main image should be uploaded as a cutout. If not, it has to have a light, neutral background image (example: light gray, white, offwhite, light beige, etc.).\n\n## Utilize the MOIN as an identifier for further processes\n\nAlways verify if the MOIN has been correctly retrieved and stored for each SKU. It should always match the MOIN you´ve get via the [marketplace status](https://api.otto.market/docs#tag/Products-V3/operation/Products-V3__getMarketPlaceStatusList), and this check should be performed regularly. Please use the list retrieval with the **lastModified** parameter to instantly detect any recent changes. This helps to prevent errors in the second validation stage regarding competition-related issues with products. Additionally, the MOIN can also be used as an identifier for inventory updates. When a SKU gets a MOIN in the OTTO systems, the SKU is correctly created and inventory could be sent. Inventory updates for SKUs which are not correctly created will end up in an error. This approach helps minimize the number of requests and optimizes the overall workload.\n\n## Use Announced Orders for stock reservation\n\nBefore an order receives the status **PROCESSABLE** and is therefore ready for processing, the order remains in the status **ANNOUNCED** for approximately 30 minutes after the customer order has been placed. During this time, the customer is able to cancel all or part of their order directly in their customer account. Customer orders with **paymentMethod=Prepayment** can remain in ANNOUNCED status for up to 10 working days.\nIt is therefore advisable to retrieve the ANNOUNCED orders and reserve inventory accordingly in your system. This can prevent overselling and the associated higher cancellation rate.\n\n## Consider the delivery type in the shipments\n\nWhether or not a **returnTrackingKey** must be provided when submitting a shipment request depends on the attributes maintained for the respective product. Please note that for all products that were created with **deliveryType=PARCEL**, you must also provide a returnTrackingKey when submitting the shipment request.\n\n# Use-Cases\n\n## How to list your first product\n\n*This sections goal is to guide you through our API docs and help you list your first product on the OTTO Market.\nYou´ll find short introductions to the steps to be taken followed by a link to the technical documentation for that step.*\n\nTo list a product you´ll have to do the following:\n\n1. Authenticate\n2. Read valid brands\n3. Read valid categories\n4. Post product\n5. Check update-tasks\n6. Check marketplace status\n7. Create shipping profile\n8. Update product delivery information\n9. Update quantities\n\n### Authenticate\nAt first you have to start by authenticating to the OTTO Market Server by posting your credentials to fetch an access token\nhttps://api.otto.market/docs#section/OTTO-Market-API-Developer's-Guide/Authentication-Options-for-OTTO-Market-API\n\n### Read valid brands\nNext you have to read the valid brands and find your relevant brand. You can only sell brands where the attribute \"usable\" = true. If you cannot find your brand, you have to create a new one by following the brand creation process in the OTTO Partner Connect Portal.\nhttps://api.otto.market/docs#tag/Products-V4/operation/Products-V4__getBrands\n\n### Read valid categories\nFollowing that you´ll need to read the valid categories to know which category to list your products in.\nYou are also be able to read from the list which attributes are mandatory (fe when listing in a specific category and which attribute is relevant for increasing the visibility of a product. Here you have to look after **relevance** and **featureRelevance** to get more information about customer relevance the usage of the attribute on otto.de. All attributes with the **featureRelevance=LEGAL** are mandatory for creating a product.\nhttps://api.otto.market/docs#tag/Products-V4/operation/Products-V4__getCategoryGroups\n\n### Post product\nWhen you´ve gathered a valid brand and category, know which attributes you want to add and now it´s finally time to post your first product.\nBy reading the documentation mentioned below you´ll learn which values (e.g. EAN, SKU, productDescription, ...) are required.\nPlease note that the title on otto.de is created by OTTO using your information in the product data. The title is composed of individual fields such as \"category\", \"brandId\", \"productLine\"... The structure can be different for each category. An info about the structure you get also in the category list in the field \"title\".\nYou´ll also find an example request for create or update product variants on this page.\nhttps://api.otto.market/docs#tag/Products-V4/operation/Products-V4__getPartnerProducts\n\n### Check update-tasks\nIf you´ve posted your product from the step before, you´ll reveice an http 202 with different links in the response. In the next step you have to check for errors by addressing the \"Update-Tasks\".\nTo get further information you have to proceed a get request with the \"self\" link. When the process state changed from \"pending\" to \"done\", you can fetch further information with the \"failed\", \"succeeded\" or \"unchanged\" link. In the response of the \"self\" link you also can see how much SKU can be found under which link. If there were errors you´ll have to solve these and post your updated product listing again.\nDon´t forget to check the update-tasks another time before carrying on.\n**Attention!** Posting the exact same data a second time is a bad idea since our server is configured to ignore duplicate listings. If a product data would have been ignored, you´ll find the information within the \"unchanged\" link.\nhttps://api.otto.market/docs#tag/Products-V4/operation/Products-V4__progressByProcessId\n\n### Check marketplace status\nLast validation step for your product is to check the marketplace status of your SKU.\nThrough Update-Tasks you´ll see if there are technical errors you´ll have to solve. In the marketplace status you´ll see if there are non-technical errors you´ll have to solve. As well the \"moin\" will be shown in the marketplace status at first. We recommend to fetch the marketplace status for each SKU as a list with the parameter \"fromDate\" in a regularer basis to see \"errors\" and get the current \"moin\".\nhttps://api.otto.market/docs#tag/Products-V4/operation/Products-V4__getMarketPlaceStatusList\n\n### Create shipping profile\nAfter your product data is correct and could go live, you need to make sure that the SKU gets all transaction data to go visible for OTTO customer.\nYou can either create your shipping profiles manually in the OTTO Partner Connect Portal or using the API.\nBesides the transportation and default processing time, you need to give information about the deliveryType, Cut-Off-Time and the working days.\nIf you will offer products with different deliveryTypes, you would need to create more than one shipping profiles.\nEach shipping profile will get a shippingProfileId which should be used in the next step.\nYou´ll also find an example request for create, update and get a shipping profile on this page.\nhttps://api.otto.market/docs#tag/ShippingProfiles-V1\n\n### Update product delivery information\nIf you´ve created shipping profiles and successfully created your first SKUs, you can now add product delivery information to the correct SKUs.\nYou can either work with the default processingTime configured in the shipping profile or update the processingTime for a specific SKU via the POST Request.\nTo reduce error messages, just sent over product delivery information for SKU wherefore you have gotten a \"moin\" via the marketplace status.\nhttps://api.otto.market/docs#tag/Availability-V1/operation/Availability-V1__storeProductDeliveryInformationUsingPOST\n\n### Update quantities\nLastly you´ll have to set the quantities of your product so customers can finally see and buy your product. To reduce error messages, just sent over quantities for SKU wherefore you have gotten a \"moin\" via the marketplace status.\nhttps://api.otto.market/docs#tag/Availability-V1/operation/Availability-V1__storeAvailableQuantitiesUsingPOST\n\n**Congratulations!** You´ve successfully listed your first product on the OTTO Market.\nThe next step is to regularly check for new orders. In the following case you can learn all about the order process and what you have to know about some specifics. [Click here to learn how to do that.](https://api.otto.market/docs#section/Use-Cases/Manage-an-order-from-start-to-finish)\n## Manage an order from start to finish\n\n*This sections goal is to guide you through our API docs and help you fulfilling your first order including subsequent activities on the OTTO Market.\nYou´ll find short introductions to the steps to be taken followed by a link to the technical documentation for that step.*\n\nTo fulfill your first order and manage subsequent activities you´ll have to do the following:\n\n1. Authenticate\n2. Regularly check for new orders\n3. Report order as shipped\n4. Fetch purchase receipt\n5. Regularly screen for return announcements\n6. Process returns\n7. Fetch refund receipt\n\n### Authenticate\nYou´ll have to start by authenticating to the OTTO Market Server by posting your credentials to fetch an access token\nhttps://api.otto.market/docs#section/OTTO-Market-API-Developer's-Guide/Authorization-(OAuth2)\n\n### Regularly check for new orders\nNext you´ll have to regurlarly check for new orders to fulfill. We recommend checking several times a day.\nYou´ll find the different fulfillment states orders can have, their descriptions and common use-cases listed at [this page](https://api.otto.market/docs#tag/Orders-V4). We also recommend to fetch orders in the **state=ANNOUNCED** for the reservation of quantity on your end. After the order switched to the **state=PROCESSABLE** (usually after 35 Minutes except for the paymentMethod=prepayment) the customer information will be visible in the order.\nTo carry on with fulfilling your first order the state has to be = PROCESSABLE.\nhttps://api.otto.market/docs#tag/Orders-V4/operation/Orders-V4__findPartnerOrders\n\n### Report order as shipped\nPackaging the ordered items is next before you can hand them to your carrier and mark the order as shipped.\nWe´ll call it a shipment from this point onward. Every shipment needs a **tracking key** and unless it´s a forwarder shipment you´ll also have to provide a **returnTrackingKey** upfront. If a returnTrackingKey is mandatory for a shipment is dependent on the deliveryType of the sku needed to fulfill in the shipment. You can manage the deliveryType for each sku within the productdata update process.\nPlease read the following endpoint for all technical information:\nhttps://api.otto.market/docs#tag/Shipments-V1/operation/Shipments-V1__createdAndSentShipmentUsingPOST\n\nIf you want to fulfill a sku with more than one package, you´ll need to split the shipment and use [this endpoint](https://api.otto.market/docs#tag/Shipments-V1/operation/Shipments-V1__createdAndSentMultiparcelShipmentUsingPOST).\n\n### Fetch purchase receipt\nAfter the shipment was successfully created, a purchase receipts will be created on our end. These receipt will be shown to the customer in ther customer account. You can get the purchase receipt by using the receipts endpoint with the **receiptTypes=PURCHASE** as JSON. You also can fetch the receipt as PDF by using the **receiptNumber**. We recommend to use the parameter **receiptTypes** and the parameter **from** and **to**. You also can fetch receipts specifically for one order by using the parameter **salesOrderId**. For further information have a look in the description of the receipts api listed at [this page](https://api.otto.market/docs#tag/Receipts-V3)\nPlease read the following endpoint for all technical information:\nhttps://api.otto.market/docs#tag/Receipts-V3/operation/Receipts-V3__getReceiptsUsingGET_5\n\n### Regularly screen for return announcements\nCustomers may want to return their order wholly or partially. Return labels will be created through their customer interface and the return status will change to announced. The status misdirected is also displayed to inform you that a customer has mistakenly returned the product to otto. It is recommended to regularly check for announced and misdirected returns using the following endpoint:\nhttps://api.otto.market/docs#tag/Returns-V3/operation/Returns-V3__getPositionItemsForUsingGETV3\n\n### Process returns\nReceived returns have to be checked by your warehouse and either accepted or rejected depending on the condition of the return.\nAccepting a return will lead to a customer repayment. You can accept returns using this endpoint:\nhttps://api.otto.market/docs#tag/Returns-V3/operation/Returns-V3__receiveAcceptedReturnsV3UsingPOSTV3\n\nIf the condition of the return is unacceptable you´re able to reject the return. If you do so you have to submit a reason for the rejection:\nhttps://api.otto.market/docs#tag/Returns-V3/operation/Returns-V3__receiveRejectedReturnsV3UsingPOSTV3\n\n### Fetch refund receipt\nAfter the return was successfully created, a refund receipts will be created on our end. These receipt will be also shown to the customer in ther customer account. You can get the refund receipt by using the receipts endpoint with the **receiptTypes=REFUND** as JSON. Our recommendations in fetching the return receipts are same as they are in fetching the purchase receipt. Use different parameter to filter your request and get your relevant information. For further information have a look in the description of the receipts api listed at [this page](https://api.otto.market/docs#tag/Receipts-V3)\nPlease read the following endpoint for all technical information:\nhttps://api.otto.market/docs#tag/Receipts-V3/operation/Receipts-V3__getReceiptsUsingGET_5\n\n**Congratulation!**\nYou´ve successfully gone through the whole order processing process on the OTTO Market. You should know which request are necessary for you and which specifics you have to note.\nIn the next step, we want to give you more information about after-sales processes. [Click here to learn how to do that.](https://api.otto.market/docs#section/Use-Cases/Manage-your-after-sales-actions)\n\n## Manage your after sales actions\n\n*This sections goal is to guide you through our API docs and help you with your after sales actions. You will learn what kind of actions you can handle via the OTTO Market API and what you have to consider doing that.\nYou´ll find short introductions to the steps to be taken followed by a link to the technical documentation for that step.*\n\nTo manage your after sales activities you´ll have to do the following:\n\n1. Authenticate\n2. Get in touch with customer\n3. Get customer messages\n4. Give subsequent discounts (price-reductions)\n\n### Authenticate\nYou´ll have to start by authenticating to the OTTO Market Server by posting your credentials to fetch an access token\nhttps://api.otto.market/docs#section/OTTO-Market-API-Developer's-Guide/Authorization-(OAuth2)\n\n### Get in touch with customer\nAfter the customer ordered a product from you, you will receive an encrypted e-mail address in the order. The encrypted e-mail address is part of the invoice address and should be used only in certain cases for the execution of the shipment or return. These cases can take place before and after the shipment is done. i.e. if you have some detailed questions about the delivery address, changes of the trackingNumber, reason why you rejected the return and to clarify the remainder of the goods and so on.\n**Attention!** You must use as sender e-mail address the one that has been stored in the seller information for customer communication.\n\nThere could be also an e-mail address within the delivery address when a customer ordered a product which needs to be fulfilled via a forwarder agency. In this cases the correct e-mail address and phone number of the customer will be shown.\n**Attention!** You may only use this contact information to pass it on to the shipping company so that they can contact the customer to clarify the delivery date.\n\n### Get customer messages\nCustomer are able to contact you in specific cases to the shipment, order or for product relevant questions directly through the customer portal. You will receive the e-mail in the OTTO Partner Connect section \"Customer Communication\" and are able to send your answer directly in the portal. You´ll also have the option to get all customer messages directly to the e-mail adress you´ve stores in the seller information in the OTTO Partner Connect. You can reply directly to incoming mails.\n\n### Give subsequent discounts (price-reductions)\nIf a customer is unsatisfied with the condition of the item he or she will usually return it. Depending on the product and the condition the customer might be interested in keeping the product if a discount is given. Customers usually contact you or OTTO to discuss such an option.\nYou can either grant discounts within the OTTO Partner Connect or via the API within the \"price-reduction\" endpoint.\nThe following endpoint documentation describes how you´re able to provide such a \"price-reduction\":\nhttps://api.otto.market/docs#tag/Price-Reductions-V1/operation/Price-Reductions-V1__applyPriceReduction\n\n### Fetch partial refund receipt\n\nAfter a price reduction was initiated, a partial refund receipt will be created on our end. The PDF document of such a receipt will be shown to the customers in their customer accounts. You can get the partial refund receipt by using the receipt endpoint with ```receiptTypes=PARITAL_REFUND``` as JSON. Our recommendations in fetching the partial refund receipts are same as they are in fetching the purchase receipt. Use different parameter to filter your request and get your relevant information. Please read the following endpoint for all technical information: https://api.otto.market/docs#tag/Receipts-V3/operation/Receipts-V3__getReceiptsUsingGET_5\n\n\n# Sandbox\n\n### General\n**Sandbox is the test environment,**\nused for testing an API connection. It provides all the functionalities of the live OTTO Market Interface. All actions and orders there are simulated for testing purposes.\n\nThe login session and the API key in the sandbox environment are completely separated from the production environment.\n\nREST API: **https://sandbox.api.otto.market**\n\n## Getting started\nFollow these steps to start testing on our sandbox environment:\n\n1. Make yourself familiar with sandbox functionalities.\n2. Request a sandbox API user:\n As a **partner (seller)** you first have to make sure that your user have the role \"API-Zugriff\". You can then navigate to the [API-Zugriff](https://portal.otto.market/settings/API). There you can create a Sandbox App for yourself.\n As a **service partner** please register in our [OTTO Market Service Partner Program](https://servicepartner.otto.market/). Follow all necessary steps and request the \"Sandbox Apps\" Permission to get access to create Sandbox Apps.\n\n3. Authenticate to our sandbox environment. As Partner have a look at the [Developer's Guide](https://api.otto.market/docs#section/OTTO-Market-API-Developer's-Guide/Authentication-Options-for-OTTO-Market-API) and as service partner have a look at the specific information in [Developer Program](https://api.otto.market/docs#section/Developer-Program/Access-to-Sandbox).\n4. Make yourself familiar with our [Best-Practice test cases](https://api.otto.market/docs#section/Sandbox/Best-Practice-test-cases) and download the testcase file\n5. Use our Order Generator to create fictional orders. See [Order Generator](https://api.otto.market/docs#section/Sandbox/Order-Generator) below to know, which orders are created.\n6. Test the API functionality of your application.\n\n## Technical Advice\nPlease note the following information:\n### Authorization\nFor the endpoint like all the other endpoints a valid authorization token has to\nbe sent. If you need further information, please consult the [Developer's Guide](https://api.otto.market/docs#section/OTTO-Market-API-Developer's-Guide/Authentication-Options-for-OTTO-Market-API).\n\n### Sandbox Reset\nTo prevent data overload, our sandbox and its orders are reset monthly at first Sunday from 6 p.m. to 10 p.m.\\\nAny dynamic data (shipments, returns) is deleted. Old shipments will not be available anymore.\\\nTherefore, you have to create new orders every month.\n\n### Customer-Interactions in Sandbox\nSince there are no real costumers, all interfaces which work with customer data will either mock customer data or reduce the functionalities i.e. returns cannot be announced. Hence, the GET endpoint of returns is retrieving an empty string.\n\n### Product validation\nSubmitted product data is validated in two steps, which will be explainded further on:\n\n**Attention:** Since the sandbox is missing a direct shop integration the second validation is simulated. For more details on how to test these functionalities, please have a look into our [Best-Practise test cases](https://api.otto.market/docs#section/Sandbox/Best-Practice-test-cases), where you can find specific EANs for testing purposes.\n\n**1. Technical validation**\n\nThe first technical validation (syntax and required attributes) takes place after you´ve sent product data using a POST request.\nRead more about uploading products [here](https://api.otto.market/docs#tag/Products-V3/operation/Products-V3__createOrUpdateProductVariations).\nIf your http request was successful (http response state 202), you´ll be provided with four different links (pending, succeeded, failed, unchanged).\nFollowing the links you´ll be able to check which products have been successfully listed, failed, unchanged or are still being processed.\n\n|Status|Explanation|\n|:-|:-|\n|Pending|The product listing is still being processed|\n|Succeeded|The shown products listing was successful|\n|Failed|Listing of all shown products has failed|\n|Unchanged|The request for the listed products is unchanged to the last request|\n\n**2. Shop validation**\n\nThe second step is the shop validation. Results of the shop validation are retrievable using the **marketplace-status endpoint**.\nPlease read the following [documentation](https://api.otto.market/docs#tag/Products-V3/operation/Products-V3__getMarketPlaceStatusList) on how to use the marketplace status endpoint.\nSubmitted product data always has one of the following four marketplace statuses:\n\n| Status | Explanation |\n|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Pending | Submitted product data is currently proceeded. |\n| Online | The SKU is displayed at otto.de. You can find the SKU using the shop link.
In some cases, additional information will be shown on how to improve the visibility on otto.de. |\n| Restricted | The SKU is not displayed at otto.de because of an error shown within the error’s container. |\n| Inactive | The SKU was set inactive via the active-status endpoint and could be reactivated via the active-status endpoint. |\n\n**Attention:** Since the sandbox is missing a direct shop integration the second validation is simulated. For more details on how to test these functionalities, please have a look into our [Best-Practise test cases](https://api.otto.market/docs#section/Sandbox/Best-Practice-test-cases), where you can find specific EANs for testing purposes.\n\n## Order Generator\nTo test your API implementation you can generate test orders only on the sandbox environment by sending an empty POST request to the following generation endpoint:\n\n[https://sandbox.api.otto.market/v4/orders/testorders]()\n\nThis will run 8 predefined scenarios on our sandbox. After the POST request, you will receive 6 orders in \"PROCESSABLE\" status with different combinations of positions and items (e.g. standard and freight delivery). You will also receive 1 prepayment order in \"ANNOUNCED\" and 1 order in \"CANCELLED_BY_MARKETPLACE\" status.\n\nThe generated orders will contain one or more position items with the following products:\n\n| Product Title | EAN | SKU |\n|-------------------------------------|---------------|-----------------------|\n| Smartphone »CallMe 1000« | 1245780164732 | SmartCM1000-schwarz-1 |\n| Fancy Shirt »Flower« | 4851278936452 | FancyFlower-m-pi |\n| Rasenmaeher »Turbo V1« | 9821393948573 | 0440-Rasen-T-V1 |\n| Spedition Wohnlandschaft 3.tlg. | 8263748321943 | Sped-Wohn-3-98735 |\n| Spedition Kühlschrank »COOL EXTREM« | 7263000981290 | Sped-Kühl084-kombi |\n\nScenarios:\n\n| Scenarios | Status | Comment |\n|------------------|--------------------------|----------------------------------------------------------------------------------------------------------------------|\n| 1, 2, 3, 4, 7, 8 | PROCESSABLE | Scenario 4 inclusive discount |\n| 5 | ANNOUNCED | Order with payment method PREPAYMENT awaiting customer's payment
Order includes weeePickup on position item level |\n| 6 | CANCELLED_BY_MARKETPLACE | Order with payment method PREPAYMENT which has been cancelled since the customer didn't pay |\n\nPlease use the generated orders to test the interaction with Orders, Shipments and Returns.\n\nIf you want to create a single scenario you can do that by sending an empty POST to:\n\n[https://sandbox.api.otto.market/v4/orders/testorders/scenario\\{scenarionumber\\}]()\n\ne.g. [https://sandbox.api.otto.market/v4/orders/testorders/scenario1]()\n\n## Best-Practice test cases\n\nWe´ve come up with mulitple test cases to help you test the basic functionalities needed for each endpoint when offering your service to an OTTO Market Seller.\nThe test cases should be tested within the sandbox environment. If you´re interested in feedback from our service partner management you can send screenshots of the test results [here](https://account.otto.market/s/ticketanlegen?category=Supportrequest&Unterkategorie=technicalInterfaces&Interface__c=api&Subject=%5BOTTO+Market+API%5D+Service+Partner+Test+Cases).\n\nThe Best-Practice testcases should help you as a developer to understand the behavior and the interdependencies between different APIs.\nWith the test cases you can get hints for testing the interfaces and to reproduce the [Use-Cases](https://api.otto.market/docs#section/Use-Cases) within the sandbox-environment.\n\nWe´re referring to the test orders created using the *test order generator* within the sandbox environment. Please read the section [Order Generator](https://api.otto.market/docs#section/Sandbox/Order-Generator) on how to create test orders.\n\nYou can download a file where you can find the Best-Practice test cases here.\n\n\n# Developer Program\nThis section describes how a service partner can integrate with OTTO Market API.\nThe developer program aims at equipping the service partners with authentication and authorization for accessing the OTTO Market API `on behalf of the partner`.\n\n## Target Group\nThe Developer Program is intended primarily for service partners who want to exchange data for OTTO Market Partners and offer their service to other sellers. OTTO Market Partners who would like to develop their own OTTO Market API connection use their own API user and can find more information [here](https://api.otto.market/docs#section/OTTO-Market-API-Developer's-Guide/Authentication-Options-for-OTTO-Market-API).\n\n## Registration as Service Partner\nIf you want to register as a service partner who needs to access Partner data, please follow the steps at [servicepartner.otto.market](https://servicepartner.otto.market/register).\nYou'll receive email notifications for any approval / denial of registration requests.\n\nAfter submitting your registration you will get access to the basic functionalities of our portal. To tailor your experience and unlock additional features, head over to the Permission Management Section. To start the journey you have to request your first permission for creating Sandbox Apps. With our confirmation, you will receive 30 days' test access to the sandbox environment for getting to know the inferfaces and estimate your effort without completing the registration process.\nIf you decide to integrate, complete the registration by filling out the self-disclosure form. You will receive the form at the end of the 30-day test access period. We will grant you unlimited sandbox access afterwards.\n\nAt the point when you decide to go live and roll-out your service, you can request the permission for creating private production apps in the permission management. You need to start working with the production environment in private access first for test and learn with pilot integrations. Afterwards you can request public production access by request the right permission.\n\nFor more information about the registration and integration process, please have a look at [servicepartner.otto.market](https://servicepartner.otto.market).\n\n## Private and Public Access for Service Partner\n\nOnce you´ve done with testing, requested the permission **private production apps** and we cofirmed the permission, you can now create private apps in the Production environemnt. (Read more about the difference between private and public apps [here](/docs#section/Developer-Program/Private-and-Public-Apps).)\n\n### Getting Public Access\n\nIf you want to get public access follow the steps below:\n\n1. Login to OTTO Partner Connect portal and navigate to the Permission Management\n2. Request the permission \"Public Production Apps\"\n3. Select necessary scopes for your public access\n4. Done! Your request will be reviewed by OTTO Market. You'll receive email notifications for approval / denial of your request.\n\n*Please note: OTTO Market will perform a quality check for each selected scope. You only can go public after passed the quality check and finished an OTTO Market Training. The colleagues will give you more information during the integration process.*\n\n## Private and Public Apps\n\n#### Private Apps\n\nPrivate apps can be created by developer with the permission \"Private Production Apps\". If a OTTO Market partner wants to install a private app, an unique app invitation link (\"Einladungslink\") is required.\n\n**Generate an app invitation link**\nYou can generate an unique app invitation link for an app by following the steps below:\n\n1. Login to the [OTTO Partner Connect](https://portal.otto.market/profile/Servicepartnerprofil) portal.\n2. Navigate to the [OTTO Market Apps](https://portal.otto.market/app-management/service-partner/apps) and [Sandbox Apps](https://portal.otto.market/app-management/sp-sandbox-apps/apps) page for production and sandbox apps respectively.\n3. Click on the three dots (…) right to the app name for which you want to create an invitation link.\n4. In the dropdown menu select \"Einladungslink generieren\".\n5. A popup window will be displayed. Copy the link from this window - it will not show up again.\n6. Done! You can now share the app invitation link with a OTTO Market partner.\n\n`Note:` You should be aware of the following:\n- After closing the popup window with the invitation link you won't be able to see this exact invitation link again.\n- You can create as much invitation links as you want to.\n- There is no possibility to show all invitation links created for a specific app.\n- Every app invitation link is only valid for 24 hours and can be used only once. (When it is used or expired the link will become invalid and you have to create a new one.)\n- If a partner clicks on the link but don't grant consent the link remains valid (until it is either expired or consent is granted).\n\n#### Public Apps\n\nPublic apps can only be created developer with the permission \"Public Production Apps\". (For getting public access refer to [Getting Public Access](https://api.otto.market/docs#section/Developer-Program/Access-to-Production).)\nIn order to install a public app, an universally valid installation link (\"Installationslink\") is required. After creating a public app this link is displayed in the app details page. You can share this link whereever you want.\nYou can also add an optional parameter \"state\" to this installation link, which preserves the state of your application page and returns user back to that state after they install. If this optional parameter exists, the user will be redirected to app's callback URL along with the optional state.\nBut be aware that it is universally valid meaning you cannot control which partner will install your app.\n\n## Scopes\n\nScopes corresponds to [OAuth scopes](https://oauth.net/2/scope/). 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.\n\n### Scopes for OTTO Market APIs\nThe below table gives mapping of displayed scope names in UI to the scope names to be used for fetching token\n\n| Display Name | Scope Name (To be used in fetching token) |\n|-------------------|-------------------------------------------|\n| Installation | installation |\n| PartnerId | partnerId |\n| Developer | developer |\n| Products | products |\n| Orders | orders |\n| Receipts | receipts |\n| Returns | returns |\n| Price Reduction | price-reduction |\n| Shipments | shipments |\n| Quantities | quantities |\n| Shipping Profiles | shipping-profiles |\n| Availability\t | availability |\n\n### Content declaration of available scopes\n\n#### Installation\nThe installation interface allows a service partner to get the installation details of a Partner\n\n#### PartnerId\nThe partnerId interface allows a service partner, access to the partner's partner id.\n\n#### Developer\nThe developer interface allows a service partner to fetch an installation token\n\n#### Products\n\nThe 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.\n\nRead more about the technical possibilities [here](https://api.otto.market/docs#tag/Products-V4).\n\n#### Quantities - depcrecated and will be shut down to the end of March 25. Use the Availability Interface for updating quantities.\n\nOnce 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.\n\nRead more about the technical possibilities [here](https://api.otto.market/docs#tag/Quantities-V2).\n\n#### Shipping Profiles\n\nWith this interface you can create, change and manage shipping profiles of the otto market partners.\n\nRead more about the technical possibilities [here](https://api.otto.market/docs#tag/ShippingProfiles-V1).\n\n#### Availability\n\nOnce 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.\nAs well you need to connect the sku to existing shipping profiles for the delivery information.\nFor this purpose the Availability Interface allows partners and service partners to update necessary information to make a SKU available on otto.de.\n\nRead more about the technical possibilities [here](https://api.otto.market/docs#tag/Availability-V1).\n\n#### Orders\n\nThis 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.\n\nRead more about the technical possibilities [here](https://api.otto.market/docs#tag/Orders-V4).\n\n#### Shipments\n\nThis 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.\n\nShipments - Read more about the technical possibilities [here](https://api.otto.market/docs#tag/Shipments-V1).\nReturn-Shipments - Read more about the technical possibilities [here](https://api.otto.market/docs#tag/ReturnShipments-V1).\n\n#### Returns\n\nThis scope enables the user to manage returns. This includes retrieving a list of announced returns, accepting and declining returns.\n\nRead more about the technical possibilities [here](https://api.otto.market/docs#tag/Returns-V3).\n\n#### Receipts\n\nOTTO Market provides receipts to the customers to document financial processes. The scopes enables users to download these documents as a PDF or a JSON.\n\nRead more about the technical possibilities [here](https://api.otto.market/docs#tag/Receipts-V2).\n\n#### Price Reduction\n\nThis 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.\n\nRead more about the technical possibilities [here](https://api.otto.market/docs#tag/Price-Reductions-V1).\n\n## Sandbox vs Production\nSandbox apps are used to test your API in sandbox environment, when you are approved for the permission \"Sandbox Apps\" by the OTTO Market team. These apps have unrestricted scopes access, so you can create sandbox apps for any scope even if you don´t need them in the production environment. For creating and testing with sandbox apps, please see [Access to Sandbox](https://api.otto.market/docs#section/Developer-Program/Access-to-Sandbox).\n\nAs the name states, production apps are for production environment. This can be created after you have an approval from OTTO Market team for the permission \"Private Production Apps\". Once you have the approval, you can request for \"Public Production Apps\", to create public apps.\nAn OTTO Market Partner has to provide consent, in order for you to access their production data. The detailed flow is described in the [Access to Production](https://api.otto.market/docs#section/Developer-Program/Access-to-Production) section below.\n\n\n## Access to Sandbox\nOnce your permission request for \"Sandbox Apps\" is approved, you can start using [Sandbox Apps](https://portal.otto.market/app-management/sp-sandbox-apps/apps).\n\n### Creating sandbox test users\nIn [Usermanagement UI](https://portal.otto.market/settings/Nutzerverwaltung) Service Partners can create their own test users for sandbox.\nThis test user can be used for authenticating against sandbox apps\n\nValid email is required for sandbox users. Upon creation of user, a password setting mail will be sent to the given sandbox user emailId\n\n**Please note:** Sandbox users are considered as part of the service partner count itself. You can create a max of 10 users (service partners + sandbox) by default.\n\nPlease also have a look in the [Download section](https://servicepartner.otto.market/en/downloads/downloads.html) of servicepartner.otto.market. There you can find a Step-by-Step Sandbox guide for testing the integration ([here](https://live.divae.servicepartner.otto.market/_Resources/Persistent/1/7/6/b/176bc5208c1cf57e27bf58b98c10752306920a50/Sandbox%20guide%20for%20testing%20the%20integration%20of%20a%20retailer.pdf)).\n\n### Creating sandbox apps\nIn create apps UI, you need to provide the following details,\n- unique name\n- homepage URL\n- authorization callback URL - Refer below section for more info\n- [scopes](docs#section/Developer-Program/Scopes) - All scopes will be listed in sandbox.\n- app type - Refer [Private and Public Apps](docs#section/Developer-Program/Private-and-Public-Apps) for more info\n\n#### Post Installation Redirect URL\nTest Partner will be redirected to your post installation redirect URL after successfully installing your app.\n\n#### Authorization callback URL\n1. Post successful redirection, you will initiate authorization code flow. Test Partner logs in with their credential. On verifying identity, partner will be redirected to your app's authorization callback URL with auth code.\n2. If you intend to incorporate query parameters in your REDIRECT_URI, ensure to suffix the url with an asterisk (*)\n\n#### App ID\nA unique app ID which will be used for identifying a service partner app.\nWhen a partner installs this app, this app ID will be used for fetching the installation details.\n\n#### Installation Link\n\nThis unique, publicly accessible link is intended for OTTO Market partners to facilitate app installation.\n\n- **Optional State Parameter**: An optional `\"state\"` parameter can be added to the installation link to retain the application page’s state. If this parameter is provided, it will be preserved and included in the app’s Post Installation Redirect URL. If the `state` parameter is not provided, the user will still be redirected to the Post Installation Redirect URL, but without the `state` data.\n\n- **Reinstallation Behavior**: If a partner has already installed the app and clicks the installation link again, they will be redirected to the Installations Overview in their OPC account, bypassing the standard installation flow.\n\nYou can simply add this link as a hyperlink on your website for convenient partner access.\n\n#### Client ID & Client Secret\nCredentials to be used for authenticating & authorising your app with OTTO authorisation server for\nfetching installation details of partner\n\n#### IP Addresses\nIf IP addresses are specified for a credential set, requests will only be successful if they originate from those addresses. If no IP addresses are provided, the credential set will expire every 180 days.\n\n#### Version\nDenotes the version of the app\n\n#### Version End Date\nThis version will remain functional until the specified date. Any changes must be scheduled at least 4 weeks in advance(Note:- Once an app version end date is set, it cannot be modified. Please contact the helpdesk if an update is required.)\n\n#### Activation Date\nDate when communication with partners begins for a new version release.\n\n## Access to Production\nOnce you are satisfied with everything you have tested in the sandbox, you can request the permission \"Public Production Apps\" in the permission management in the OTTO Partner Connect Portal.\nWhen approved, you can start creating production apps using [OTTO Market Apps](https://portal.otto.market/app-management/service-partner/apps) in OTTO Partner Connect.\n\n### Creating apps\nIn create apps UI, you need to provide the following details,\n- unique name\n- homepage URL\n- authorization callback URL - Refer below section for more info\n- [scopes](docs#section/Developer-Program/Scopes) - Only scopes approved for you will be shown\n- app type (only if the service partner has public access)\n\n#### Post Installation Redirect URL\nPartner will be redirected to your post installation redirect URL after successfully installing your app.\n\n#### Authorization callback URL\n1. Post successful redirection, you will initiate authorization code flow. Partner logs in with their credential. On verifying identity, partner will be redirected to your app's authorization callback URL with auth code.\n2. If you intend to incorporate query parameters in your REDIRECT_URI, ensure to suffix the url with an asterisk (*)\n\n#### App ID\nA unique app ID which will be used for identifying a service partner app.\nWhen a partner installs this app, this app ID will be used for fetching the installation details.\n\n#### Installation Link\n\nThis unique, publicly accessible link is intended for OTTO Market partners to facilitate app installation.\n\n- **Optional State Parameter**: An optional `\"state\"` parameter can be added to the installation link to retain the application page’s state. If this parameter is provided, it will be preserved and included in the app’s Post Installation Redirect URL. If the `state` parameter is not provided, the user will still be redirected to the Post Installation Redirect URL, but without the `state` data.\n\n- **Reinstallation Behavior**: If a partner has already installed the app and clicks the installation link again, they will be redirected to the Installations Overview in their OPC account, bypassing the standard installation flow.\n\nYou can simply add this link as a hyperlink on your website for convenient partner access.\n\n#### Client ID & Client Secret\nCredentials to be used for authenticating & authorising your app with OTTO authorisation server for\nfetching installation details of partner\n\n#### IP Addresses\nIf IP addresses are specified for a credential set, requests will only be successful if they originate from those addresses. If no IP addresses are provided, the credential set will expire every 180 days.\n\n#### Version\nDenotes the version of the app\n\n#### Version End Date\nThis version will remain functional until the specified date. Any changes must be scheduled at least 4 weeks in advance.(Note:- Once an app version end date is set, it cannot be modified. Please contact the helpdesk if an update is required.)\n\n#### Activation Date\nDate when communication with partners begins for a new version release.\n\n### Extend scopes on an existing App\nIf you want to add more scopes to an existing app, use the \"extend scopes\" functionality to select the additional scopes you wish to access. When you extend the scopes, a new version of the app will be created, replicating the previous app and retaining its values. Please note that the appName cannot be edited, but all other configurations can be modified if needed.\n### Why extend scopes instead of creating a new app?\n- You should create a new app if you have a completely new use case or functionality that you want to exclude from your general service I.e. you are implementing a completely new API interface with new functions on your site and you are expanding the range of the service that you are offering on the OTTO Market.\n- However, if you only need to access new scopes while retaining the existing app configurations, extending the scopes is the preferred option.\n- When you extend the scopes, a new version of the app is created, as mentioned earlier. Partners who installed the previous version will be automatically notified once the activation date is reached that a new version is available. They can then choose whether or not to install the new version.\n- The main advantage of extending the scope of an existing app is the automated and simplified communication by OTTO. OTTO Market Partners will be notified via email and banners in the OTTO Partner Connect portal. This greatly reduces the communication effort required to migrate partners on your side.\n## Installation of app by an OTTO Partner (Sandbox | Production)\n\n $\"App$ \n\n1. **Share the Installation Link with a `state` Parameter (Optional)** \n The application's installation link can be shared with your partners in the following ways. If needed, include a \"state\" parameter for tracking the installer:\n\n- Through your platform or portal.\n- Via an email sent to your partners.\n- Through OPC for a versioned app (when upgrading via OPC, adding a `state` param might not be possible).\n\nYour partner then navigates to the installation link and installs the app.\n\n**Security Notes:**\n- If you include a `state` parameter, ensure it does not expose any sensitive data such as `userId` or similar information. Instead, consider using a secure, random, unguessable value that is only understandable by your system. This value should be valid for a limited time (e.g., 2 minutes) and should be tied to the specific installer session.\n- One way to achieve this is by generating a random token that can be mapped to the installer’s identity within your system. This token should be designed to be unguessable and resistant to attacks, such as using UUIDs or secure random generators.\n\n2. **Redirect to Post-Installation URL and Authenticate the Installer** \n After installation, your partner is redirected to your app’s post-installation URL. If a `state` parameter was included, it will be appended to this URL. At this point, you must authenticate the installer using your IDP.\n\n- Upon landing at the post-installation URL, authenticate the installer using your IDP.\n- Once authenticated, store the installer’s identity (e.g., unique installer ID) for linking purposes.\n\n\n3. **Authenticate the User Against OTTO’s IDP Using OAuth2 Authorization Code Flow** \n After authenticating the user with your IDP, initiate the OAuth2 Authorization Code Flow with OTTO’s IDP. During this process:\n\n- Pass the installer’s identity (or a relevant identifier) as a custom query parameter in the `redirect_uri` (e.g., `installer_id` or similar). This is for the purpose of linking the `installationId` obtained from OTTO to the corresponding installer ID in your system.\n- You can use any query parameter name (e.g., `installer_id`) in the `redirect_uri` that suits your needs, as long as your system understands it.\n\n**Security Recommendation for Installer Identity:**\n- Instead of passing the raw `installerId`, consider passing an encrypted or random, unguessable token that is valid for a short time. For example, generate a token that combines a timestamp (for time-based validity) and a secure random value (e.g., `encrypt(randomToken + currentTime)`). This value should only be understandable by your system and be mapped to the installer’s identity.\n\n3.1 **Redirect the User to OTTO’s Authorization Endpoint:** \nUse the scopes `installation` and `partnerId` to initiate the flow. For example:\n\n ```\n https://sandbox.api.otto.market/oauth2/auth?response_type=code&client_id={CLIENT_ID}&redirect_uri={YOUR_REDIRECT_URI}&scope=installation%20partnerId\n ```\n\n3.2 **User Logs in and Authorizes the App:** \nThe user logs in and verifies their identity through OTTO’s login page.\n\n3.3 **Receive Authorization Code:** \nUpon successful authorization, your app will receive the authorization code at the specified redirect URI.\n\n3.4 **Exchange the Authorization Code for an Access Token:** \nMake a POST request to the token endpoint to get an access token:\n\n ```plaintext\n POST /oauth2/token HTTP/1.1\n Host: sandbox.api.otto.market or api.otto.market\n Content-Type: application/x-www-form-urlencoded\n\n grant_type=authorization_code&client_id={yourClientId}&client_secret={yourClientSecret}&code={yourAuthorizationCode}&redirect_uri={https://yourApp/callback}\n ```\n\nFor more information on implementing the OAuth2 Authorization Code Flow, please refer to the [OAuth 2.0 Authorization Code](https://tools.ietf.org/html/rfc6749#section-4.1) section of the OAuth2 standard documentation. You can retrieve the necessary endpoints from the OpenID Connect well-known configuration:\n\n- Sandbox Well-Known Endpoint: [Sandbox Well-Known Endpoint](https://sandbox.api.otto.market/sec-api/auth/realms/deepsea-sandbox/.well-known/openid-configuration)\n- Production Well-Known Endpoint: [Production Well-Known Endpoint](https://api.otto.market/sec-api/auth/realms/otto-partner/.well-known/openid-configuration)\n\n**Note:** \nIf your app’s post-installation URL is the same as the OAuth2 callback URL, passing the installer’s ID in the `redirect_uri` is unnecessary, as you’ve already retained it.\n\n4. **Retrieve and Link the Installation ID with the Installer’s Identity** \n Once you have authenticated the user against OTTO’s IDP, retrieve the installation ID:\n\n ```plaintext\n GET /v1/apps/{appId}/installation HTTP/1.1\n Host: sandbox.api.otto.market or api.otto.market\n Authorization: Bearer {access_token}\n ```\n\n **Response:**\n\n ```json\n {\n \"installationId\": \"string\",\n \"appVersion\": \"V3\",\n \"existingInstallations\": [\n {\n \"installationId\": \"string\",\n \"state\": \"ENABLED\",\n \"appVersion\": \"V1\"\n }\n ]\n }\n ```\n\n **Note:** \n For first-time installations, no values will appear under `existingInstallations`. Store the installation ID alongside the installer’s identity in your system.\n\n5. **Fetch a Developer Access Token Using Client Credentials Flow** \n To fetch a developer access token, implement the Client Credentials Flow:\n\n ```plaintext\n POST /oauth2/token HTTP/1.1\n Host: sandbox.api.otto.market or api.otto.market\n Content-Type: application/x-www-form-urlencoded\n\n grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&scope=developer\n ```\n\n Replace `{CLIENT_ID}` and `{CLIENT_SECRET}` with your client details.\n\n6. **Retrieve an Installation Access Token and Access OTTO Market APIs** \n With the developer access token, obtain an installation access token by making a POST request:\n\n ```plaintext\n POST /v1/apps/{appId}/installations/{installationId}/accessToken HTTP/1.1\n Host: sandbox.api.otto.market or api.otto.market\n Authorization: Bearer {access_token}\n Content-Type: application/x-www-form-urlencoded\n\n scope={SCOPE_VALUES}\n ```\n\n **Response:**\n\n ```json\n {\n \"access_token\": \"token\",\n \"expires_in\": 1800\n }\n ```\n\nPlease note that in step 6, the Host header should be either `sandbox.api.otto.market` or `api.otto.market`. Additionally, the Authorization header should include the value `Bearer {access_token}` obtained in step 5.\n\nYou can now use this installation access token to authenticate your requests when accessing OTTO Market APIs. Include the access token in the Authorization header with the value Bearer {access_token} for subsequent API calls.\nPlease note that once the access token expires, repeat steps 5 and 6 to obtain a new access token and installation access token respectively. Use the updated tokens for continued access to OTTO Market APIs."},"servers":[{"url":"https://api.otto.market","description":"Live Server"}],"paths":{"/v3/products":{"get":{"security":[{"bearerAuth":["products"]}],"description":"The total number of results could be limited by specifying query parameters. Generally the resulting product variations will be paginated. The default page length is 100 product variations per response, also the page size limit. The links specified in the result can be used to page through the total result space.","operationId":"Products-V3__getPartnerProducts","parameters":[{"description":"search for product variations by their sku value. Use this if your sku values contain slash ('/') or dot ('.') characters.","explode":true,"in":"query","name":"sku","required":false,"schema":{"type":"string"},"style":"form"},{"description":"search for product variations by their productReference value","explode":true,"in":"query","name":"productReference","required":false,"schema":{"type":"string"},"style":"form"},{"description":"search for product variations by their category value","explode":true,"in":"query","name":"category","required":false,"schema":{"type":"string"},"style":"form"},{"description":"search for product variations by their brandId value","explode":true,"in":"query","name":"brandId","required":false,"schema":{"type":"string"},"style":"form"},{"explode":true,"in":"query","name":"page","required":false,"schema":{"format":"int32","type":"integer"},"style":"form"},{"description":"proposed limit for the number of products per response page (at most 100)","explode":true,"in":"query","name":"limit","required":false,"schema":{"format":"int32","type":"integer"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductVariationApiResult__Products-V3"}}},"description":"successful operation"},"401":{"description":"The technical user could not be authenticated"},"403":{"description":"The technical user is not authorized to read the specified product variations. This may be the case, if the user has not the necessary role."}},"summary":"Read product variations","tags":["Products-V3"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url 'https://api.otto.market/v3/products?sku=SOME_STRING_VALUE&productReference=SOME_STRING_VALUE&category=SOME_STRING_VALUE&brandId=SOME_STRING_VALUE&page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET 'https://api.otto.market/v3/products?sku=SOME_STRING_VALUE&productReference=SOME_STRING_VALUE&category=SOME_STRING_VALUE&brandId=SOME_STRING_VALUE&page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE' \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]},"post":{"security":[{"bearerAuth":["products"]}],"description":"Returns a process-id to query results. The limit for the number of product variations in one request is 500.","operationId":"Products-V3__createOrUpdateProductVariations","parameters":[{"description":"Holds the optional client side update request timestamp, in ISO DateTime format","example":"2000-10-31T01:30:10.000-05:00","explode":false,"in":"header","name":"X-Request-Timestamp","required":false,"schema":{"format":"yyyy-MM-dd'T'HH:mm:ss.SSSXXX","type":"string"},"style":"simple"}],"requestBody":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ProductVariation__Products-V3"},"type":"array"}}}},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductProcessProgress__Products-V3"}}},"description":"The request for a modification of the specified product variations was accepted and will be executed"},"401":{"description":"The technical user could not be authenticated"},"403":{"description":"The technical user is not authorized to modify the specified product variations. This may be the case, if the user has not the necessary role."}},"summary":"Create or update product variations","tags":["Products-V3"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request POST \\\n --url https://api.otto.market/v3/products \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --header 'X-Request-Timestamp: 2000-10-31T01:30:10.000-05:00' \\\n --header 'content-type: application/json' \\\n --data '[{\"productReference\":\"UBN-11779\",\"sku\":\"3858389911564\",\"ean\":\"3858389911564\",\"pzn\":\"PZN-4908802\",\"mpn\":\"H2G2-42\",\"moin\":\"M00A1234BC\",\"releaseDate\":\"2019-10-19T00:00:00Z\",\"productDescription\":{\"category\":\"Outdoorjacke\",\"brandId\":\"CMWBBRW2\",\"productLine\":\"501\",\"manufacturer\":\"3M\",\"productionDate\":\"2021-07-02T09:30:52.093Z\",\"multiPack\":true,\"bundle\":false,\"fscCertified\":true,\"disposal\":false,\"productUrl\":\"http://myproduct.somewhere.com/productname/\",\"description\":\"

Some example words...in bold...some more

\",\"bulletPoints\":[\"My top key information...\"],\"attributes\":[{\"name\":\"Bundweite\",\"values\":[\"34\"],\"additional\":false}]},\"mediaAssets\":[{\"type\":\"IMAGE\",\"location\":\"http://apartners.url/image-location\"}],\"order\":{\"maxOrderQuantity\":{\"quantity\":10,\"periodInDays\":7}},\"pricing\":{\"standardPrice\":{\"amount\":19.95,\"currency\":\"EUR\"},\"vat\":\"FULL\",\"msrp\":{\"amount\":19.95,\"currency\":\"EUR\"},\"sale\":{\"salePrice\":{\"amount\":19.95,\"currency\":\"EUR\"},\"startDate\":\"2019-10-19T09:30:00Z\",\"endDate\":\"2019-10-19T09:30:00Z\"},\"normPriceInfo\":{\"normAmount\":100,\"normUnit\":\"g\",\"salesAmount\":500,\"salesUnit\":\"g\"}},\"logistics\":{\"packingUnitCount\":3,\"packingUnits\":[{\"weight\":365,\"width\":600,\"height\":200,\"length\":300}]},\"productSafety\":{\"name\":\"Die Musterfirma GmbH\",\"address\":\"Musterstraße 1, 12345, Musterstadt, Deutschland\",\"regionCode\":\"DE\",\"email\":\"info@die-musterfirma.de\",\"url\":\"https://musterfirma/kontakt-information\",\"phone\":\"+ 49 40 123456789\"}}]' | \\\n http POST https://api.otto.market/v4/products \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN' \\\n X-Request-Timestamp:2000-10-31T01:30:10.000-05:00 \\\n content-type:application/json"}]}},"/v4/products/active-status":{"get":{"security":[{"bearerAuth":["products"]}],"description":"The total number of results could be limited by specifying query parameters. Generally the resulting active status values will be paginated. The default page length is 100 active status entries per response, also the page size limit. The links specified in the result can be used to page through the total result space.","operationId":"Products-V4__getActiveStatus","parameters":[{"description":"search for product variations by their sku value. Use this if your sku values contain slash ('/') or dot ('.') characters.","explode":true,"in":"query","name":"sku","required":false,"schema":{"type":"string"},"style":"form"},{"description":"search for product variations by their productReference value","explode":true,"in":"query","name":"productReference","required":false,"schema":{"type":"string"},"style":"form"},{"description":"search for product variations by their category value","explode":true,"in":"query","name":"category","required":false,"schema":{"type":"string"},"style":"form"},{"description":"search for product variations by their brand ID value","explode":true,"in":"query","name":"brandId","required":false,"schema":{"type":"string"},"style":"form"},{"explode":true,"in":"query","name":"page","required":false,"schema":{"format":"int32","type":"integer"},"style":"form"},{"description":"proposed limit for the number of active status values per response page (at most 100)","explode":true,"in":"query","name":"limit","required":false,"schema":{"format":"int32","type":"integer"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActiveStatusListResponse__Products-V4"}}},"description":"successful operation"},"401":{"description":"The technical user could not be authenticated"},"403":{"description":"The technical user is not authorized to read the active status of the specified product variations. This may be the case, if the user has not the necessary role."}},"summary":"Read active status","tags":["Products-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url 'https://api.otto.market/v4/products/active-status?sku=SOME_STRING_VALUE&productReference=SOME_STRING_VALUE&category=SOME_STRING_VALUE&brandId=SOME_STRING_VALUE&page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET 'https://api.otto.market/v4/products/active-status?sku=SOME_STRING_VALUE&productReference=SOME_STRING_VALUE&category=SOME_STRING_VALUE&brandId=SOME_STRING_VALUE&page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE' \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]},"post":{"security":[{"bearerAuth":["products"]}],"description":"Returns a process-id to query results. The limit for the number of product active statuses in one request is 500.","operationId":"Products-V4__updateActiveStatus","parameters":[{"description":"Holds the optional client side update request timestamp, in ISO DateTime format","example":"2000-10-31T01:30:10.000-05:00","explode":false,"in":"header","name":"X-Request-Timestamp","required":false,"schema":{"format":"yyyy-MM-dd'T'HH:mm:ss.SSSXXX","type":"string"},"style":"simple"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActiveStatusListRequest__Products-V4"}}}},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductProcessProgress__Products-V4"}}},"description":"The request for a modification of the active status of the specified product variation was accepted and will be executed"},"400":{"description":"The request body is no valid JSON document"},"401":{"description":"The technical user could not be authenticated"},"403":{"description":"The technical user is not authorized to modify the active status of the specified product variations. This may be the case, if the user has not the necessary role."}},"summary":"Update active status","tags":["Products-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request POST \\\n --url https://api.otto.market/v4/products/active-status \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --header 'X-Request-Timestamp: 2000-10-31T01:30:10.000-05:00' \\\n --header 'content-type: application/json' \\\n --data '{\"status\":[{\"sku\":\"82388894-5883-488\",\"active\":true}]}'"},{"lang":"Shell + Httpie","source":"echo '{\"status\":[{\"sku\":\"82388894-5883-488\",\"active\":true}]}' | \\\n http POST https://api.otto.market/v4/products/active-status \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN' \\\n X-Request-Timestamp:2000-10-31T01:30:10.000-05:00 \\\n content-type:application/json"}]}},"/v4/products/brands":{"get":{"security":[{"bearerAuth":["products"]}],"parameters":[{"$ref":"#/components/parameters/If-Match"},{"$ref":"#/components/parameters/If-None-Match"},{"$ref":"#/components/parameters/If-Modified-Since"},{"$ref":"#/components/parameters/If-Unmodified-Since"},{"explode":true,"in":"query","name":"page","required":false,"schema":{"format":"int32","type":"integer"},"style":"form"},{"explode":true,"in":"query","name":"limit","required":false,"schema":{"format":"int32","type":"integer"},"style":"form"}],"description":"Read the list of brands that are known on the Otto market place. The list of brands will be paginated. Brands consist of a name, a brand Id, a (link to a) logo and a boolean useable that lets you know wheter you are allowed to set up variants with this brand on the Otto Marketplace. The default page length is 100 entries per response, the page size upper limit is 1000. The links specified in the result can be used to page through the total result space. Note that there will be no prev link on the first page and no next link on the last page.","operationId":"Products-V4__getBrands","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandListResponse__Products-V4"}}},"headers":{"ETag":{"$ref":"#/components/headers/ETag"},"Last-Modified":{"$ref":"#/components/headers/Last-Modified"}},"description":"successful operation"},"401":{"description":"The technical user could not be authenticated"},"403":{"description":"The technical user is not authorized to read a list of known brands. This may be the case, if the user has not the necessary role."}},"summary":"List of allowed brands","tags":["Products-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url 'https://api.otto.market/v4/products/brands?page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --header 'If-Match: 7da7a728f910' \\\n --header 'If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT' \\\n --header 'If-None-Match: 7da7a728f910' \\\n --header 'If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT'"},{"lang":"Shell + Httpie","source":"http GET 'https://api.otto.market/v4/products/brands?page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE' \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN' \\\n If-Match:7da7a728f910 \\\n If-Modified-Since:'Sat, 29 Oct 1994 19:43:31 GMT' \\\n If-None-Match:7da7a728f910 \\\n If-Unmodified-Since:'Sat, 29 Oct 1994 19:43:31 GMT'"}]}},"/v4/products/categories":{"get":{"security":[{"bearerAuth":["products"]}],"description":"Returns product categories and associated attributes of the OTTO market place. The total number of results could be limited by specifying query parameters. Generally the resulting product categories values will be paginated. The default page length is 100 product categories per response, the page size limit is 2000. The links specified in the result can be used to page through the total result space.","operationId":"Products-V4__getCategoryGroups","parameters":[{"description":"the number (starting with 0) of the page, that should be delivered.","explode":true,"in":"query","name":"page","required":false,"schema":{"format":"int32","type":"integer"},"style":"form"},{"description":"proposed limit for the number of product categories per response page (at most 2000)","explode":true,"in":"query","name":"limit","required":false,"schema":{"format":"int32","type":"integer"},"style":"form"},{"description":"read a single category","explode":true,"in":"query","name":"category","required":false,"schema":{"type":"string"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryGroups__Products-V4"}}},"description":"successful operation"},"401":{"description":"The technical user could not be authenticated"},"403":{"description":"The technical user is not authorized to read the product categories. This may be the case, if the user has not the necessary role."},"404":{"description":"The category could not be found."}},"summary":"Read product categories","tags":["Products-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url 'https://api.otto.market/v4/products/categories?page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE&category=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET 'https://api.otto.market/v4/products/categories?page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE&category=SOME_STRING_VALUE' \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v4/products/content-changes":{"get":{"security":[{"bearerAuth":["products"]}],"description":"Read the content changes for all your product variations within a specific time period. You can also use this endpoint to read the content changes for more than one variation or if the sku value contains slash ('/') or dot ('.') characters, so that you cannot use the other endpoint with one dedicated sku value in the path. The resulting content changes will be paginated. The default page length is 100 entries per response, which also is the page size upper limit. The links specified in the result can be used to page through the total result space.","operationId":"Products-V4__getContentChanges2","parameters":[{"description":"search for product variations by their sku value. Use this to query for multiple variations or if your sku values contain slash ('/') or dot ('.') characters. You may separate multiple sku values by comma or state each one with a &sku= in front of the value. Please note that if you like to query for a single variation whose value contains a comma you have to add one empty &sku= at the end of the query string or use the other endpoint.","explode":true,"in":"query","name":"sku","required":false,"schema":{"items":{"type":"string"},"type":"array"},"style":"form"},{"description":"search for content changes from this time on. The maxmimum and default value is 28 days before now. Future values can be specified, but lead to an empty result.","explode":true,"in":"query","name":"fromDate","required":false,"schema":{"format":"date-time","type":"string"},"style":"form"},{"explode":true,"in":"query","name":"page","required":false,"schema":{"format":"int32","type":"integer"},"style":"form"},{"description":"proposed limit for the number of content changes per response page (at most 100)","explode":true,"in":"query","name":"limit","required":false,"schema":{"format":"int32","type":"integer"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentChangesApiResult__Products-V4"}}},"description":"successful operation"},"401":{"description":"The technical user could not be authenticated"},"403":{"description":"The technical user is not authorized to read content changes of the specified product variations. This may be the case, if the user has not the necessary role."},"404":{"description":"The product variation with the specified sku value could not be found."}},"summary":"Read content changes within time period","tags":["Products-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url 'https://api.otto.market/v4/products/content-changes?sku=SOME_ARRAY_VALUE&fromDate=SOME_STRING_VALUE&page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET 'https://api.otto.market/v4/products/content-changes?sku=SOME_ARRAY_VALUE&fromDate=SOME_STRING_VALUE&page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE' \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v4/products/marketplace-status":{"get":{"security":[{"bearerAuth":["products"]}],"description":"The total number of results could be limited by specifying query parameters. Generally the resulting marketplace status will be paginated. The default page length is 100 product variations per response, also the page size limit. The links specified in the result can be used to page through the total result space.","operationId":"Products-V4__getMarketPlaceStatusList","parameters":[{"description":"search for product variations by their sku value. Use this if your sku values contain slash ('/') or dot ('.') characters.","explode":true,"in":"query","name":"sku","required":false,"schema":{"type":"string"},"style":"form"},{"description":"search marketplace status by the productReference value of the related product variations","explode":true,"in":"query","name":"productReference","required":false,"schema":{"type":"string"},"style":"form"},{"description":"search marketplace status by the category value of the related product variations","explode":true,"in":"query","name":"category","required":false,"schema":{"type":"string"},"style":"form"},{"description":"search marketplace status by the brand ID value of the related product variations","explode":true,"in":"query","name":"brandId","required":false,"schema":{"type":"string"},"style":"form"},{"description":"search marketplace status for a time range starting with the given date (in ISO8601, like '2021-10-09T07:52:19.820Z' or '2021-10-09T07:52:19.820+01:00')","explode":true,"in":"query","name":"fromDate","required":false,"schema":{"format":"date-time","type":"string"},"style":"form"},{"description":"page to load","explode":true,"in":"query","name":"page","required":false,"schema":{"format":"int32","type":"integer"},"style":"form"},{"description":"proposed limit for the number of marketplace status per response page (at most 1000)","explode":true,"in":"query","name":"limit","required":false,"schema":{"format":"int32","type":"integer"},"style":"form"},{"description":"only include items that match any of the provided status","explode":true,"in":"query","name":"marketPlaceStatus","required":false,"schema":{"items":{"enum":["PENDING","ONLINE","RESTRICTED","REJECTED","INACTIVE"],"type":"string"},"type":"array"},"style":"form"},{"description":"Define the sort order of the resulting entries. Available values are 'desc' for 'newest lastModified first' and 'asc' for 'oldest lastModified first' - default is 'desc'","explode":true,"in":"query","name":"sort-order","required":false,"schema":{"enum":["desc","asc"],"type":"string"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketPlaceStatusApiResult__Products-V4"}}},"description":"successful operation"},"304":{"description":"The request included an If-Modified-Since header, but the resource has not been modified since the specified date."},"401":{"description":"The technical user could not be authenticated"},"403":{"description":"The technical user is not authorized to read the specified marketplace status. This may be the case, if the user has not the necessary role."}},"summary":"Read marketplace status of product variations","tags":["Products-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url 'https://api.otto.market/v4/products/marketplace-status?sku=SOME_STRING_VALUE&productReference=SOME_STRING_VALUE&category=SOME_STRING_VALUE&brandId=SOME_STRING_VALUE&fromDate=SOME_STRING_VALUE&page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE&marketPlaceStatus=SOME_ARRAY_VALUE&sort-order=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET 'https://api.otto.market/v4/products/marketplace-status?sku=SOME_STRING_VALUE&productReference=SOME_STRING_VALUE&category=SOME_STRING_VALUE&brandId=SOME_STRING_VALUE&fromDate=SOME_STRING_VALUE&page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE&marketPlaceStatus=SOME_ARRAY_VALUE&sort-order=SOME_STRING_VALUE' \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v4/products/prices":{"get":{"security":[{"bearerAuth":["products"]}],"description":"Read your product variations prices. The total number of results could be limited by specifying query parameters. Generally the resulting product variations will be paginated. The default page length is 100 product variations per response, also the page size limit. The links specified in the result can be used to page through the total result space.","operationId":"Products-V4__getProductVariationPrices","parameters":[{"description":"search for product variations by their sku value. Use this if your sku values contain slash ('/') or dot ('.') characters.","explode":true,"in":"query","name":"sku","required":false,"schema":{"type":"string"},"style":"form"},{"description":"search for product variations by their productReference value","explode":true,"in":"query","name":"productReference","required":false,"schema":{"type":"string"},"style":"form"},{"description":"search for product variations by their category value","explode":true,"in":"query","name":"category","required":false,"schema":{"type":"string"},"style":"form"},{"description":"search for product variations by their ID value","explode":true,"in":"query","name":"brandId","required":false,"schema":{"type":"string"},"style":"form"},{"explode":true,"in":"query","name":"page","required":false,"schema":{"format":"int32","type":"integer"},"style":"form"},{"description":"proposed limit for the number of products per response page (at most 100)","explode":true,"in":"query","name":"limit","required":false,"schema":{"format":"int32","type":"integer"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceApiResult__Products-V4"}}},"description":"successful operation"},"401":{"description":"The technical user could not be authenticated"},"403":{"description":"The technical user is not authorized to read the specified product variations prices. This may be the case, if the user has not the necessary role."}},"summary":"Read product variations prices","tags":["Products-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url 'https://api.otto.market/v4/products/prices?sku=SOME_STRING_VALUE&productReference=SOME_STRING_VALUE&category=SOME_STRING_VALUE&brandId=SOME_STRING_VALUE&page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET 'https://api.otto.market/v4/products/prices?sku=SOME_STRING_VALUE&productReference=SOME_STRING_VALUE&category=SOME_STRING_VALUE&brandId=SOME_STRING_VALUE&page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE' \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]},"post":{"security":[{"bearerAuth":["products"]}],"description":"Update your product variation prices and get a process-id to query results. The limit for the number of product variation prices in one request is 500.","operationId":"Products-V4__updateProductVariationPrices","parameters":[{"description":"Holds the optional client side update request timestamp, in ISO DateTime format","example":"2000-10-31T01:30:10.000-05:00","explode":false,"in":"header","name":"X-Request-Timestamp","required":false,"schema":{"format":"yyyy-MM-dd'T'HH:mm:ss.SSSXXX","type":"string"},"style":"simple"}],"requestBody":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/SkuPricing__Products-V4"},"type":"array"}}}},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductProcessProgress__Products-V4"}}},"description":"The request for a modification of the specified product variation prices was accepted and will be executed"},"401":{"description":"The technical user could not be authenticated"},"403":{"description":"The technical user is not authorized to modify the specified product variation prices. This may be the case, if the user has not the necessary role."}},"summary":"Update product variation prices","tags":["Products-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request POST \\\n --url https://api.otto.market/v4/products/prices \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --header 'X-Request-Timestamp: 2000-10-31T01:30:10.000-05:00' \\\n --header 'content-type: application/json' \\\n --data '[{\"sku\":\"string\",\"standardPrice\":{\"amount\":19.95,\"currency\":\"EUR\"},\"sale\":{\"salePrice\":{\"amount\":19.95,\"currency\":\"EUR\"},\"startDate\":\"2019-10-19T09:30:00Z\",\"endDate\":\"2019-10-19T09:30:00Z\"}}]'"},{"lang":"Shell + Httpie","source":"echo '[{\"sku\":\"string\",\"standardPrice\":{\"amount\":19.95,\"currency\":\"EUR\"},\"sale\":{\"salePrice\":{\"amount\":19.95,\"currency\":\"EUR\"},\"startDate\":\"2019-10-19T09:30:00Z\",\"endDate\":\"2019-10-19T09:30:00Z\"}}]' | \\\n http POST https://api.otto.market/v4/products/prices \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN' \\\n X-Request-Timestamp:2000-10-31T01:30:10.000-05:00 \\\n content-type:application/json"}]}},"/v4/products/update-tasks/{processUuid}":{"get":{"security":[{"bearerAuth":["products"]}],"description":"The response will contain the links for the different parts of the result: products successfully created or updated, products with failures, products which did not contain any changes compared to the last sent version.","operationId":"Products-V4__progressByProcessId","parameters":[{"description":"search for a product data delivery result by its processUuid.","explode":false,"in":"path","name":"processUuid","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductProcessProgress__Products-V4"}}},"description":"successful operation"},"401":{"description":"The technical user could not be authenticated"},"403":{"description":"The technical user is not authorized to read the specified product variations. This may be the case, if the user has not the necessary role."},"404":{"description":"The product data delivery results with the specified processUuid value could not be found."}},"summary":"Request the results of a product data delivery","tags":["Products-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url https://api.otto.market/v4/products/update-tasks/%7BprocessUuid%7D \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET https://api.otto.market/v4/products/update-tasks/%7BprocessUuid%7D \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v4/products/update-tasks/{processUuid}/failed":{"get":{"security":[{"bearerAuth":["products"]}],"description":"Request the failed products of the product data delivery with the linked processUuid. The response will contain a list of failed products with associated error details.","operationId":"Products-V4__failedByProcessId","parameters":[{"description":"search for the failed products of a product data delivery identified by its processUuid.","explode":false,"in":"path","name":"processUuid","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductProcessResult__Products-V4"}}},"description":"successful operation"},"401":{"description":"The technical user could not be authenticated"},"403":{"description":"The technical user is not authorized to read the specified product variations. This may be the case, if the user has not the necessary role."},"404":{"description":"The product data delivery results with the specified processUuid value could not be found."}},"summary":"List failed products of a product data delivery","tags":["Products-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url https://api.otto.market/v4/products/update-tasks/%7BprocessUuid%7D/failed \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET https://api.otto.market/v4/products/update-tasks/%7BprocessUuid%7D/failed \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v4/products/update-tasks/{processUuid}/succeeded":{"get":{"security":[{"bearerAuth":["products"]}],"description":"Request the succeeded products of the product data delivery with the linked processUuid. The response will contain a list of successfully delivered products.","operationId":"Products-V4__succeededByProcessId","parameters":[{"description":"search for the succeeded products of a product data delivery identified by its processUuid.","explode":false,"in":"path","name":"processUuid","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductProcessResult__Products-V4"}}},"description":"successful operation"},"401":{"description":"The technical user could not be authenticated"},"403":{"description":"The technical user is not authorized to read the specified product variations. This may be the case, if the user has not the necessary role."},"404":{"description":"The product data delivery results with the specified processUuid value could not be found."}},"summary":"List succeeded products of a product data delivery","tags":["Products-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url https://api.otto.market/v4/products/update-tasks/%7BprocessUuid%7D/succeeded \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET https://api.otto.market/v4/products/update-tasks/%7BprocessUuid%7D/succeeded \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v4/products/update-tasks/{processUuid}/unchanged":{"get":{"security":[{"bearerAuth":["products"]}],"description":"Request the unchanged products of the product data delivery with the linked processUuid. The response will contain a list of unchanged products.","operationId":"Products-V4__unchangedByProcessId","parameters":[{"description":"search for the unchanged products of a product data delivery identified by its processUuid.","explode":false,"in":"path","name":"processUuid","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductProcessResult__Products-V4"}}},"description":"successful operation"},"401":{"description":"The technical user could not be authenticated"},"403":{"description":"The technical user is not authorized to read the specified product variations. This may be the case, if the user has not the necessary role."},"404":{"description":"The product data delivery results with the specified processUuid value could not be found."}},"summary":"List unchanged products of a product data delivery","tags":["Products-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url https://api.otto.market/v4/products/update-tasks/%7BprocessUuid%7D/unchanged \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET https://api.otto.market/v4/products/update-tasks/%7BprocessUuid%7D/unchanged \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v4/products/{sku}":{"get":{"security":[{"bearerAuth":["products"]}],"description":"Returns a single product variation by SKU.","operationId":"Products-V4__getProductVariation","parameters":[{"description":"search for a product variation by its SKU value","explode":false,"in":"path","name":"sku","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductVariation__Products-V4"}}},"description":"successful operation"},"401":{"description":"The technical user could not be authenticated"},"403":{"description":"The technical user is not authorized to read the specified product variations. This may be the case, if the user has not the necessary role."},"404":{"description":"The product variation with the specified sku value could not be found."}},"summary":"Read a single product variation","tags":["Products-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url https://api.otto.market/v4/products/%7Bsku%7D \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET https://api.otto.market/v4/products/%7Bsku%7D \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v4/products/{sku}/active-status":{"get":{"security":[{"bearerAuth":["products"]}],"description":"Returns active status of the requested product variation by SKU.","operationId":"Products-V4__getVariationActiveStatus","parameters":[{"description":"search for a product variation by its SKU value","explode":false,"in":"path","name":"sku","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActiveStatus__Products-V4"}}},"description":"successful operation"},"401":{"description":"The technical user could not be authenticated"},"403":{"description":"The technical user is not authorized to read the active status of the specified product variations. This may be the case, if the user has not the necessary role."},"404":{"description":"The product variation with the specified sku value could not be found."}},"summary":"Read the active status of a single product variation","tags":["Products-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url https://api.otto.market/v4/products/%7Bsku%7D/active-status \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET https://api.otto.market/v4/products/%7Bsku%7D/active-status \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v4/products/{sku}/content-changes":{"get":{"security":[{"bearerAuth":["products"]}],"description":"Returns the content changes info for a single product variation within a specific time period. The resulting content changes will be paginated. The default page length is 100 entries per response, also the page size limit. The links specified in the result can be used to page through the total result space.","operationId":"Products-V4__getContentChanges","parameters":[{"description":"search for a product variation by its SKU value","explode":false,"in":"path","name":"sku","required":true,"schema":{"type":"string"},"style":"simple"},{"description":"search for content changes from this ISO8601 date on. The maxmimum and default value is 28 days before now. Future values can be specified, but lead to an empty result.","explode":true,"in":"query","name":"fromDate","required":false,"schema":{"format":"date-time","type":"string"},"style":"form"},{"explode":true,"in":"query","name":"page","required":false,"schema":{"format":"int32","type":"integer"},"style":"form"},{"description":"proposed limit for the number of entries per response page (at most 100)","explode":true,"in":"query","name":"limit","required":false,"schema":{"format":"int32","type":"integer"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentChangesApiResult__Products-V4"}}},"description":"successful operation"},"401":{"description":"The technical user could not be authenticated"},"403":{"description":"The technical user is not authorized to read the content changes of the specified product variations. This may be the case, if the user has not the necessary role."},"404":{"description":"The product variation with the specified sku value could not be found."}},"summary":"Read content changes for a single product variation","tags":["Products-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url 'https://api.otto.market/v4/products/%7Bsku%7D/content-changes?fromDate=SOME_STRING_VALUE&page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET 'https://api.otto.market/v4/products/%7Bsku%7D/content-changes?fromDate=SOME_STRING_VALUE&page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE' \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v4/products/{sku}/marketplace-status":{"get":{"security":[{"bearerAuth":["products"]}],"description":"Returns marketplace status for a single product variation by SKU.","operationId":"Products-V4__getMarketPlaceStatus","parameters":[{"description":"search for a marketplace status by its SKU value","explode":false,"in":"path","name":"sku","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketPlaceStatus__Products-V4"}}},"description":"successful operation"},"401":{"description":"The technical user could not be authenticated"},"403":{"description":"The technical user is not authorized to read the specified marketplace status. This may be the case, if the user has not the necessary role."},"404":{"description":"The product variation with the specified sku value could not be found."}},"summary":"Read marketplace status for a single product variation","tags":["Products-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url https://api.otto.market/v4/products/%7Bsku%7D/marketplace-status \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET https://api.otto.market/v4/products/%7Bsku%7D/marketplace-status \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v4/products/{sku}/prices":{"get":{"security":[{"bearerAuth":["products"]}],"description":"Read the price data of a single product variation.","operationId":"Products-V4__getProductVariationPrice","parameters":[{"description":"search for a product variation by its SKU value","explode":false,"in":"path","name":"sku","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkuPricing__Products-V4"}}},"description":"successful operation"},"401":{"description":"The technical user could not be authenticated"},"403":{"description":"The technical user is not authorized to read the specified product variations. This may be the case, if the user has not the necessary role."},"404":{"description":"The product variation with the specified sku value could not be found."}},"summary":"Read a single product variation price","tags":["Products-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url https://api.otto.market/v4/products/%7Bsku%7D/prices \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET https://api.otto.market/v4/products/%7Bsku%7D/prices \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v4/orders":{"get":{"description":"Retrieve orders sorted by order date from oldest to newest. The number of returned orders is limited to 128; cursor based pagination is supported.","operationId":"Orders-V4__findPartnerOrders","parameters":[{"description":"Defines earliest change date (ISO 8601) the returned orders should have","example":"2019-08-01T01:00:00+02:00","in":"query","name":"fromDate","required":false,"schema":{"type":"string"}},{"description":"Only orders newer than the date specified (ISO 8601) will be returned","example":"2020-07-01T00:00:00+02:00","in":"query","name":"fromOrderDate","required":false,"schema":{"type":"string"}},{"description":"Only orders older than the date specified (ISO 8601) will be returned","example":"2020-07-01T23:59:59+02:00","in":"query","name":"toOrderDate","required":false,"schema":{"type":"string"}},{"description":"
ANNOUNCED: Orders with at least one position item in state ANNOUNCED
PROCESSABLE: Orders with at least one position item in state PROCESSABLE and none in ANNOUNCED
SENT: Orders with at least one position item in state SENT and none in either ANNOUNCED or PROCESSABLE
RETURNED: Orders with at least one position item in state RETURNED and none in either ANNOUNCED, PROCESSABLE, or SENT
CANCELLED_BY_PARTNER: Orders with at least one position item in state CANCELLED_BY_PARTNER
CANCELLED_BY_MARKETPLACE: Orders with at least one position item in state CANCELLED_BY_MARKETPLACE

If no state is provided, orders in all possible states are returned.
Several values can be passed; it will return a combination of these states without duplicates.
Also see parameter 'mode'.","example":"PROCESSABLE&fulfillmentStatus=CANCELLED_BY_MARKETPLACE","in":"query","name":"fulfillmentStatus","required":false,"schema":{"type":"string","enum":["ANNOUNCED","PROCESSABLE","SENT","RETURNED","CANCELLED_BY_PARTNER","CANCELLED_BY_MARKETPLACE"]},"style":"form"},{"description":"The maximum amount of orders to return","in":"query","name":"limit","required":false,"schema":{"type":"integer","format":"int32","default":128}},{"description":"Sort result by 'orderColumnType' in ASCending or DESCending order","in":"query","name":"orderDirection","required":false,"schema":{"type":"string","default":"ASC","enum":["ASC","DESC"]}},{"description":"The column on which to apply 'orderDirection' parameter","in":"query","name":"orderColumnType","required":false,"schema":{"type":"string","default":"ORDER_LIFECYCLE_DATE","enum":["ORDER_DATE","ORDER_LIFECYCLE_DATE","LAST_MODIFIED_DATE","EXPECTED_DELIVERY_DATE"]}},{"description":"In search mode AT_LEAST_ONE orders with at least one position item in given 'fulfillmentStatus' will always be returned","in":"query","name":"mode","required":false,"schema":{"type":"string","default":"BUCKET","enum":["BUCKET","AT_LEAST_ONE"]}},{"description":"Cursor for paging requests. If a next cursor is provided, the only other request parameter being considered is 'limit'

Note: Only the cursor string is required - not the whole link","example":"eyJmZiI6MTU5NDg5NDQ3MTA1OCwicGlmIjoiNDcxM","in":"query","name":"nextcursor","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"examples":{"List of orders":{"description":"List of orders","summary":"List of orders","value":{"resources":[{"salesOrderId":"8bd8a7cb-1ce1-4024-bdec-1c60de3c8006","orderNumber":"bwvdp9gcyk","orderDate":"2021-03-31T09:45:52.313+0000","lastModifiedDate":"2021-03-31T10:30:52.434+0000","positionItems":[{"positionItemId":"41d73c45-6177-4230-8907-4ffafd09064e","fulfillmentStatus":"ANNOUNCED","dealName":"Deal der Woche 52","dealId":"b65ef4bc-8f28-4fdd-a14a-b30b98449698","itemValueGrossPrice":{"amount":13.37,"currency":"EUR"},"product":{"sku":"P4567","productTitle":"Red T-Shirt","articleNumber":"X2G1D12FT8","ean":"4606938545083","vatRate":19}}],"orderLifecycleInformation":{"lifecycleChangeDate":"2021-03-31T10:30:52.433+0000"},"payment":{"paymentMethod":"PREPAYMENT"},"initialDeliveryFees":[{"name":"DELIVERY_FEE_STANDARD","deliveryFeeAmount":{"amount":5.95,"currency":"EUR"},"positionItemIds":["41d73c45-6177-4230-8907-4ffafd09064e"],"vatRate":19}],"links":[{"rel":"self","href":"/v4/orders/8bd8a7cb-1ce1-4024-bdec-1c60de3c8006"}]},{"salesOrderId":"02807492-35b8-46a1-9493-ac34ba006da0","orderNumber":"cwvcp4gvyy","orderDate":"2021-04-15T12:19:49.007+0000","lastModifiedDate":"2021-04-15T13:04:51.121+0000","positionItems":[{"positionItemId":"50606ce0-fb36-47af-b5f2-30e18da115b4","fulfillmentStatus":"ANNOUNCED","itemValueGrossPrice":{"amount":11.49,"currency":"EUR"},"product":{"sku":"T7781","productTitle":"Blue Socks","articleNumber":"Y7G1D73GH1","vatRate":19}}],"orderLifecycleInformation":{"lifecycleChangeDate":"2021-04-15T13:04:51.112+0000"},"payment":{"paymentMethod":"PREPAYMENT"},"initialDeliveryFees":[{"name":"DELIVERY_FEE_STANDARD","deliveryFeeAmount":{"amount":5.95,"currency":"EUR"},"positionItemIds":["50606ce0-fb36-47af-b5f2-30e18da115b4"],"vatRate":19}],"links":[{"rel":"self","href":"/v4/orders/02807492-35b8-46a1-9493-ac34ba006da0"}]}],"links":[{"rel":"next","href":"/v4/orders?nextcursor=QlVDS0VUOjE1NjgyMjAwNDg2MTM6NDcxMTpBTk5PVU5DRUQ6&limit=128"}]}}},"schema":{"$ref":"#/components/schemas/PartnerOrderList__Orders-V4"}}},"description":"Successfully retrieved sales orders"},"400":{"content":{"application/json":{"examples":{"Bad request":{"description":"Bad request","summary":"Response for invalid requests","value":{"errors":[{"path":"/v4/orders/...","title":"Bad Request","detail":"Cannot parse request - please check query parameters and/or body"}]}}}}},"description":"Request is invalid"},"401":{"content":{"application/json":{"examples":{"Auth failed":{"description":"Auth failed","summary":"Response for invalid credentials","value":{"errors":[{"path":"/v4/orders/...","title":"Unauthorized","detail":"No proper credentials were provided"}]}}}}},"description":"Authentication failed"},"403":{"content":{"application/json":{"examples":{"Authorization missing":{"description":"Authorization missing","summary":"Response for missing access role rights","value":{"errors":[{"path":"/v4/orders/...","title":"Forbidden","detail":"No permission to access specified resource(s)"}]}}}}},"description":"Forbidden"}},"security":[{"bearerAuth":["orders"]}],"summary":"List of orders filtered by fulfillment state","tags":["Orders-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url 'https://api.otto.market/v4/orders?fromDate=2019-08-01T01%3A00%3A00%2B02%3A00&fromOrderDate=2020-07-01T00%3A00%3A00%2B02%3A00&toOrderDate=2020-07-01T23%3A59%3A59%2B02%3A00&fulfillmentStatus=PROCESSABLE%26fulfillmentStatus%3DCANCELLED_BY_MARKETPLACE&limit=SOME_INTEGER_VALUE&orderDirection=SOME_STRING_VALUE&orderColumnType=SOME_STRING_VALUE&mode=SOME_STRING_VALUE&nextcursor=eyJmZiI6MTU5NDg5NDQ3MTA1OCwicGlmIjoiNDcxM' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET 'https://api.otto.market/v4/orders?fromDate=2019-08-01T01%3A00%3A00%2B02%3A00&fromOrderDate=2020-07-01T00%3A00%3A00%2B02%3A00&toOrderDate=2020-07-01T23%3A59%3A59%2B02%3A00&fulfillmentStatus=PROCESSABLE%26fulfillmentStatus%3DCANCELLED_BY_MARKETPLACE&limit=SOME_INTEGER_VALUE&orderDirection=SOME_STRING_VALUE&orderColumnType=SOME_STRING_VALUE&mode=SOME_STRING_VALUE&nextcursor=eyJmZiI6MTU5NDg5NDQ3MTA1OCwicGlmIjoiNDcxM' \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v4/orders/{orderNumber}":{"get":{"description":"Fetch a single order by its unique order number.","operationId":"Orders-V4__getPartnerOrderByOrderNumber","parameters":[{"in":"path","name":"orderNumber","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"examples":{"Announced order":{"description":"Announced order","summary":"An order in state ANNOUNCED","value":{"salesOrderId":"8bd8a7cb-1ce1-4024-bdec-1c60de3c8006","orderNumber":"bwvdp9gcyk","orderDate":"2021-03-31T09:45:52.313+0000","lastModifiedDate":"2021-03-31T10:30:52.434+0000","positionItems":[{"positionItemId":"41d73c45-6177-4230-8907-4ffafd09064e","fulfillmentStatus":"ANNOUNCED","dealName":"Deal der Woche 52","dealId":"b65ef4bc-8f28-4fdd-a14a-b30b98449698","itemValueGrossPrice":{"amount":13.37,"currency":"EUR"},"product":{"sku":"P4567","productTitle":"Red T-Shirt","articleNumber":"X2G1D12FT8","ean":"4606938545083","vatRate":19}}],"orderLifecycleInformation":{"lifecycleChangeDate":"2021-03-31T10:30:52.433+0000"},"payment":{"paymentMethod":"PREPAYMENT"},"initialDeliveryFees":[{"name":"DELIVERY_FEE_STANDARD","deliveryFeeAmount":{"amount":5.95,"currency":"EUR"},"positionItemIds":["41d73c45-6177-4230-8907-4ffafd09064e"],"vatRate":19}],"links":[{"rel":"self","href":"/v4/orders/8bd8a7cb-1ce1-4024-bdec-1c60de3c8006"}]}},"Processable order":{"description":"Processable order","summary":"An order in state PROCESSABLE","value":{"salesOrderId":"a24c37c0-768f-44e6-9f5c-1e4430d4ab32","orderNumber":"bwqwz7s8cx","orderDate":"2021-04-16T05:59:01.255+0000","lastModifiedDate":"2021-04-16T06:44:02.249+0000","positionItems":[{"positionItemId":"8a88e387-a03d-4cc9-99d9-3de6a5c038bd","fulfillmentStatus":"PROCESSABLE","dealName":"Deal der Woche 52","dealId":"b65ef4bc-8f28-4fdd-a14a-b30b98449698","expectedDeliveryDate":"2021-04-21T12:00:00.000+02:00","itemValueGrossPrice":{"amount":23.95,"currency":"EUR"},"product":{"sku":"V0533","productTitle":"White Shirt","articleNumber":"1563237W3","vatRate":19}},{"positionItemId":"43111eca-18e5-4fe4-846c-2009d3643495","fulfillmentStatus":"CANCELLED_BY_PARTNER","dealName":"Deal der Woche 52","dealId":"b65ef4bc-8f28-4fdd-a14a-b30b98449698","expectedDeliveryDate":"2021-04-21T12:00:00.000+02:00","cancellationReason":"CANCELLED_ON_PARTNER_WISH","itemValueGrossPrice":{"amount":99.2,"currency":"EUR"},"product":{"sku":"A7567","productTitle":"Black Jeans","articleNumber":"333207J4","vatRate":19}},{"positionItemId":"e4b96f70-495a-423c-877e-8886b5532ba4","fulfillmentStatus":"PROCESSABLE","expectedDeliveryDate":"2021-04-24T12:00:00.000+02:00","itemValueGrossPrice":{"amount":15.7,"currency":"EUR"},"product":{"sku":"L8456","productTitle":"Red Socks","articleNumber":"4561237P3","vatRate":19}}],"orderLifecycleInformation":{"lifecycleChangeDate":"2021-04-16T06:44:02.249+0000"},"payment":{"paymentMethod":"PREPAYMENT"},"initialDeliveryFees":[{"name":"DELIVERY_FEE_STANDARD","deliveryFeeAmount":{"amount":5.95,"currency":"EUR"},"positionItemIds":["8a88e387-a03d-4cc9-99d9-3de6a5c038bd","43111eca-18e5-4fe4-846c-2009d3643495","e4b96f70-495a-423c-877e-8886b5532ba4"],"vatRate":19}],"deliveryAddress":{"salutation":"MS","title":"Dr.","lastName":"Mustermann","firstName":"Max","street":"Werner-Otto-Str.","addition":"Hinterm Haus","houseNumber":"960","city":"Hamburg","zipCode":"22179","countryCode":"DEU","phoneNumber":"040 12345678","email":"test@example.com"},"invoiceAddress":{"salutation":"MS","title":"Dr.","lastName":"Mustermann","firstName":"Max","street":"Werner-Otto-Str.","addition":"Hinterm Haus","houseNumber":"960","city":"Hamburg","zipCode":"22179","countryCode":"DEU"},"links":[{"rel":"self","href":"/v4/orders/a24c37c0-768f-44e6-9f5c-1e4430d4ab32"}]}}},"schema":{"$ref":"#/components/schemas/PartnerOrder__Orders-V4"}}},"description":"Successfully found the requested sales order"},"400":{"content":{"application/json":{"examples":{"Bad request":{"description":"Bad request","summary":"Response for invalid requests","value":{"errors":[{"path":"/v4/orders/...","title":"Bad Request","detail":"Cannot parse request - please check query parameters and/or body"}]}}}}},"description":"Request is invalid"},"401":{"content":{"application/json":{"examples":{"Auth failed":{"description":"Auth failed","summary":"Response for invalid credentials","value":{"errors":[{"path":"/v4/orders/...","title":"Unauthorized","detail":"No proper credentials were provided"}]}}}}},"description":"Authentication failed"},"403":{"content":{"application/json":{"examples":{"Authorization missing":{"description":"Authorization missing","summary":"Response for missing access role rights","value":{"errors":[{"path":"/v4/orders/...","title":"Forbidden","detail":"No permission to access specified resource(s)"}]}}}}},"description":"Forbidden"},"404":{"content":{"application/json":{"examples":{"Not found":{"description":"Not found","summary":"Resource 'Not Found' response","value":{"errors":[{"path":"/v4/orders/...","title":"Not Found","detail":"The specified resource(s) could not be found"}]}}}}},"description":"Order with given orderNumber not found"}},"security":[{"bearerAuth":["orders"]}],"summary":"Get an order via order number","tags":["Orders-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url https://api.otto.market/v4/orders/%7BorderNumber%7D \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET https://api.otto.market/v4/orders/%7BorderNumber%7D \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v4/orders/{salesOrderId}":{"get":{"description":"Fetch a single order by its unique sales order id.","operationId":"Orders-V4__getPartnerOrderBySalesOrderId","parameters":[{"in":"path","name":"salesOrderId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"examples":{"Announced order":{"description":"Announced order","summary":"An order in state ANNOUNCED","value":{"salesOrderId":"8bd8a7cb-1ce1-4024-bdec-1c60de3c8006","orderNumber":"bwvdp9gcyk","orderDate":"2021-03-31T09:45:52.313+0000","lastModifiedDate":"2021-03-31T10:30:52.434+0000","positionItems":[{"positionItemId":"41d73c45-6177-4230-8907-4ffafd09064e","fulfillmentStatus":"ANNOUNCED","dealName":"Deal der Woche 52","dealId":"b65ef4bc-8f28-4fdd-a14a-b30b98449698","itemValueGrossPrice":{"amount":13.37,"currency":"EUR"},"product":{"sku":"P4567","productTitle":"Red T-Shirt","articleNumber":"X2G1D12FT8","ean":"4606938545083","vatRate":19}}],"orderLifecycleInformation":{"lifecycleChangeDate":"2021-03-31T10:30:52.433+0000"},"payment":{"paymentMethod":"PREPAYMENT"},"initialDeliveryFees":[{"name":"DELIVERY_FEE_STANDARD","deliveryFeeAmount":{"amount":5.95,"currency":"EUR"},"positionItemIds":["41d73c45-6177-4230-8907-4ffafd09064e"],"vatRate":19}],"links":[{"rel":"self","href":"/v4/orders/8bd8a7cb-1ce1-4024-bdec-1c60de3c8006"}]}},"Processable order":{"description":"Processable order","summary":"An order in state PROCESSABLE","value":{"salesOrderId":"a24c37c0-768f-44e6-9f5c-1e4430d4ab32","orderNumber":"bwqwz7s8cx","orderDate":"2021-04-16T05:59:01.255+0000","lastModifiedDate":"2021-04-16T06:44:02.249+0000","positionItems":[{"positionItemId":"8a88e387-a03d-4cc9-99d9-3de6a5c038bd","fulfillmentStatus":"PROCESSABLE","dealName":"Deal der Woche 52","dealId":"b65ef4bc-8f28-4fdd-a14a-b30b98449698","expectedDeliveryDate":"2021-04-21T12:00:00.000+02:00","itemValueGrossPrice":{"amount":23.95,"currency":"EUR"},"product":{"sku":"V0533","productTitle":"White Shirt","articleNumber":"1563237W3","vatRate":19}},{"positionItemId":"43111eca-18e5-4fe4-846c-2009d3643495","fulfillmentStatus":"CANCELLED_BY_PARTNER","dealName":"Deal der Woche 52","dealId":"b65ef4bc-8f28-4fdd-a14a-b30b98449698","expectedDeliveryDate":"2021-04-21T12:00:00.000+02:00","cancellationReason":"CANCELLED_ON_PARTNER_WISH","itemValueGrossPrice":{"amount":99.2,"currency":"EUR"},"product":{"sku":"A7567","productTitle":"Black Jeans","articleNumber":"333207J4","vatRate":19}},{"positionItemId":"e4b96f70-495a-423c-877e-8886b5532ba4","fulfillmentStatus":"PROCESSABLE","expectedDeliveryDate":"2021-04-24T12:00:00.000+02:00","itemValueGrossPrice":{"amount":15.7,"currency":"EUR"},"product":{"sku":"L8456","productTitle":"Red Socks","articleNumber":"4561237P3","vatRate":19}}],"orderLifecycleInformation":{"lifecycleChangeDate":"2021-04-16T06:44:02.249+0000"},"payment":{"paymentMethod":"PREPAYMENT"},"initialDeliveryFees":[{"name":"DELIVERY_FEE_STANDARD","deliveryFeeAmount":{"amount":5.95,"currency":"EUR"},"positionItemIds":["8a88e387-a03d-4cc9-99d9-3de6a5c038bd","43111eca-18e5-4fe4-846c-2009d3643495","e4b96f70-495a-423c-877e-8886b5532ba4"],"vatRate":19}],"deliveryAddress":{"salutation":"MS","title":"Dr.","lastName":"Mustermann","firstName":"Max","street":"Werner-Otto-Str.","addition":"Hinterm Haus","houseNumber":"960","city":"Hamburg","zipCode":"22179","countryCode":"DEU","phoneNumber":"040 12345678","email":"test@example.com"},"invoiceAddress":{"salutation":"MS","title":"Dr.","lastName":"Mustermann","firstName":"Max","street":"Werner-Otto-Str.","addition":"Hinterm Haus","houseNumber":"960","city":"Hamburg","zipCode":"22179","countryCode":"DEU"},"links":[{"rel":"self","href":"/v4/orders/a24c37c0-768f-44e6-9f5c-1e4430d4ab32"}]}}},"schema":{"$ref":"#/components/schemas/PartnerOrder__Orders-V4"}}},"description":"Successfully found the requested sales order"},"400":{"content":{"application/json":{"examples":{"Bad request":{"description":"Bad request","summary":"Response for invalid requests","value":{"errors":[{"path":"/v4/orders/...","title":"Bad Request","detail":"Cannot parse request - please check query parameters and/or body"}]}}}}},"description":"Request is invalid"},"401":{"content":{"application/json":{"examples":{"Auth failed":{"description":"Auth failed","summary":"Response for invalid credentials","value":{"errors":[{"path":"/v4/orders/...","title":"Unauthorized","detail":"No proper credentials were provided"}]}}}}},"description":"Authentication failed"},"403":{"content":{"application/json":{"examples":{"Authorization missing":{"description":"Authorization missing","summary":"Response for missing access role rights","value":{"errors":[{"path":"/v4/orders/...","title":"Forbidden","detail":"No permission to access specified resource(s)"}]}}}}},"description":"Forbidden"},"404":{"content":{"application/json":{"examples":{"Not found":{"description":"Not found","summary":"Resource 'Not Found' response","value":{"errors":[{"path":"/v4/orders/...","title":"Not Found","detail":"The specified resource(s) could not be found"}]}}}}},"description":"Order with given salesOrderId not found"}},"security":[{"bearerAuth":["orders"]}],"summary":"Get an order via sales order id","tags":["Orders-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url https://api.otto.market/v4/orders/%7BsalesOrderId%7D \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET https://api.otto.market/v4/orders/%7BsalesOrderId%7D \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v4/orders/{salesOrderId}/cancellation":{"post":{"description":"Allows to cancel all position items of one or more orders by salesOrderId.
Note: Only position items in state PROCESSABLE can be cancelled. Position items in different states will be ignored. If no position item can be cancelled the operation will respond with a conflict error message.","operationId":"Orders-V4__cancelPartnerOrders","parameters":[{"description":"The salesOrderIds of the orders to cancel","in":"path","name":"salesOrderId","required":true,"schema":{"type":"array","items":{"type":"string"}}}],"responses":{"202":{"description":"The request was accepted - update will be processed asynchronously"},"400":{"content":{"application/json":{"examples":{"Bad request":{"description":"Bad request","summary":"Response for invalid requests","value":{"errors":[{"path":"/v4/orders/...","title":"Bad Request","detail":"Cannot parse request - please check query parameters and/or body"}]}}}}},"description":"Request is invalid"},"401":{"content":{"application/json":{"examples":{"Auth failed":{"description":"Auth failed","summary":"Response for invalid credentials","value":{"errors":[{"path":"/v4/orders/...","title":"Unauthorized","detail":"No proper credentials were provided"}]}}}}},"description":"Authentication failed"},"403":{"content":{"application/json":{"examples":{"Authorization missing":{"description":"Authorization missing","summary":"Response for missing access role rights","value":{"errors":[{"path":"/v4/orders/...","title":"Forbidden","detail":"No permission to access specified resource(s)"}]}}}}},"description":"Forbidden"},"404":{"content":{"application/json":{"examples":{"Not found":{"description":"Not found","summary":"Resource 'Not Found' response","value":{"errors":[{"path":"/v4/orders/...","title":"Not Found","detail":"The specified resource(s) could not be found"}]}}}}},"description":"At least one of the given salesOrderIds is unknown"},"409":{"content":{"application/json":{"example":{"errors":[{"path":"/v4/orders/9404a8e2-8203-43de-889d-b5d733b6698f/cancellation","title":"Conflict","detail":"No position item in sales order [9404a8e2-8203-43de-889d-b5d733b6698f] has a fulfillment status that can be changed to [CANCELLED_BY_PARTNER]. Fulfillment status needs to be [PROCESSABLE]."}]}}},"description":"There was a conflict while trying to cancel"}},"security":[{"bearerAuth":["orders"]}],"summary":"Cancel all position items of an order","tags":["Orders-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request POST \\\n --url https://api.otto.market/v4/orders/%7BsalesOrderId%7D/cancellation \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http POST https://api.otto.market/v4/orders/%7BsalesOrderId%7D/cancellation \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v4/orders/{salesOrderId}/positionItems/{positionItemIds}/cancellation":{"post":{"description":"Allows to cancel specific position items of an order by salesOrderId and positionItemIds.
Note: Only position items in state PROCESSABLE can be cancelled. Position items in state CANCELLED_BY_PARTNER will be ignored. If any position item is in a different state the operation will leave the whole order unchanged and respond with a conflict error message.","operationId":"Orders-V4__cancelPartnerOrderPositionItems","parameters":[{"description":"The salesOrderId of the order","in":"path","name":"salesOrderId","required":true,"schema":{"type":"string"}},{"description":"The positionItemIds of the order to cancel","in":"path","name":"positionItemIds","required":true,"schema":{"type":"array","items":{"type":"string"}}}],"responses":{"202":{"description":"The request was accepted - update will be processed asynchronously"},"400":{"content":{"application/json":{"examples":{"Bad request":{"description":"Bad request","summary":"Response for invalid requests","value":{"errors":[{"path":"/v4/orders/...","title":"Bad Request","detail":"Cannot parse request - please check query parameters and/or body"}]}}}}},"description":"Request is invalid"},"401":{"content":{"application/json":{"examples":{"Auth failed":{"description":"Auth failed","summary":"Response for invalid credentials","value":{"errors":[{"path":"/v4/orders/...","title":"Unauthorized","detail":"No proper credentials were provided"}]}}}}},"description":"Authentication failed"},"403":{"content":{"application/json":{"examples":{"Authorization missing":{"description":"Authorization missing","summary":"Response for missing access role rights","value":{"errors":[{"path":"/v4/orders/...","title":"Forbidden","detail":"No permission to access specified resource(s)"}]}}}}},"description":"Forbidden"},"404":{"content":{"application/json":{"examples":{"Not found":{"description":"Not found","summary":"Resource 'Not Found' response","value":{"errors":[{"path":"/v4/orders/...","title":"Not Found","detail":"The specified resource(s) could not be found"}]}}}}},"description":"Order with given salesOrderId not found or order did not contain one of the given positionItemIds"},"409":{"content":{"application/json":{"example":{"errors":[{"path":"/v4/orders/9404a8e2-8203-43de-889d-b5d733b6698f/positionItems/ac50ec7f-0e0a-404f-a06d-524cfc2374ba/cancellation","title":"Conflict","detail":"Fulfillment status of position item [ac50ec7f-0e0a-404f-a06d-524cfc2374ba] in sales order [9404a8e2-8203-43de-889d-b5d733b6698f] can't be changed from [ANNOUNCED] to [CANCELLED_BY_PARTNER]. Fulfillment status needs to be [PROCESSABLE]."}]}}},"description":"There was a conflict while trying to cancel"}},"security":[{"bearerAuth":["orders"]}],"summary":"Cancel specific position items of an order","tags":["Orders-V4"],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request POST \\\n --url https://api.otto.market/v4/orders/%7BsalesOrderId%7D/positionItems/%7BpositionItemIds%7D/cancellation \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http POST https://api.otto.market/v4/orders/%7BsalesOrderId%7D/positionItems/%7BpositionItemIds%7D/cancellation \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v1/return-shipments":{"get":{"security":[{"bearerAuth":["shipments"]}],"tags":["ReturnShipments-V1"],"summary":"Retrieve returnShipments.","description":"This endpoint can be used to retrieve the returned shipments for a given authorized partner.","operationId":"ReturnShipments-V1__listReturnShipmentsUsingGET","parameters":[{"name":"datefrom","description":"ReturnShipments which are announced after this date or had an status update after this date will be returned for the partner which is determined from the authorization token. The date is considered as UTC.","in":"query","required":true,"allowEmptyValue":false,"schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","description":"The maximum number of returnShipments to be returned in each response.","required":false,"schema":{"type":"integer","format":"int32","minimum":1,"maximum":100,"default":25}},{"name":"next","in":"query","description":"The cursor which points to the next returnShipment that should be queried. It is used to paginate the results.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnShipmentList__ReturnShipments-V1"}}}},"400":{"description":"BadRequest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest__ReturnShipments-V1"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized__ReturnShipments-V1"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorGetReturnShipmentList__ReturnShipments-V1"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url 'https://api.otto.market/v1/return-shipments?datefrom=SOME_STRING_VALUE&limit=SOME_INTEGER_VALUE&next=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET 'https://api.otto.market/v1/return-shipments?datefrom=SOME_STRING_VALUE&limit=SOME_INTEGER_VALUE&next=SOME_STRING_VALUE' \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v1/return-shipments/carriers/{carrier}/trackingnumbers/{trackingNumber}":{"get":{"security":[{"bearerAuth":["shipments"]}],"tags":["ReturnShipments-V1"],"summary":"Retrieve returnShipment by carrier and tracking number.","description":"This endpoint can be used to retrieve a returned shipment by carrier and tracking number.","operationId":"ReturnShipments-V1__returnShipmentByCarrierAndTrackingNumberUsingGET","parameters":[{"name":"carrier","in":"path","description":"The carrier of the returnShipment.","required":true,"schema":{"type":"string","enum":["DHL","GLS","HERMES","HES"]}},{"name":"trackingNumber","in":"path","description":"The tracking number of the returnShipment assigned by the carrier.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnShipment__ReturnShipments-V1"}}}},"400":{"description":"BadRequest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest__ReturnShipments-V1"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized__ReturnShipments-V1"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenGetReturnShipmentByTrackingNumber__ReturnShipments-V1"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundGetReturnShipmentByTrackingNumber__ReturnShipments-V1"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorGetReturnShipmentByTrackingNumber__ReturnShipments-V1"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url https://api.otto.market/v1/return-shipments/carriers/%7Bcarrier%7D/trackingnumbers/%7BtrackingNumber%7D \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET https://api.otto.market/v1/return-shipments/carriers/%7Bcarrier%7D/trackingnumbers/%7BtrackingNumber%7D \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v1/return-shipments/{returnShipmentId}":{"get":{"security":[{"bearerAuth":["shipments"]}],"tags":["ReturnShipments-V1"],"summary":"Retrieve returnShipments by returnShipment ID.","description":"This endpoint can be used to retrieve a returned shipment by OTTO internal returnShipment ID.","operationId":"ReturnShipments-V1__returnShipmentUsingGET","parameters":[{"name":"returnShipmentId","in":"path","description":"Internal return shipment identifier assigned by OTTO Market.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnShipment__ReturnShipments-V1"}}}},"400":{"description":"BadRequest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest__ReturnShipments-V1"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized__ReturnShipments-V1"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenGetReturnShipmentByReturnShipmentId__ReturnShipments-V1"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundGetReturnShipmentByReturnShipmentId__ReturnShipments-V1"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorGetReturnShipmentByReturnShipmentId__ReturnShipments-V1"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url https://api.otto.market/v1/return-shipments/%7BreturnShipmentId%7D \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET https://api.otto.market/v1/return-shipments/%7BreturnShipmentId%7D \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v1/shipments":{"post":{"security":[{"bearerAuth":["shipments"]}],"tags":["Shipments-V1"],"summary":"Create a shipment and mark the position items as sent.","description":"This endpoint should be used to create a shipment with a list of position items.","operationId":"Shipments-V1__createdAndSentShipmentUsingPOST","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateShipmentRequest__Shipments-V1"},"examples":{"parcel delivery request":{"$ref":"#/components/examples/ShipmentCreateRequestParcelDelivery__Shipments-V1"},"forwarder delivery request":{"$ref":"#/components/examples/ShipmentCreateRequestForwarderDelivery__Shipments-V1"},"forwarder delivery request (no trackingNumber available)":{"$ref":"#/components/examples/ShipmentCreateRequestForwarderDeliveryWithoutTrackingNo__Shipments-V1"}}}},"description":"request","required":true},"responses":{"201":{"description":"Resource created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateShipmentResponse__Shipments-V1"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest__Shipments-V1"},"examples":{"insufficent permissions":{"$ref":"#/components/examples/ShipmentCreateInsufficientPermissionsResponse__Shipments-V1"},"tracking key mandatory":{"$ref":"#/components/examples/ShipmentCreateTrackingKeyMandatoryResponse__Shipments-V1"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized__Shipments-V1"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conflict__Shipments-V1"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerError__Shipments-V1"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request POST \\\n --url https://api.otto.market/v1/shipments \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --header 'content-type: application/json' \\\n --data '{\"trackingKey\":{\"carrier\":\"HERMES\",\"trackingNumber\":\"H1234567890123456789\"},\"shipDate\":\"2019-10-11T07:49:12.642Z\",\"shipFromAddress\":{\"city\":\"Dresden\",\"countryCode\":\"DEU\",\"zipCode\":\"01067\"},\"positionItems\":[{\"positionItemId\":\"b01b8ad2-a49c-47fc-8ade-8629ec000020\",\"salesOrderId\":\"bf43d748-f13d-49ca-b2e2-1824e9000021\",\"returnTrackingKey\":{\"carrier\":\"DHL\",\"trackingNumber\":\"577546565072\"}},{\"positionItemId\":\"b01b8ad2-a49c-47fc-8ade-8629ec000022\",\"salesOrderId\":\"bf43d748-f13d-49ca-b2e2-1824e9000021\",\"returnTrackingKey\":{\"carrier\":\"DHL\",\"trackingNumber\":\"577546565072\"}}]}'"},{"lang":"Shell + Httpie","source":"echo '{\"trackingKey\":{\"carrier\":\"HERMES\",\"trackingNumber\":\"H1234567890123456789\"},\"shipDate\":\"2019-10-11T07:49:12.642Z\",\"shipFromAddress\":{\"city\":\"Dresden\",\"countryCode\":\"DEU\",\"zipCode\":\"01067\"},\"positionItems\":[{\"positionItemId\":\"b01b8ad2-a49c-47fc-8ade-8629ec000020\",\"salesOrderId\":\"bf43d748-f13d-49ca-b2e2-1824e9000021\",\"returnTrackingKey\":{\"carrier\":\"DHL\",\"trackingNumber\":\"577546565072\"}},{\"positionItemId\":\"b01b8ad2-a49c-47fc-8ade-8629ec000022\",\"salesOrderId\":\"bf43d748-f13d-49ca-b2e2-1824e9000021\",\"returnTrackingKey\":{\"carrier\":\"DHL\",\"trackingNumber\":\"577546565072\"}}]}' | \\\n http POST https://api.otto.market/v1/shipments \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN' \\\n content-type:application/json"}]},"get":{"security":[{"bearerAuth":["shipments"]}],"tags":["Shipments-V1"],"summary":"Retrieve shipments.","description":"This endpoint can be used to retrieve the shipments for a given authorized partner.","operationId":"Shipments-V1__listShipmentsUsingGET","parameters":[{"name":"datefrom","description":"Shipments created from this date onwards for the given authorized partner will be returned. Can be specified as either an ISO date (`YYYY-MM-DD`), which will be inferred to be in UTC time, or an ISO date time (`YYYY-MM-DD'T'HH:mm:ss.SSSXXX`).\n\nFor example, `2024-01-10` would be interpreted the same as `2024-01-10T00:00:00Z`.","in":"query","required":true,"allowEmptyValue":false,"schema":{"type":"string","format":"YYYY-MM-DD['T'HH:mm:ss.SSSXXX]"}},{"name":"limit","in":"query","description":"The maximum number of shipments to be returned in each response.","required":false,"schema":{"type":"integer","format":"int32","minimum":1,"maximum":100,"default":25}},{"name":"next","in":"query","description":"The cursor which points to the next shipment that should be queried. It is used to paginate the results.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentList__Shipments-V1"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized__Shipments-V1"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorGetShipmentList__Shipments-V1"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url 'https://api.otto.market/v1/shipments?datefrom=SOME_STRING_VALUE&limit=SOME_INTEGER_VALUE&next=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET 'https://api.otto.market/v1/shipments?datefrom=SOME_STRING_VALUE&limit=SOME_INTEGER_VALUE&next=SOME_STRING_VALUE' \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v1/shipments/carriers/{carrier}/trackingnumbers/{trackingNumber}":{"get":{"security":[{"bearerAuth":["shipments"]}],"tags":["Shipments-V1"],"summary":"Retrieve shipment by carrier and tracking number.","description":"This endpoint can be used to retrieve a shipment by carrier and tracking number.","operationId":"Shipments-V1__shipmentByCarrierAndTrackingNumberUsingGET","parameters":[{"name":"carrier","in":"path","description":"The carrier of the shipment.","required":true,"schema":{"type":"string","enum":["DHL","DHL_EXPRESS","DHL_FREIGHT","DHL_HOME_DELIVERY","GLS","HERMES","DPD","UPS","BTW","BURSPED","CARGOLINE","DACHSER","DB_SCHENKER","DSV","EMONS","EPH_DIREKT","IDS","GEIS","GEL","GUETTLER","HES","HELLMANN","HEUEL","KOCH","KUEHNE_NAGEL","LOGWIN","MEYER_JUMBO","RABEN_LOGISTIK","RHENUS","REIMER","REITHMEIER","SCHOCKEMOEHLE","SCHMIDT_GEVELSBERG","ZUFALL","OTHER_FORWARDER"]}},{"name":"trackingNumber","in":"path","description":"The tracking number of the shipment assigned by the carrier.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment__Shipments-V1"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized__Shipments-V1"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenGetShipmentByTrackingNumber__Shipments-V1"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundGetShipmentByTrackingNumber__Shipments-V1"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorGetShipmentByTrackingNumber__Shipments-V1"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url https://api.otto.market/v1/shipments/carriers/%7Bcarrier%7D/trackingnumbers/%7BtrackingNumber%7D \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET https://api.otto.market/v1/shipments/carriers/%7Bcarrier%7D/trackingnumbers/%7BtrackingNumber%7D \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v1/shipments/{shipmentId}":{"get":{"security":[{"bearerAuth":["shipments"]}],"tags":["Shipments-V1"],"summary":"Retrieve shipment by shipment ID.","description":"This endpoint can be used to retrieve a shipment by OTTO internal shipment ID.","operationId":"Shipments-V1__shipmentUsingGET","parameters":[{"name":"shipmentId","in":"path","description":"Internal shipment identifier assigned by OTTO Market.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment__Shipments-V1"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized__Shipments-V1"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenGetShipmentByShipmentId__Shipments-V1"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundGetShipmentByShipmentId__Shipments-V1"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorGetShipmentByShipmentId__Shipments-V1"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url https://api.otto.market/v1/shipments/%7BshipmentId%7D \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET https://api.otto.market/v1/shipments/%7BshipmentId%7D \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v1/shipments/carriers/{carrier}/trackingnumbers/{trackingNumber}/positionitems":{"post":{"security":[{"bearerAuth":["shipments"]}],"tags":["Shipments-V1"],"summary":"Correct an existing shipment (add sent items) by carrier and tracking number.","description":"This endpoint allows to update an existing shipment with new position items.","operationId":"Shipments-V1__appendPositionItemsByCarrierAndTrackingNumberUsingPOST","parameters":[{"name":"carrier","in":"path","description":"The carrier of the shipment.","required":true,"schema":{"type":"string","enum":["DHL","DHL_EXPRESS","DHL_FREIGHT","DHL_HOME_DELIVERY","GLS","HERMES","DPD","UPS","BTW","BURSPED","CARGOLINE","DACHSER","DB_SCHENKER","DSV","EMONS","EPH_DIREKT","IDS","GEIS","GEL","GUETTLER","HES","HELLMANN","HEUEL","KOCH","KUEHNE_NAGEL","LOGWIN","MEYER_JUMBO","RABEN_LOGISTIK","RHENUS","REIMER","REITHMEIER","SCHOCKEMOEHLE","SCHMIDT_GEVELSBERG","ZUFALL","OTHER_FORWARDER"]}},{"name":"trackingNumber","in":"path","description":"The tracking number of the shipment assigned by the carrier.","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PositionItem__Shipments-V1"}}}},"description":"The position items included in shipment.","required":true},"responses":{"200":{"description":"OK"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestAddPositionItemByTrackingNumber__Shipments-V1"},"examples":{"insufficent permissions":{"$ref":"#/components/examples/ShipmentAddPositionItemsInsufficientPermissionsResponse__Shipments-V1"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized__Shipments-V1"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundAddPositionItemByTrackingNumber__Shipments-V1"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConflictAddPositionItemByTrackingNumber__Shipments-V1"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorAddPositionItemByTrackingNumber__Shipments-V1"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request POST \\\n --url https://api.otto.market/v1/shipments/carriers/%7Bcarrier%7D/trackingnumbers/%7BtrackingNumber%7D/positionitems \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --header 'content-type: application/json' \\\n --data '[{\"positionItemId\":\"e454dff5-a96f-4e96-9399-710cf59645c2\",\"salesOrderId\":\"a46fb35b-9c77-41c9-af10-2676b756a9af\",\"returnTrackingKey\":{\"carrier\":\"DHL\",\"trackingNumber\":\"577546565072\"},\"returnAddressCarrierId\":\"7423afd2-e7ab-4bae-ac30-048b7c0346c1\"}]'"},{"lang":"Shell + Httpie","source":"echo '[{\"positionItemId\":\"e454dff5-a96f-4e96-9399-710cf59645c2\",\"salesOrderId\":\"a46fb35b-9c77-41c9-af10-2676b756a9af\",\"returnTrackingKey\":{\"carrier\":\"DHL\",\"trackingNumber\":\"577546565072\"},\"returnAddressCarrierId\":\"7423afd2-e7ab-4bae-ac30-048b7c0346c1\"}]' | \\\n http POST https://api.otto.market/v1/shipments/carriers/%7Bcarrier%7D/trackingnumbers/%7BtrackingNumber%7D/positionitems \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN' \\\n content-type:application/json"}]}},"/v1/shipments/{shipmentId}/positionitems":{"post":{"security":[{"bearerAuth":["shipments"]}],"tags":["Shipments-V1"],"summary":"Correct an existing shipment (add sent items) by shipment ID.","description":"This endpoint allows to update an existing shipment with new position items. Note that this is just a correction process for shipments where position items are missing. A separate purchase receipt will be generated for the newly added position items.","operationId":"Shipments-V1__appendPositionItemsUsingPOST","parameters":[{"name":"shipmentId","in":"path","description":"Internal shipment identifier assigned by OTTO Market.","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PositionItem__Shipments-V1"}}}},"description":"positionItems","required":true},"responses":{"200":{"description":"OK"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestAddPositionItemByShipmentId__Shipments-V1"},"examples":{"insufficent permissions":{"$ref":"#/components/examples/ShipmentAddPositionItemsInsufficientPermissionsResponse__Shipments-V1"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized__Shipments-V1"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundAddPositionItemByShipmentId__Shipments-V1"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConflictAddPositionItemByShipmentId__Shipments-V1"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorAddPositionItemByShipmentId__Shipments-V1"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request POST \\\n --url https://api.otto.market/v1/shipments/%7BshipmentId%7D/positionitems \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --header 'content-type: application/json' \\\n --data '[{\"positionItemId\":\"e454dff5-a96f-4e96-9399-710cf59645c2\",\"salesOrderId\":\"a46fb35b-9c77-41c9-af10-2676b756a9af\",\"returnTrackingKey\":{\"carrier\":\"DHL\",\"trackingNumber\":\"577546565072\"},\"returnAddressCarrierId\":\"7423afd2-e7ab-4bae-ac30-048b7c0346c1\"}]'"},{"lang":"Shell + Httpie","source":"echo '[{\"positionItemId\":\"e454dff5-a96f-4e96-9399-710cf59645c2\",\"salesOrderId\":\"a46fb35b-9c77-41c9-af10-2676b756a9af\",\"returnTrackingKey\":{\"carrier\":\"DHL\",\"trackingNumber\":\"577546565072\"},\"returnAddressCarrierId\":\"7423afd2-e7ab-4bae-ac30-048b7c0346c1\"}]' | \\\n http POST https://api.otto.market/v1/shipments/%7BshipmentId%7D/positionitems \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN' \\\n content-type:application/json"}]}},"/v1/multiparcel-shipments":{"post":{"security":[{"bearerAuth":["shipments"]}],"tags":["Shipments-V1"],"summary":"Create a multiparcel shipment and mark the position items as sent.","description":"This endpoint is designed for creating multiparcel shipments when a single article (position item) is sent in multiple shipments, each with its own tracking key.","operationId":"Shipments-V1__createdAndSentMultiparcelShipmentUsingPOST","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMultiparcelShipmentRequest__Shipments-V1"},"examples":{"multiparcel delivery request":{"$ref":"#/components/examples/MultiparcelShipmentCreateRequestParcelDelivery__Shipments-V1"}}}},"description":"request","required":true},"responses":{"201":{"description":"Resource created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMultiparcelShipmentResponse__Shipments-V1"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest__Shipments-V1"},"examples":{"insufficent permissions":{"$ref":"#/components/examples/MultiparcelShipmentCreateInsufficientPermissionsResponse__Shipments-V1"},"tracking key mandatory":{"$ref":"#/components/examples/MultiparcelShipmentCreateTrackingKeyMandatoryResponse__Shipments-V1"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized__Shipments-V1"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConflictMultiparcel__Shipments-V1"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorMultiparcel__Shipments-V1"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request POST \\\n --url https://api.otto.market/v1/multiparcel-shipments \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --header 'content-type: application/json' \\\n --data '[{\"trackingKey\":{\"carrier\":\"HERMES\",\"trackingNumber\":\"H1234567890123456789\"},\"shipDate\":\"2019-10-11T07:49:12.642Z\",\"shipFromAddress\":{\"city\":\"Dresden\",\"countryCode\":\"DEU\",\"zipCode\":\"01067\"},\"positionItems\":[{\"positionItemId\":\"b01b8ad2-a49c-47fc-8ade-8629ec000020\",\"salesOrderId\":\"bf43d748-f13d-49ca-b2e2-1824e9000021\",\"returnTrackingKey\":{\"carrier\":\"DHL\",\"trackingNumber\":\"577546565072\"}},{\"positionItemId\":\"b01b8ad2-a49c-47fc-8ade-8629ec000022\",\"salesOrderId\":\"bf43d748-f13d-49ca-b2e2-1824e9000021\",\"returnTrackingKey\":{\"carrier\":\"DHL\",\"trackingNumber\":\"577546565072\"}}]},{\"trackingKey\":{\"carrier\":\"HERMES\",\"trackingNumber\":\"H1234567890123456789\"},\"shipDate\":\"2019-10-11T07:49:12.642Z\",\"shipFromAddress\":{\"city\":\"Dresden\",\"countryCode\":\"DEU\",\"zipCode\":\"01067\"},\"positionItems\":[{\"positionItemId\":\"b01b8ad2-a49c-47fc-8ade-8629ec000020\",\"salesOrderId\":\"bf43d748-f13d-49ca-b2e2-1824e9000021\",\"returnTrackingKey\":{\"carrier\":\"DHL\",\"trackingNumber\":\"577546565072\"}},{\"positionItemId\":\"b01b8ad2-a49c-47fc-8ade-8629ec000022\",\"salesOrderId\":\"bf43d748-f13d-49ca-b2e2-1824e9000021\",\"returnTrackingKey\":{\"carrier\":\"DHL\",\"trackingNumber\":\"577546565072\"}}]}]'"},{"lang":"Shell + Httpie","source":"echo '[{\"trackingKey\":{\"carrier\":\"HERMES\",\"trackingNumber\":\"H1234567890123456789\"},\"shipDate\":\"2019-10-11T07:49:12.642Z\",\"shipFromAddress\":{\"city\":\"Dresden\",\"countryCode\":\"DEU\",\"zipCode\":\"01067\"},\"positionItems\":[{\"positionItemId\":\"b01b8ad2-a49c-47fc-8ade-8629ec000020\",\"salesOrderId\":\"bf43d748-f13d-49ca-b2e2-1824e9000021\",\"returnTrackingKey\":{\"carrier\":\"DHL\",\"trackingNumber\":\"577546565072\"}},{\"positionItemId\":\"b01b8ad2-a49c-47fc-8ade-8629ec000022\",\"salesOrderId\":\"bf43d748-f13d-49ca-b2e2-1824e9000021\",\"returnTrackingKey\":{\"carrier\":\"DHL\",\"trackingNumber\":\"577546565072\"}}]},{\"trackingKey\":{\"carrier\":\"HERMES\",\"trackingNumber\":\"H1234567890123456789\"},\"shipDate\":\"2019-10-11T07:49:12.642Z\",\"shipFromAddress\":{\"city\":\"Dresden\",\"countryCode\":\"DEU\",\"zipCode\":\"01067\"},\"positionItems\":[{\"positionItemId\":\"b01b8ad2-a49c-47fc-8ade-8629ec000020\",\"salesOrderId\":\"bf43d748-f13d-49ca-b2e2-1824e9000021\",\"returnTrackingKey\":{\"carrier\":\"DHL\",\"trackingNumber\":\"577546565072\"}},{\"positionItemId\":\"b01b8ad2-a49c-47fc-8ade-8629ec000022\",\"salesOrderId\":\"bf43d748-f13d-49ca-b2e2-1824e9000021\",\"returnTrackingKey\":{\"carrier\":\"DHL\",\"trackingNumber\":\"577546565072\"}}]}]' | \\\n http POST https://api.otto.market/v1/multiparcel-shipments \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN' \\\n content-type:application/json"}]}},"/v3/returns":{"get":{"security":[{"bearerAuth":["returns"]}],"tags":["Returns-V3"],"summary":"Get all the items filtered on return status","description":"The items will be sorted on status modified time in reverse chronological order. Additionally we provide cursor based pagination via next link. This endpoint is limited to at max 50 results per page","operationId":"Returns-V3__getPositionItemsForUsingGETV3","parameters":[{"name":"limit","in":"query","description":"Page size to limit the number of items returned in the response. Maximum value for limit can 50","required":false,"allowEmptyValue":false,"example":10,"schema":{"type":"integer","format":"int32","default":10}},{"name":"page","in":"query","description":"Page number to fetch. This parameter is required to fetch data for specific page number","required":false,"allowEmptyValue":false,"example":1,"schema":{"type":"integer","format":"int32","default":1}},{"name":"status","in":"query","description":"Return status for which items are being queried for (case-insensitive)","example":"MISDIRECTED","schema":{"type":"string","enum":["MISDIRECTED","ANNOUNCED","ACCEPTED","REJECTED"]}}],"responses":{"200":{"description":"Ok","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/PositionItemList__Returns-V3"}}}},"400":{"description":"Bad Request","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ApiErrorResponseV3__Returns-V3"}}}},"401":{"description":"Unauthorized to access","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ApiErrorResponseV3__Returns-V3"}}}},"404":{"description":"Item not found","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ApiErrorResponseV3__Returns-V3"}}}},"500":{"description":"Internal server error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ApiErrorResponseV3__Returns-V3"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url 'https://api.otto.market/v3/returns?limit=10&page=1&status=MISDIRECTED' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET 'https://api.otto.market/v3/returns?limit=10&page=1&status=MISDIRECTED' \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v3/returns/acceptance":{"post":{"security":[{"bearerAuth":["returns"]}],"tags":["Returns-V3"],"summary":"Accept the return for a sent position item (up to 200 items per request)","operationId":"Returns-V3__receiveAcceptedReturnsV3UsingPOSTV3","requestBody":{"content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/AcceptedPartnerReturnV3__Returns-V3"}}},"description":"acceptedPartnerReturn","required":true},"responses":{"200":{"description":"Ok","content":{"application/json;charset=UTF-8":{"schema":{"type":"object"}}}},"207":{"description":"Multi status","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/AcceptedReturnMultiStatusResponse__Returns-V3"}}}},"401":{"description":"Invalid token","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ApiErrorResponseV3__Returns-V3"}}}},"413":{"description":"Payload too large","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ApiErrorResponseV3__Returns-V3"}}}},"422":{"description":"Non-processable","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ApiErrorResponseV3__Returns-V3"}}}},"500":{"description":"Internal server error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ApiErrorResponseV3__Returns-V3"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request POST \\\n --url https://api.otto.market/v3/returns/acceptance \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http POST https://api.otto.market/v3/returns/acceptance \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v3/returns/rejection":{"post":{"security":[{"bearerAuth":["returns"]}],"tags":["Returns-V3"],"summary":"Reject the return for a sent position item (up to 200 items per request)","operationId":"Returns-V3__receiveRejectedReturnsV3UsingPOSTV3","requestBody":{"content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/RejectedPartnerReturnV3__Returns-V3"}}},"description":"rejectedPartnerReturn","required":true},"responses":{"200":{"description":"Ok","content":{"application/json;charset=UTF-8":{"schema":{"type":"object"}}}},"207":{"description":"Multi status","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/RejectedReturnMultiStatusResponse__Returns-V3"}}}},"400":{"description":"Bad request"},"401":{"description":"Invalid token","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ApiErrorResponseV3__Returns-V3"}}}},"413":{"description":"Payload too large","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ApiErrorResponseV3__Returns-V3"}}}},"422":{"description":"Non-processable","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ApiErrorResponseV3__Returns-V3"}}}},"500":{"description":"Internal server error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ApiErrorResponseV3__Returns-V3"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request POST \\\n --url https://api.otto.market/v3/returns/rejection \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http POST https://api.otto.market/v3/returns/rejection \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v3/receipts/{receiptNumber}.pdf":{"get":{"tags":["Receipts-V3"],"summary":"Get the PDF document of a specific receipt","description":"Get PDF document by 'receiptNumber'","operationId":"Receipts-V3__getReceiptPdfUsingGET_3","parameters":[{"name":"receiptNumber","in":"path","description":"ReceiptNumber","required":true,"schema":{"type":"string"},"example":"R-DE-123456789-2020-1507"}],"responses":{"200":{"description":"Successfully retrieved the receipt PDF","content":{"application/pdf":{}}},"401":{"description":"Unauthorized Access"},"403":{"description":"Forbidden Access"},"404":{"description":"Receipt PDF Not Found"}},"security":[{"bearerAuth":["receipts"]}],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url https://api.otto.market/v3/receipts/R-DE-123456789-2020-1507.pdf \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET https://api.otto.market/v3/receipts/R-DE-123456789-2020-1507.pdf \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v3/receipts/{receiptNumber}":{"get":{"tags":["Receipts-V3"],"summary":"Get the JSON object of a specific receipt","description":"Get JSON object by the 'receiptNumber'","operationId":"Receipts-V3__getReceiptUsingGET_5","parameters":[{"name":"receiptNumber","in":"path","description":"ReceiptNumber","required":true,"schema":{"type":"string"},"example":"R-DE-123456789-2020-1507"}],"responses":{"200":{"description":"Successfully retrieved the receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Receipt__Receipts-V3"}}}},"401":{"description":"Unauthorized Access"},"403":{"description":"Forbidden"},"404":{"description":"Receipt Not Found"}},"security":[{"bearerAuth":["receipts"]}],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url https://api.otto.market/v3/receipts/R-DE-123456789-2020-1507 \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET https://api.otto.market/v3/receipts/R-DE-123456789-2020-1507 \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v3/receipts":{"get":{"tags":["Receipts-V3"],"summary":"Get receipts as list of JSON objects","description":"Retrieve receips sorted by creation date, latest ones first. The number of receipts is limited to 128 results; cursor based pagination is supported.","operationId":"Receipts-V3__getReceiptsUsingGET_5","parameters":[{"name":"limit","in":"query","description":"Page size to limit the number of receipts returned in the response","required":false,"schema":{"minimum":1,"type":"integer","format":"int32","default":128},"example":128},{"name":"page","in":"query","description":"Page number to fetch. This parameter is required to fetch data for specific page number.\n
This field is deprecated, please use 'next' parameter","required":false,"deprecated":true,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"receiptTypes","in":"query","description":"\nSearch for receipts filtered by multiple receipt types.\n\n
PURCHASE - A purchase receipt (also known as an invoice) records the prices charged to the customer at the time of sale.\nThe receipt contains information per order, partner and shipment. It is generated when items are shipped to the customer, so there may be more than one receipt per order.\nShipping costs are charged only once per partner and per order, and are billed with first purchase receipt of this partner order.\nSurcharges imposed by payment provider on the customer for using special payment conditions are not included in the OTTO Market receipts.\n\n
REFUND - We distinguish between different types of reimbursement documents. A refund receipt documents a credit note issued to a customer for a refund.\nThis document is currently created when returns are accepted. In very rare cases, refund receipts may also be created during the cancellation process to reimburse shipping costs for full returns.\n Previous partial refunds will be taken into account.\n\n
PARTIAL_REFUND - We distinguish different types of reimbursement documents. A partial refund receipt documents a credit note issued to a customer without return.\n As a partner, you might offer a customer a partial refund if there is a legitimate complaint to avoid a return.\n\n
If no receiptType is provided, receipts of all existing receiptTypes will be returned.\n\nPlease for your own interest, hand over all receipt types you are interested in using the list parameter receiptTypes, so that OTTO Market could add new receipt types without side effects for your own processes.\nUsing this option you can decide by your own when to incorporate new receipt types in your own processes.\n\n\nPlease do not use the possibility of calls without specifying the receiptTypes anymore.","required":false,"schema":{"type":"array","items":{"type":"string","enum":["PURCHASE","REFUND","PARTIAL_REFUND"]}},"example":"PURCHASE,REFUND"},{"name":"from","in":"query","description":"Only receipts with creation date newer or equal than the date specified (yyy-mm-dd in UTC) will be returned.","required":false,"schema":{"type":"string","format":"date"},"example":"2022-08-01"},{"name":"to","in":"query","description":"Only receipts with creation date older or equal than the date specified (yyy-mm-dd in UTC) will be returned.","required":false,"schema":{"type":"string","format":"date"},"example":"2022-08-31"},{"name":"salesOrderId","in":"query","description":"Search for receipts filtered by sales order Id","required":false,"schema":{"type":"string"},"example":"f23eb274-a8a2-4721-a7bc-0d9aa1b11940"},{"name":"next","in":"query","description":"Cursor for paging requests. If a next cursor is provided, the only other request parameter being considered is 'limit'\n\nNote: Only the cursor string is required - not the whole link","required":false,"schema":{"type":"string"},"example":"eyJjcmVhdGlvbkRhdGUiOjE2ODU2OTE1NjUuMTk4MDAwMDAwLCJyZWNlaXB0TnVtYmVyIjoiRS1ERS0xMTg0NzU2OTAtMjAyMy0zNTgxMyJ9"}],"responses":{"200":{"description":"Successfully retrieved list of receipts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceiptsList__Receipts-V3"}}}},"401":{"description":"Unauthorized Access"},"403":{"description":"Forbidden Access"},"404":{"description":"Receipts Not Found"}},"security":[{"bearerAuth":["receipts"]}],"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url 'https://api.otto.market/v3/receipts?limit=128&page=1&receiptTypes=PURCHASE%2CREFUND&from=2022-08-01&to=2022-08-31&salesOrderId=f23eb274-a8a2-4721-a7bc-0d9aa1b11940&next=eyJjcmVhdGlvbkRhdGUiOjE2ODU2OTE1NjUuMTk4MDAwMDAwLCJyZWNlaXB0TnVtYmVyIjoiRS1ERS0xMTg0NzU2OTAtMjAyMy0zNTgxMyJ9' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET 'https://api.otto.market/v3/receipts?limit=128&page=1&receiptTypes=PURCHASE%2CREFUND&from=2022-08-01&to=2022-08-31&salesOrderId=f23eb274-a8a2-4721-a7bc-0d9aa1b11940&next=eyJjcmVhdGlvbkRhdGUiOjE2ODU2OTE1NjUuMTk4MDAwMDAwLCJyZWNlaXB0TnVtYmVyIjoiRS1ERS0xMTg0NzU2OTAtMjAyMy0zNTgxMyJ9' \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v1/price-reductions":{"get":{"security":[{"bearerAuth":["price-reduction"]}],"tags":["Price-Reductions-V1"],"summary":"Get all priceReductions","description":"This API can be used to fetch the price reduction for a single positionItemId by providing positionId as a query parameter in the request. If the positionItemId is not specified, then this api would list the price reductions for all your products.","operationId":"Price-Reductions-V1__getAllReductionsForPartner","parameters":[{"name":"positionItemId","in":"query","description":"positionItemId for which price reductions are to be fetched","required":false,"schema":{"type":"string","format":"uuid"},"example":"72d5b4ce-83c0-43aa-9645-0913456648a8"},{"name":"page","in":"query","description":"Page number to be fetched. Page number should not be less than 1","required":false,"schema":{"type":"integer","format":"int32","default":1}},{"name":"limit","in":"query","description":"Number of positionItemIds to be fetched per page. Limit should not exceed 128","required":false,"schema":{"type":"integer","format":"int32","default":10}}],"responses":{"200":{"description":"Successfully retrieved price reductions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceReductionsResponse__Price-Reductions-V1"}}}},"401":{"description":"Unauthorized Access"},"403":{"description":"Forbidden Access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenApplyPriceReduction__Price-Reductions-V1"}}}},"404":{"description":"Price reductions Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundPriceReductionForPositionItemId__Price-Reductions-V1"}}}},"424":{"description":"Unable to retrieve price discounts due to internal errors with downstream systems. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedDependency__Price-Reductions-V1"}}}}},"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url 'https://api.otto.market/v1/price-reductions?positionItemId=72d5b4ce-83c0-43aa-9645-0913456648a8&page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET 'https://api.otto.market/v1/price-reductions?positionItemId=72d5b4ce-83c0-43aa-9645-0913456648a8&page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE' \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]},"post":{"security":[{"bearerAuth":["price-reduction"]}],"tags":["Price-Reductions-V1"],"summary":"Apply price reduction for a positionItemId","description":"Apply price reduction on a positionItemId","operationId":"Price-Reductions-V1__applyPriceReduction","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerPriceReductionRequest__Price-Reductions-V1"}}},"required":true},"responses":{"202":{"description":"Successfully applied price reduction for a positionItemId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedPriceReductionResponse__Price-Reductions-V1"}}}},"401":{"description":"Unauthorized Access"},"403":{"description":"Forbidden Access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenApplyPriceReduction__Price-Reductions-V1"}}}},"404":{"description":"PositionItemId not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundPositionItemId__Price-Reductions-V1"}}}},"409":{"description":"PositionItemId is not shipped or returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConflictPositionItemId__Price-Reductions-V1"}}}},"424":{"description":"Unable to retrieve price discounts due to internal errors with downstream systems. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedDependency__Price-Reductions-V1"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorApplyPriceReduction__Price-Reductions-V1"}}}}},"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request POST \\\n --url https://api.otto.market/v1/price-reductions \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --header 'content-type: application/json' \\\n --data '{\"positionItemId\":\"ef0decec-e5b7-40d8-bd91-9dafec8041a2\",\"salesOrderId\":\"9bd8f312-a044-4003-9f73-706a82f71a8f\",\"priceReduction\":{\"amount\":121.01,\"currency\":\"EUR\"}}'"},{"lang":"Shell + Httpie","source":"echo '{\"positionItemId\":\"ef0decec-e5b7-40d8-bd91-9dafec8041a2\",\"salesOrderId\":\"9bd8f312-a044-4003-9f73-706a82f71a8f\",\"priceReduction\":{\"amount\":121.01,\"currency\":\"EUR\"}}' | \\\n http POST https://api.otto.market/v1/price-reductions \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN' \\\n content-type:application/json"}]}},"/v1/shipping-profiles":{"post":{"security":[{"bearerAuth":["shipping-profiles"]}],"tags":["ShippingProfiles-V1"],"summary":"Create shipping profile","description":"This POST API endpoint is to create shipping profile API\nPOST will always create a new shipping profile after ensuring it is not a duplicate for a partner.\n","operationId":"ShippingProfiles-V1__createShippingProfile","parameters":[{"name":"Authorization","in":"header","description":"Access Token","required":true,"example":"Bearer access_token","schema":{"type":"string"}}],"requestBody":{"content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/CreateShippingProfileRequest__ShippingProfiles-V1"}}},"description":"create shipping profile","required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateShippingProfileResponse__ShippingProfiles-V1"}}}},"400":{"description":"Bad Request
1. If any of the mandatory attribute missing in request body
2. If request body attributes type/format is wrong
3. Shipping Profile name is already existing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIErrorResponseForBadRequest__ShippingProfiles-V1"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden (Invalid token)","content":{"application/json":{"examples":{"Token is invalid":{"value":{"message":"Forbidden"}}}}}},"404":{"description":"Not found (URL is invalid)","content":{"application/json":{"examples":{"URL is invalid":{"value":{"message":"Not Found"}}}}}},"409":{"description":"Conflict.
When the same shipping profile ID already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIErrorResponseForConflict__ShippingProfiles-V1"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIInternalServerErrorResponse__ShippingProfiles-V1"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request POST \\\n --url https://api.otto.market/v1/shipping-profiles \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http POST https://api.otto.market/v1/shipping-profiles \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]},"get":{"security":[{"bearerAuth":["shipping-profiles"]}],"tags":["ShippingProfiles-V1"],"summary":"Get all shipping profiles from a partner","description":"This GET API endpoint is to get all shipping profiles for a partner.\nResponse is by default paginated with default page size of 300.\n","operationId":"ShippingProfiles-V1__getShippingProfiles","parameters":[{"name":"Authorization","in":"header","description":"Access Token","required":true,"example":"Bearer access_token","schema":{"type":"string"}},{"name":"cursor","in":"query","description":"Page number to fetch. This parameter is required to fetch data for specific page number","required":false,"allowEmptyValue":false,"example":"YtNTQzZS01YTBiLWFjNzktNTNmNWRiMTMyZTQ0fFJldmlld0RlbW8x","schema":{"type":"string"}}],"responses":{"200":{"description":"The shipping profile(s) of the partner","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/GetAllShippingProfilesResponse__ShippingProfiles-V1"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden (Invalid token)","content":{"application/json":{"examples":{"Token is invalid":{"value":{"message":"Forbidden"}}}}}},"404":{"description":"Not found (URL is invalid)","content":{"application/json":{"examples":{"URL is invalid":{"value":{"message":"Not Found"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIInternalServerErrorResponse__ShippingProfiles-V1"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url 'https://api.otto.market/v1/shipping-profiles?cursor=YtNTQzZS01YTBiLWFjNzktNTNmNWRiMTMyZTQ0fFJldmlld0RlbW8x' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET 'https://api.otto.market/v1/shipping-profiles?cursor=YtNTQzZS01YTBiLWFjNzktNTNmNWRiMTMyZTQ0fFJldmlld0RlbW8x' \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v1/shipping-profiles/{shippingProfileId}":{"get":{"security":[{"bearerAuth":["shipping-profiles"]}],"tags":["ShippingProfiles-V1"],"summary":"Get shipping profile by shipping profile id","description":"This GET API endpoint is to get a shipping profile of the partner by shipping profile id.\n","operationId":"ShippingProfiles-V1__getShippingProfileById","parameters":[{"name":"Authorization","in":"header","description":"Access Token","required":true,"example":"Bearer access_token","schema":{"type":"string"}},{"name":"shippingProfileId","in":"path","description":"The id of the shipping profile in uuid4 format and the primaryKey for mapping a Profile to a SKU","required":true,"allowEmptyValue":false,"schema":{"type":"string","example":"7bec0ef6-4324-4fa4-9fbf-42c54659ef04"}}],"responses":{"200":{"description":"The shipping profile details of the partner
1. specific shipping profile for the given shippingProfileId","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/GetShippingProfileResponse__ShippingProfiles-V1"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden (Invalid token)","content":{"application/json":{"examples":{"Token is invalid":{"value":{"message":"Forbidden"}}}}}},"404":{"description":"Not found.
1. If request path is not /v1/shipping-profiles
2. If shipping profile id is not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIErrorResponseForNotFound__ShippingProfiles-V1"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIInternalServerErrorResponse__ShippingProfiles-V1"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url https://api.otto.market/v1/shipping-profiles/7bec0ef6-4324-4fa4-9fbf-42c54659ef04 \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET https://api.otto.market/v1/shipping-profiles/7bec0ef6-4324-4fa4-9fbf-42c54659ef04 \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]},"put":{"security":[{"bearerAuth":["shipping-profiles"]}],"tags":["ShippingProfiles-V1"],"summary":"Update shipping profile","description":"This PUT API endpoint is to update a shipping profile\nPUT will always take an shipping profile and update it. \ndeliveryType field cannot be updated\n","operationId":"ShippingProfiles-V1__updateShippingProfile","parameters":[{"name":"Authorization","in":"header","description":"Access Token","required":true,"example":"Bearer access_token","schema":{"type":"string"}},{"name":"shippingProfileId","in":"path","description":"The id of the shipping profile in uuid4 format and the primaryKey for mapping a Profile to a SKU","required":true,"allowEmptyValue":false,"example":"7bec0ef6-4324-4fa4-9fbf-42c54659ef04","schema":{"type":"string"}}],"requestBody":{"content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/CreateShippingProfileRequest__ShippingProfiles-V1"}}},"description":"shipping profile request","required":true},"responses":{"204":{"description":"No Content"},"400":{"description":"Bad Request
1. If any of the mandatory attribute missing in request body
2. If request body attributes type/format is wrong
3. Shipping Profile name is already existing
4. Trying to update deliveryType","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIErrorResponseForBadRequest__ShippingProfiles-V1"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden (Invalid token)","content":{"application/json":{"examples":{"Token is invalid":{"value":{"message":"Forbidden"}}}}}},"404":{"description":"Not found.
1. If request path is not /v1/shipping-profiles
2. If shipping profile ID is not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIErrorResponseForNotFound__ShippingProfiles-V1"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIInternalServerErrorResponse__ShippingProfiles-V1"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request PUT \\\n --url https://api.otto.market/v1/shipping-profiles/7bec0ef6-4324-4fa4-9fbf-42c54659ef04 \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http PUT https://api.otto.market/v1/shipping-profiles/7bec0ef6-4324-4fa4-9fbf-42c54659ef04 \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]},"delete":{"security":[{"bearerAuth":["shipping-profiles"]}],"tags":["ShippingProfiles-V1"],"summary":"Delete shipping profile","description":"This DELETE API endpoint is to delete a shipping profile by id.\n","operationId":"ShippingProfiles-V1__deleteShippingProfile","parameters":[{"name":"Authorization","in":"header","description":"Access Token","required":true,"example":"Bearer access_token","schema":{"type":"string"}},{"name":"shippingProfileId","in":"path","description":"The id of the shipping profile in uuid4 format and the primaryKey for mapping a Profile to a SKU","required":true,"allowEmptyValue":false,"schema":{"type":"string","example":"7bec0ef6-4324-4fa4-9fbf-42c54659ef04"}}],"responses":{"204":{"description":"No Content"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden (Invalid token)","content":{"application/json":{"examples":{"Token is invalid":{"value":{"message":"Forbidden"}}}}}},"404":{"description":"Not found.
1. If request path is not /v1/shipping-profiles
2. If the shipping profile id not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIErrorResponseForNotFound__ShippingProfiles-V1"}}}},"412":{"description":"Pre condition failed.
1. When only one shipping profile exist for a partner. A partner must have at least one shipping profile
2. When shipping profile has one or more skus linked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIErrorResponseForPrecondition__ShippingProfiles-V1"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIInternalServerErrorResponse__ShippingProfiles-V1"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request DELETE \\\n --url https://api.otto.market/v1/shipping-profiles/7bec0ef6-4324-4fa4-9fbf-42c54659ef04 \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http DELETE https://api.otto.market/v1/shipping-profiles/7bec0ef6-4324-4fa4-9fbf-42c54659ef04 \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v1/availability/quantities":{"post":{"security":[{"bearerAuth":["availability"]}],"tags":["Availability-V1"],"summary":"Update quantities","operationId":"Availability-V1__storeAvailableQuantitiesUsingPOST","parameters":[{"name":"Authorization","in":"header","description":"Access Token","required":true,"example":"Bearer access_token","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json;charset=UTF-8":{"schema":{"type":"array","minItems":1,"maxItems":200,"items":{"$ref":"#/components/schemas/AvailableQuantityRequestDTO__Availability-V1"},"example":[{"quantity":123,"sku":"4007781056144"},{"quantity":123,"sku":"4007781056145"}]}}}},"responses":{"200":{"description":"Ok","content":{"application/json;charset=UTF-8":{"schema":{"type":"object"}}}},"207":{"description":"Multi Status (SKUs is unknown | Quantity must be >= 0 | Field must not be empty)","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/UpdateQuantityMultiStatusResponse__Availability-V1"}}}},"401":{"description":"Unauthorized to access"},"403":{"description":"Forbidden (Invalid token)","content":{"application/json":{"examples":{"Token is invalid":{"value":{"message":"Forbidden"}}}}}},"404":{"description":"Not found (URL is invalid)","content":{"application/json":{"examples":{"URL is invalid":{"value":{"message":"Not Found"}}}}}},"413":{"description":"Payload too large","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/PayloadTooLargeApiErrorResponseForQuantities__Availability-V1"}}}},"422":{"description":"Non-processable (SKUs is unknown | Quantity must be >= 0 | Field must not be empty | Invalid Quantity: Can only accept whole numbers)","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse__Availability-V1"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request POST \\\n --url https://api.otto.market/v1/availability/quantities \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http POST https://api.otto.market/v1/availability/quantities \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]},"get":{"security":[{"bearerAuth":["availability"]}],"tags":["Availability-V1"],"summary":"Get quantities from a partner (up to 200 per request)","description":"Retrieve available quantities sorted by sku name in ascending.The maximum number of returned quantities is limited to 200.","operationId":"Availability-V1__getAvailableQuantities","parameters":[{"name":"Authorization","in":"header","description":"Access Token","required":true,"example":"Bearer access_token","schema":{"type":"string"}},{"name":"limit","in":"query","description":"The maximum number of available quantities to be returned in each response.","required":false,"deprecated":true,"schema":{"type":"integer","format":"int32","default":200}},{"name":"page","in":"query","description":"Page number (0..N)","required":false,"deprecated":true,"schema":{"type":"integer","format":"int32","default":0}},{"name":"cursor","in":"query","description":"Cursor for paging requests. If a cursor is provided, the only other request parameter being considered is 'limit'. The cursor value is the last evaluted sku in the request response (Needs to be a valid sku value)","required":false,"schema":{"type":"string","example":"c2t1NDM="}}],"responses":{"200":{"description":"Ok","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/AvailableQuantityResponse__Availability-V1"}}}},"400":{"description":"Limit and page need to be integers","content":{"application/json":{"examples":{"Bad request":{"summary":"Response for invalid requests","description":"BAD REQUEST","value":{"errors":[{"code":400,"detail":"Limit and page need to be valid integers","path":"/v1/availability/quantities","title":"BAD REQUEST","logreg":""}]}}}}}},"403":{"description":"Unauthorized to access","content":{"application/json":{"examples":{"Bad request":{"summary":"Response for invalid requests","description":"FORBIDDEN","value":{"errors":[{"code":403,"detail":"User is unauthorised to perform this action","path":"/v1/availability/quantities","title":"Access Forbidden","logreg":""}]}}}}}},"404":{"description":"Not found (URL is invalid)","content":{"application/json":{"examples":{"URL is invalid":{"value":{"message":"Not Found"}}}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url 'https://api.otto.market/v1/availability/quantities?limit=SOME_INTEGER_VALUE&page=SOME_INTEGER_VALUE&cursor=c2t1NDM%3D' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET 'https://api.otto.market/v1/availability/quantities?limit=SOME_INTEGER_VALUE&page=SOME_INTEGER_VALUE&cursor=c2t1NDM%3D' \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v1/availability/quantities/{sku}":{"get":{"security":[{"bearerAuth":["availability"]}],"tags":["Availability-V1"],"summary":"Get quantity for a sku","description":"Fetch a single available quantity by its unique sku name.","operationId":"Availability-V1__getAvailableQuantityBySku","parameters":[{"name":"Authorization","in":"header","description":"Access Token","required":true,"example":"Bearer access_token","schema":{"type":"string"}},{"name":"sku","in":"path","required":true,"description":"The sku for the available quantity","schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/AvailableQuantitySingleResponseDTO__Availability-V1"}}}},"403":{"description":"Unauthorized to access","content":{"application/json":{"examples":{"Bad request":{"summary":"Response for invalid requests","description":"FORBIDDEN","value":{"errors":[{"code":403,"detail":"User is unauthorised to perform this action","path":"/v1/availability/quantities","title":"Access Forbidden","logreg":""}]}}}}}},"404":{"description":"Requested sku was unknown (send a quantity update for the product before trying to retrieve it)","content":{"application/json":{"examples":{"Bad request":{"summary":"Requested sku was unknown","description":"NOT FOUND","value":{"errors":[{"code":404,"detail":"No record found for requested sku","path":"/v1/availability/quantities/{sku}","title":"NOT FOUND","logreg":""}]}}}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url https://api.otto.market/v1/availability/quantities/%7Bsku%7D \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET https://api.otto.market/v1/availability/quantities/%7Bsku%7D \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v1/availability/product-delivery-information":{"post":{"security":[{"bearerAuth":["availability"]}],"tags":["Availability-V1"],"summary":"Update product delivery information","operationId":"Availability-V1__storeProductDeliveryInformationUsingPOST","parameters":[{"name":"Authorization","in":"header","description":"Access Token","required":true,"example":"Bearer access_token","schema":{"type":"string"}}],"requestBody":{"content":{"application/json;charset=UTF-8":{"schema":{"type":"array","minItems":1,"maxItems":200,"items":{"$ref":"#/components/schemas/ProductDeliveryInformationRequestDTO__Availability-V1"}}}},"required":true},"responses":{"202":{"description":"Ok","content":{"application/json;charset=UTF-8":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"OK"}}}}}},"207":{"description":"Multi Status","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProductDeliveryInformationMultiStatusResponse__Availability-V1"}}}},"400":{"description":"Bad Request
1. If any of the mandatory attribute missing in request body
2. If request body attributes type/format is wrong
3. Duplicate sku records exists in the request
4. All items have invalid Sku or shipping profile ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIErrorResponseForBadRequest__Availability-V1"}}}},"401":{"description":"Unauthorized to access"},"403":{"description":"Forbidden (Invalid token)","content":{"application/json":{"examples":{"Token is invalid":{"value":{"message":"Forbidden"}}}}}},"404":{"description":"Not found (URL is invalid)","content":{"application/json":{"examples":{"URL is invalid":{"value":{"message":"Not Found"}}}}}},"413":{"description":"Payload too large","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ApiErrorResponseForPayloadTooLarge__Availability-V1"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIErrorResponseForInternalServer__Availability-V1"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request POST \\\n --url https://api.otto.market/v1/availability/product-delivery-information \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http POST https://api.otto.market/v1/availability/product-delivery-information \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]},"get":{"security":[{"bearerAuth":["availability"]}],"tags":["Availability-V1"],"summary":"Get product delivery information from a partner","description":"Retrieve sku and shipping profile mapping.The maximum number of returned items is limited to 200. If there are more items, a cursor field is returned to get the next results.","operationId":"Availability-V1__getProductDeliveryInformation","parameters":[{"name":"Authorization","in":"header","description":"Access Token","required":true,"example":"Bearer access_token","schema":{"type":"string"}},{"name":"limit","in":"query","description":"The maximum number of shipping profile and sku mappings to be returned in each response.","deprecated":true,"required":false,"schema":{"type":"integer","format":"int32","default":200}},{"name":"cursor","in":"query","description":"Cursor for paging requests. If a cursor is provided, the only other request parameter being considered is 'limit'.

Note:The cursor value must remain unchanged from the previous request.","required":false,"schema":{"type":"string","example":"c2t1NDM="}}],"responses":{"200":{"description":"The sku(s)-shipping profile(s) mapping of the partner","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/GetAllProductDeliveryInfoResponse__Availability-V1"}}}},"403":{"description":"Forbidden (Invalid token)","content":{"application/json":{"examples":{"Token is invalid":{"value":{"message":"Forbidden"}}}}}},"404":{"description":"Not found (URL is invalid)","content":{"application/json":{"examples":{"URL is invalid":{"value":{"message":"Not Found"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIErrorResponseForInternalServer__Availability-V1"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url 'https://api.otto.market/v1/availability/product-delivery-information?limit=SOME_INTEGER_VALUE&cursor=c2t1NDM%3D' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET 'https://api.otto.market/v1/availability/product-delivery-information?limit=SOME_INTEGER_VALUE&cursor=c2t1NDM%3D' \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}},"/v1/availability/product-delivery-information/{sku}":{"get":{"security":[{"bearerAuth":["availability"]}],"tags":["Availability-V1"],"summary":"Get product delivery information for a SKU","description":"This GET API endpoint is to get a shipping profile id and processing time for given sku\n","operationId":"Availability-V1__getDeliveryInformationBySKU","parameters":[{"name":"Authorization","in":"header","description":"Access Token","required":true,"example":"Bearer access_token","schema":{"type":"string"}},{"name":"sku","in":"path","description":"the sku in string format","required":true,"allowEmptyValue":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The delivery information of the sku","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProductDeliveryInformationResponseDTO__Availability-V1"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden (Invalid token)","content":{"application/json":{"examples":{"Token is invalid":{"value":{"message":"Forbidden"}}}}}},"404":{"description":"Not found.
1. If request path is not /v1/availability/product-delivery-information/
2. If sku is not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIErrorResponseForNotFound__Availability-V1"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIErrorResponseForInternalServer__Availability-V1"}}}}},"deprecated":false,"x-codeSamples":[{"lang":"Shell + Curl","source":"curl --request GET \\\n --url https://api.otto.market/v1/availability/product-delivery-information/%7Bsku%7D \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"},{"lang":"Shell + Httpie","source":"http GET https://api.otto.market/v1/availability/product-delivery-information/%7Bsku%7D \\\n Authorization:'Bearer REPLACE_BEARER_TOKEN'"}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"ActiveStatus__Products-V3":{"properties":{"sku":{"description":"Partner-unique identifier for a product variation provided by the partner","example":"82388894-5883-488","type":"string"},"active":{"description":"The product variation is supposed to be active or not","example":true,"type":"boolean"},"lastModified":{"description":"the ISO8601 timestamp of the last modification of the active status","example":"2019-06-18T06:12:36Z","format":"date-time","readOnly":true,"type":"string"}},"type":"object"},"ActiveStatusListRequest__Products-V3":{"properties":{"status":{"items":{"$ref":"#/components/schemas/ActiveStatus__Products-V3"},"type":"array"}},"type":"object"},"ActiveStatusListResponse__Products-V3":{"properties":{"status":{"items":{"$ref":"#/components/schemas/ActiveStatus__Products-V3"},"type":"array"},"links":{"description":"a list of links that can be used for pagination (among others).","items":{"$ref":"#/components/schemas/ActiveStatusListResponseLink__Products-V3"},"type":"array"}},"type":"object"},"ActiveStatusListResponseLink__Products-V3":{"properties":{"rel":{"description":"link relation type","enum":["self","prev","next"],"example":"self","type":"string"},"href":{"description":"the linked reference as URI","example":"/v3/products/active-status?page=0&limit=100","type":"string"}},"type":"object"},"AdditionalRequirement__Products-V3":{"properties":{"name":{"description":"the name of the product attribute.","example":"normPriceInfo","type":"string"},"jsonPath":{"description":"the JSON path leading to the specific product attribute.","example":"$.productVariations[*].pricing.normPriceInfo","type":"string"},"description":{"description":"a brief human readable description of the requirement","example":"Die Produktkategorie fällt unter die Preisangabenverordnung, weshalb ein Grundpreis angegeben werden muss.","type":"string"},"reference":{"description":"a link to the official documentation that describes the requirement","example":"https://api.otto.market/docs/03_Products/v3/products-interface.html","type":"string"},"condition":{"$ref":"#/components/schemas/Condition__Products-V3"},"featureRelevance":{"description":"a list of feature relevances that can describe the reason for the requirement.","example":["LEGAL"],"items":{"type":"string"},"type":"array"}},"type":"object"},"Attribute__Products-V3":{"properties":{"name":{"description":"The name of the describing attribute, like 'color' or 'size'.","example":"Bundweite","type":"string"},"values":{"description":"The value for the given name, like 'blue' or 'S', as a JSON array","example":["34"],"items":{"type":"string"},"type":"array"},"additional":{"description":"true, if the attribute is not defined by the marketplace.","example":false,"type":"boolean"}},"type":"object"},"AttributeDefinition__Products-V3":{"properties":{"name":{"description":"the name of the attribute. This attribute name has to be used within the product description.","example":"Durchmesser","type":"string"},"attributeGroup":{"description":"title of the attributes displayed in the product details in the shop.","example":"Maße & Gewicht","type":"string"},"type":{"description":"defines the format of the attribute value, such as string, integer, etc.","example":"FLOAT","type":"string"},"multiValue":{"description":"if the value is true, several values can be transferred to this attribute (polyvalence attribute); otherwise, only a single value may be transferred to this attribute.","example":true,"type":"boolean"},"unit":{"description":"the values must be transferred in the specified unit.","example":"cm","type":"string"},"unitDisplayName":{"description":"the value gets displayed with this unit in the shop.","example":"Zentimeter","type":"string"},"allowedValues":{"description":"only the listed values are permitted for the attribute.","example":"natur bunt grau ...","items":{"type":"string"},"type":"array"},"featureRelevance":{"description":"describes what the attribute can be used for and where it gets displayed in the shop.","example":"FILTER","items":{"type":"string"},"type":"array"},"relatedMediaAssets":{"description":"mandatory media assets for the category","items":{"type":"string"},"type":"array"},"relevance":{"description":"the relevance of the attribute.","example":"HIGH","type":"string"},"description":{"description":"additional information for the attribute.","example":"some textual description","type":"string"},"exampleValues":{"description":"example values for the attribute.","example":"Edelstahl Aluminium Stahl","items":{"type":"string"},"type":"array"},"recommendedValues":{"description":"use the listed values to get full navigation and filter features on otto.de. If no suitable value exists, then enter your own value.","example":"modern klassisch Landhaus Vintage","items":{"type":"string"},"type":"array"},"reference":{"description":"reference to further documentation.","example":"http://wikipedia.de/something","type":"string"}},"type":"object"},"Brand__Products-V3":{"properties":{"id":{"description":"the id value of the brand which you have to use with your product data uploads!","example":"K5J8PJFR","type":"string"},"name":{"description":"the name of the brand as it is known on the OTTO marketplace. Use this name to find the brand of your products in the list of available brands, but don't use it in your product data - use only the id value of the brand!","example":"adidas","type":"string"},"logo":{"description":"If a brand logo image is existing, you can find the URL of it here.","example":"https://brandlogos.foo.org/logo-xyz.jpg","type":"string"},"usable":{"description":"If this value if ``false`` you are not allowed to use this brand for products you like to sell on the OTTO marketplace. If the value is ``true`` you might use this brand.","example":true,"type":"boolean"}},"type":"object"},"BrandListResponse__Products-V3":{"properties":{"brands":{"items":{"$ref":"#/components/schemas/Brand__Products-V3"},"type":"array"},"links":{"description":"a list of links that can be used for pagination (among others).","items":{"$ref":"#/components/schemas/BrandListLink__Products-V3"},"type":"array"}},"type":"object"},"BrandListLink__Products-V3":{"properties":{"rel":{"description":"link relation type","enum":["self","prev","next"],"example":"self","type":"string"},"href":{"description":"the linked reference as URI","example":"/v3/products/brands?page=0&limit=100","type":"string"}},"type":"object"},"CategoryGroup__Products-V3":{"properties":{"categoryGroup":{"description":"a category group defines a list of categories and the market place attributes for these categories.","type":"string"},"categories":{"description":"the list of the categories for this category group.","example":"Farbe","items":{"type":"string"},"type":"array"},"variationThemes":{"description":"overview of all attributes that can be used to create variantions.","items":{"type":"string"},"type":"array"},"title":{"description":"shows how our product title is built","type":"string"},"attributes":{"description":"list of the market place attributes for the categories of this group.","items":{"$ref":"#/components/schemas/AttributeDefinition__Products-V3"},"type":"array"},"createdAt":{"description":"ISO8601 creation date of the category.","example":"2021-07-02T01:35:57.181Z","format":"date-time","type":"string"},"lastModified":{"description":"ISO8601 last modification date of the category.","example":"2021-07-02T01:35:57.181Z","format":"date-time","type":"string"},"additionalRequirements":{"description":"a list of general requirements for certain product attributes that apply to all categories in the category group","items":{"$ref":"#/components/schemas/AdditionalRequirement__Products-V3"},"type":"array"}},"type":"object"},"CategoryGroups__Products-V3":{"properties":{"categoryGroups":{"description":"a list of the category groups defined on the OTTO market place.","items":{"$ref":"#/components/schemas/CategoryGroup__Products-V3"},"type":"array"},"links":{"description":"a list of links that can be used for pagination (among others).","items":{"$ref":"#/components/schemas/CategoryGroupsLink__Products-V3"},"type":"array"}},"type":"object"},"Condition__Products-V3":{"properties":{"name":{"description":"the name of an attribute.","type":"string"},"jsonPath":{"description":"the JSON path that leads to the attribute value.","type":"string"},"value":{"description":"the value of the attribute to which the requirement applies.","type":"string"}},"type":"object"},"CategoryGroupsLink__Products-V3":{"properties":{"rel":{"description":"link relation type","enum":["self","prev","next"],"example":"self","type":"string"},"href":{"description":"the linked reference as URI","example":"/v3/products/categories?page=0&limit=100","type":"string"}},"type":"object"},"ContentChange__Products-V3":{"properties":{"sku":{"type":"string"},"ean":{"type":"string"},"productReference":{"type":"string"},"shopLink":{"type":"string"},"lastContentChange":{"format":"date-time","type":"string"}},"type":"object"},"ContentChangesApiResult__Products-V3":{"properties":{"contentChanges":{"items":{"$ref":"#/components/schemas/ContentChange__Products-V3"},"type":"array"},"links":{"description":"a list of links that can be used for pagination.","items":{"$ref":"#/components/schemas/ContentChangesLink__Products-V3"},"type":"array"}},"type":"object"},"Delivery__Products-V3":{"description":"A container holding attributes to describe the way you ship the orders to the customers","properties":{"type":{"description":"The type of the delivery as described in the enumeration. Right now we only support PARCEL, FORWARDER_PREFERREDLOCATION, FORWARDER_CURBSIDE and FORWARDER_HEAVYDUTY.","enum":["PARCEL","FORWARDER_PREFERREDLOCATION","FORWARDER_CURBSIDE","FORWARDER_HEAVYDUTY"],"example":"PARCEL","type":"string"},"deliveryTime":{"description":"Mandatory. The delivery time in days, with allowed values from 1 to 999.","example":1,"format":"int32","type":"integer"}},"required":["deliveryTime","type"],"type":"object"},"Link__Products-V3":{"properties":{"rel":{"description":"link relation type","enum":["self","prev","next"],"example":"self","type":"string"},"href":{"description":"the linked reference as URI","example":"/v3/products?page=0&limit=100","type":"string"}},"type":"object"},"ContentChangesLink__Products-V3":{"properties":{"rel":{"description":"link relation type","enum":["self","prev","next"],"example":"self","type":"string"},"href":{"description":"the linked reference as URI","example":"/v3/products/content-changes?page=0&limit=100","type":"string"}},"type":"object"},"LinkRelation__Products-V3":{"type":"object"},"Logistics__Products-V3":{"description":"In case of using the logistic service of our marketplace, here you may provide information about the packaging of the goods","properties":{"packingUnitCount":{"description":"The number of packing units.","example":3,"format":"int32","type":"integer"},"packingUnits":{"description":"The measurements of the packing units in g and mm.","items":{"$ref":"#/components/schemas/PackingUnit__Products-V3"},"type":"array"}},"type":"object"},"MarketPlaceStatus__Products-V3":{"properties":{"sku":{"description":"Partner-unique identifier for a product variation provided by the partner","example":"82388894-5883-488","type":"string"},"moin":{"description":"Is an identifier, generated by the OTTO marketplace, for a product variation together with the associated content. Is used in the context of \"Wettbewerb am Artikel\" to confirm the content of the existing variation and its correctness and to put the own offer live for this variation.","example":"M00A1234BC","type":"string"},"status":{"description":"the status of the variation on the OTTO market place","enum":["PENDING","ONLINE","RESTRICTED","REJECTED","INACTIVE"],"example":"RESTRICTED","type":"string"},"errors":{"description":"errors that occurred when processing the variation","items":{"$ref":"#/components/schemas/MarketPlaceStatusError__Products-V3"},"type":"array"},"information":{"description":"information for product optimization on the OTTO market place","items":{"$ref":"#/components/schemas/MarketPlaceStatusInformation__Products-V3"},"type":"array"},"links":{"description":"contains the link to the partner variation data and to the product in OTTO shop","items":{"$ref":"#/components/schemas/MarketPlaceStatusLink__Products-V3"},"type":"array"},"lastModified":{"description":"last change of the marketplace status as ISO8601 date","example":"2021-07-02T09:30:52.093Z","format":"date-time","type":"string"}},"type":"object"},"MarketPlaceStatusApiResult__Products-V3":{"properties":{"marketPlaceStatus":{"items":{"$ref":"#/components/schemas/MarketPlaceStatus__Products-V3"},"type":"array"},"links":{"description":"a list of links that can be used for pagination.","items":{"$ref":"#/components/schemas/MarketPlaceStatusApiLink__Products-V3"},"type":"array"}},"type":"object"},"MarketPlaceStatusError__Products-V3":{"properties":{"code":{"description":"code to identify the error","example":"800020 - PRODUCTDATASHEET_MISSING","type":"string"},"title":{"description":"short description of the error","example":"Das Produktdatenblatt fehlt.","type":"string"}},"type":"object"},"MarketPlaceStatusInformation__Products-V3":{"properties":{"code":{"description":"code to identify the information","example":"300007 - INCOMPLETE_MEDIA_ASSET_IMPORT","type":"string"},"title":{"description":"short description of the information","example":"Die Bilder werden zur Zeit verarbeitet. Wir bitten um etwas Geduld. Wenn der Status sich innerhalb der nächsten 24 Stunden nicht verändert, wenden Sie sich bitte an support@otto.market.","type":"string"}},"type":"object"},"MarketPlaceStatusLink__Products-V3":{"properties":{"rel":{"description":"link relation type","enum":["variation","shop"],"example":"shop","type":"string"},"href":{"description":"the linked reference as URI","example":"https://www.otto.de/p/myProduct","type":"string"}},"type":"object"},"MarketPlaceStatusApiLink__Products-V3":{"properties":{"rel":{"description":"link relation type","enum":["self","prev","next"],"example":"self","type":"string"},"href":{"description":"the linked reference as URI","example":"/v3/products/marketplace-status?page=0&limit=100","type":"string"}},"type":"object"},"MediaAsset__Products-V3":{"properties":{"type":{"description":"The type of the provided media asset. At least one media asset of type 'IMAGE' must be provided. The number of media assets of type 'IMAGE' is not limited.","enum":["IMAGE","DIMENSIONAL_DRAWING","COLOR_VARIANT","ENERGY_EFFICIENCY_LABEL","MATERIAL_SAMPLE","PRODUCT_DATASHEET","USER_MANUAL","MANUFACTURER_WARRANTY","SAFETY_DATASHEET","ASSEMBLY_INSTRUCTIONS","WARNING_LABEL"],"example":"IMAGE","type":"string"},"location":{"description":"The partners location of the media asset as a valid URL (see http://www.ietf.org/rfc/rfc2396.txt and http://www.ietf.org/rfc/rfc2732.txt) with a maximum length of 2083 characters. OTTO market will use the link for downloading the media asset and providing it to otto.de. Please note that the image has to be of type JPG or PNG with a RGB color space an a minimum size of 500x1000 pixel and a maximum width of 4500 pixel.","example":"http://apartners.url/image-location","format":"uri","type":"string"}},"required":["location","type"],"type":"object"},"MonetaryAmount__Products-V3":{"properties":{"amount":{"description":"Holds the value of the monetary amount expressed in a currency, e.g. euros. The number format expects a decimal point, like 10.99. Numbers without a decimal point are taken as a unit of the given currency, e.g. 10 is taken as 10 euros. The value has to have no more than 2 decimal places. If you specify more decimal places, the product variation will be rejected. The same applies, if you use other characters than digits and an optional decimal point, e.g. '2E+4'","example":19.95,"type":"number"},"currency":{"description":"Holds the currency of the monetary amount expressed as a shortcut according to ISO 4217 and http://publications.europa.eu/code/de/de-5000700.htm. NOTE: Currently the only allowed currency code is \"EUR\". All other currency codes will be rejected.","example":"EUR","type":"string"}},"type":"object"},"NormPriceInfo__Products-V3":{"description":"The information about normed prices, must be provided completely, or not at all. The representation of the normprice has to contain the following values for normAmount and normUnit: 1 pcs,1 sqm,1 kg,1 l,1 m,100 ml,100 g,1 g,1000 g,1 pair,1 RM,1 dm3.","properties":{"normAmount":{"description":"The norm packaging size.","enum":[1,100,1000],"example":100,"format":"int32","type":"integer"},"normUnit":{"description":"The name of the unit the norm price is based on.","enum":["Stk","qm","kg","l","m","ml","g","Paar","RM","dm3"],"example":"g","type":"string"},"salesAmount":{"description":"The packaging size of the sales unit.","example":500,"type":"number"},"salesUnit":{"description":"The name of the unit the sales price is based on.","enum":["Stk","qm","kg","l","m","ml","g","Paar","RM","dm3"],"example":"g","type":"string"}},"type":"object"},"PackingUnit__Products-V3":{"properties":{"weight":{"description":"The weight of a packing unit in grams.","example":365,"format":"int32","type":"integer"},"width":{"description":"The width of a packing unit in millimeters.","example":600,"format":"int32","type":"integer"},"height":{"description":"The height of a packing unit in millimeters.","example":200,"format":"int32","type":"integer"},"length":{"description":"The depth of a packing unit in millimeters.","example":300,"format":"int32","type":"integer"}},"type":"object"},"PriceApiResult__Products-V3":{"properties":{"variationPrices":{"items":{"$ref":"#/components/schemas/SkuPricing__Products-V3"},"type":"array"},"links":{"description":"a list of links that can be used for pagination.","items":{"$ref":"#/components/schemas/PriceApiResultLink__Products-V3"},"type":"array"}},"type":"object"},"Pricing__Products-V3":{"description":"this container holds attributes for the different price types, currency and tax related information","properties":{"standardPrice":{"$ref":"#/components/schemas/MonetaryAmount__Products-V3"},"vat":{"description":"The value added tax that is included in the sales price.","enum":["FULL","REDUCED","FREE"],"example":"FULL","type":"string"},"msrp":{"$ref":"#/components/schemas/MonetaryAmount__Products-V3"},"sale":{"$ref":"#/components/schemas/Sale__Products-V3"},"normPriceInfo":{"$ref":"#/components/schemas/NormPriceInfo__Products-V3"}},"required":["standardPrice","vat"],"type":"object"},"PriceApiResultLink__Products-V3":{"properties":{"rel":{"description":"link relation type","enum":["self","prev","next"],"example":"self","type":"string"},"href":{"description":"the linked reference as URI","example":"/v3/products/prices?page=0&limit=100","type":"string"}},"type":"object"},"ProductDescription__Products-V3":{"description":"Extensive description of the product.","properties":{"category":{"description":"Denotes the assortment type of the product, like 'bag' or 'shirt'. Mandatory. Must be identical for all variants of a product. Must be present in the Category service offered via Category endpoint","example":"Outdoorjacke","type":"string"},"brandId":{"description":"Denotes the brand ID of a product. Brands and the mapping of their names to brand Ids should be done using the brand endpoint. Must be present in the Brand service offered via Brand endpoint. Must be identical for all variants of a product.","example":"CMWBBRW2","type":"string"},"productLine":{"description":"Denotes the proper name of a product, like '501'. May contain a maximum of 70 characters. If provided, it must be identical for all variants of a product.","example":"501","type":"string"},"manufacturer":{"description":"Denotes the manufacturer of a product. If provided, it must be identical for all variants of a product.","example":"3M","type":"string"},"productionDate":{"description":"Denotes the ISO8601 date of manufacture of a product variant.","example":"2021-07-02T09:30:52.093Z","format":"date-time","type":"string"},"multiPack":{"description":"If the product variant is part of a set: 'true'; otherwise 'false'","example":true,"type":"boolean"},"bundle":{"description":"If the product variant is part of a bundle: 'true'; otherwise 'false'","example":false,"type":"boolean"},"fscCertified":{"description":"If the product variant is certified by the Forest Stewardship Council: 'true'; otherwise 'false'","example":true,"type":"boolean"},"disposal":{"description":"If true, otto.de will present information about the disposal of the product (or parts of it).","example":false,"type":"boolean"},"productUrl":{"description":"Refers to a representation of the product variant in a shop of the partner. Should be a valid URL.","example":"http://myproduct.somewhere.com/productname/","type":"string"},"description":{"description":"Represents a textual description of a product variant. May contain HTML elements. Should contain less than 2000 characters. Relevant for SEO.","example":"

Some example words...in bold...some more

","type":"string"},"bulletPoints":{"description":"May contain a minimum of 3 and a maximum of 180 characters.","example":["My top key information..."],"items":{"type":"string"},"type":"array"},"attributes":{"description":"Lists all the descriptive information about a product variant a partner can provide. Must be provided in the form of a key values pair. Will be validated against the AttributeDefinitions from Category endpoint provided by Otto market.","items":{"$ref":"#/components/schemas/Attribute__Products-V4"},"type":"array"}},"required":["brandId","category"],"type":"object"},"ProductLink__Products-V4":{"type":"object"},"ProductProcessProgress__Products-V4":{"properties":{"state":{"description":"the current state of the process","enum":["pending","done"],"type":"string"},"message":{"description":"a human-readable message describing the current state of the process","type":"string"},"total":{"description":"the total work to complete for this process","format":"int32","type":"integer","example":7},"progress":{"description":"the fraction of work that is already completed, as compared to the total work","format":"int32","type":"integer","example":7},"succeeded":{"description":"the number of successfully processed variations","format":"int32","type":"integer","example":4},"failed":{"description":"the number of failed processed variations","format":"int32","type":"integer","example":2},"unchanged":{"description":"the number of unchanged and not processed variations","format":"int32","type":"integer","example":1},"pingAfter":{"description":"recommendation when to poll this resource again to receive a meaningful update - ISO8601 date","example":"2020-05-13T10:40:01.815Z","format":"date-time","type":"string"},"links":{"description":"a list of links that can be used to access detailed information about the process result","items":{"$ref":"#/components/schemas/ProductProcessResultLink__Products-V4"},"type":"array"}},"type":"object"},"ProductProcessResult__Products-V4":{"properties":{"results":{"items":{"$ref":"#/components/schemas/ProductProcessTaskResult__Products-V4"},"type":"array"}},"type":"object"},"ProductProcessResultLink__Products-V4":{"properties":{"rel":{"description":"link relation type","enum":["self","failed","succeeded","unchanged"],"type":"string","example":"self"},"href":{"description":"the linked reference as URI","example":"/v4/products/update-tasks/11111111-0003-4444-9999-bbbbbbbbbbbbb","type":"string"}},"type":"object"},"ProductProcessTaskError__Products-V4":{"properties":{"code":{"type":"string"},"title":{"type":"string"},"path":{"type":"string"},"jsonPath":{"type":"string"},"logref":{"type":"string"}},"type":"object"},"ProductProcessTaskResult__Products-V4":{"properties":{"variation":{"type":"string"},"errors":{"items":{"$ref":"#/components/schemas/ProductProcessTaskError__Products-V4"},"type":"array"}},"type":"object"},"ProductVariation__Products-V4":{"properties":{"productReference":{"description":"The productReference groups all variations, that you want to combine into one product. This is not visible to the customer. The productReference can be freely assigned and may consist of maximum 50 characters. You can only use the productReference once within your product catalog. You should therefore use a value that makes sense for all variations of the product and does not refer to any specifics of a particular variation. You will find the product reference, for example, in the product overview in the portal.","example":"UBN-11779","type":"string"},"sku":{"description":"Identifier for a product variation, provided by the partner, must be unique for a partner. It is mandatory, may consist of a maximum of 50 characters and must not contain leading or trailing spaces or non-printable Unicode control characters.","example":"3858389911564","type":"string"},"ean":{"description":"External identifier of a product, must be unique in a partner assortment, must not start with a 2.","example":"3858389911564","type":"string"},"pzn":{"description":"Pharmazentralnummer, a german standard for identifying pharmaceutical products.","example":"PZN-4908802","type":"string"},"mpn":{"description":"Manufacturer part number, may consist of a maximum of 50 characters.","example":"H2G2-42","type":"string"},"moin":{"description":"Is an identifier, generated by the OTTO marketplace, for a product variation together with the associated content. Is used in the context of \"Wettbewerb am Artikel\" to confirm the content of the existing variation and its correctness and to put the own offer live for this variation.","example":"M00A1234BC","type":"string"},"releaseDate":{"description":"ISO8601 Date (e.g. 2024-08-01T08:00:00+0100) on which the product is released by the manufacturer, e.g. computer games.","example":"2019-10-19T00:00:00Z","format":"date-time","type":"string"},"productDescription":{"$ref":"#/components/schemas/ProductDescription__Products-V4"},"mediaAssets":{"description":"A list of media assets describing this product variation. Currently these may only be static images of the types JPG or PNG with a RGB color space. Furthermore the images have to have a minimum size of 500 x 1000 pixel and a maximum width of 4500 pixel.","items":{"$ref":"#/components/schemas/MediaAsset__Products-V4"},"type":"array"},"order":{"$ref":"#/components/schemas/Order__Products-V4"},"pricing":{"$ref":"#/components/schemas/Pricing__Products-V4"},"logistics":{"$ref":"#/components/schemas/Logistics__Products-V4"},"productSafety":{"$ref":"#/components/schemas/ProductSafety__Products-V4"}},"required":["ean","productReference","sku","productDescription","pricing","mediaAssets","productSafety"],"type":"object"},"ProductVariationApiResult__Products-V4":{"properties":{"productVariations":{"items":{"$ref":"#/components/schemas/ProductVariation__Products-V4"},"type":"array"},"links":{"description":"a list of links that can be used for pagination.","items":{"$ref":"#/components/schemas/Link__Products-V4"},"type":"array"}},"type":"object"},"Sale__Products-V4":{"properties":{"salePrice":{"$ref":"#/components/schemas/MonetaryAmount__Products-V4"},"startDate":{"description":"The start ISO8601 date for the sales.","example":"2019-10-19T09:30:00Z","format":"date-time","type":"string"},"endDate":{"description":"The end ISO8601 date for the sales.","example":"2019-10-19T09:30:00Z","format":"date-time","type":"string"}},"type":"object"},"SkuPricing__Products-V4":{"properties":{"sku":{"description":"Partner-unique identifier for a product variation provided by the partner.","type":"string"},"standardPrice":{"$ref":"#/components/schemas/MonetaryAmount__Products-V4"},"sale":{"$ref":"#/components/schemas/Sale__Products-V4"}},"required":["sku","standardPrice"],"type":"object"},"MaxOrderQuantity__Products-V4":{"description":"The maximum number of items a consumer may order during a specified time period. E.g. max 10 items every 7 days.","properties":{"quantity":{"description":"The maximum number of items a consumer may order during a specified time period. Quantity with allowed values from 1 to 50.","example":10,"type":"integer"},"periodInDays":{"description":"The period of time in days during which a consumer may order the specified maximum number of items. Period in days with allowed values from 1 to 90.","example":7,"type":"integer"}},"type":"object"},"Order__Products-V4":{"description":"A Container holding order constraints","properties":{"maxOrderQuantity":{"$ref":"#/components/schemas/MaxOrderQuantity__Products-V4"}},"type":"object"},"ProductSafety__Products-V4":{"description":"Should be used for providing information about the manufacturer of the product.","properties":{"name":{"description":"The company name of the manufacturer or the importer placing the product into the European Economic Area (EEA) with a maximum length of 100 characters.","example":"Die Musterfirma GmbH","type":"string"},"address":{"description":"The complete address including street, postal code, city, country, without any formatting, comma separation, no line breaks, with a maximum length of 200 characters.","example":"Musterstraße 1, 12345, Musterstadt, Deutschland","type":"string"},"regionCode":{"description":"Allowed values are the country codes of the European Economic Area (EEA) members in ISO-3166 Alpha-2 format. Important for validation of the address.","example":"DE","type":"string"},"email":{"description":"A valid and complete email address with a maximum length of 100 characters. **Mandatory** if no url is specified.","example":"info@die-musterfirma.de","type":"string"},"url":{"description":"Valid URL (see http://www.ietf.org/rfc/rfc2396.txt and http://www.ietf.org/rfc/rfc2732.txt) with a maximum length of 200 characters to the contact information of the manufacturer or importer. **Mandatory** if no email is specified.","example":"https://musterfirma/kontakt-information","type":"string"},"phone":{"description":"A valid phone number with a maximum length of 20 characters.","example":"+ 49 40 123456789","type":"string"}},"required":["name","address"],"type":"object"},"Address__Orders-V4":{"type":"object","description":"Address","properties":{"addition":{"type":"string","description":"The addition","example":"Hinterm Haus"},"city":{"type":"string","description":"The city","example":"Musterstadt"},"countryCode":{"type":"string","description":"The country in ISO-3166-1 Alpha-3 format","example":"DEU"},"email":{"type":"string","description":"The e-mail address; if part of the delivery address is in plain text; if part of the invoice address it's a pseudonymized e-mail address","example":"test@example.com"},"firstName":{"type":"string","description":"The firstName","example":"Max"},"houseNumber":{"type":"string","description":"The house number","example":"17"},"lastName":{"type":"string","description":"The lastName","example":"Mustermann"},"phoneNumber":{"type":"string","description":"The phone number","example":"0491234567890"},"salutation":{"type":"string","description":"The salutation (MR, MS, COMPANY, UNKNOWN)","example":"MR"},"street":{"type":"string","description":"The street","example":"Musterstraße"},"title":{"type":"string","description":"The title","example":"Dr."},"zipCode":{"type":"string","description":"The zipCode","example":"12345"}},"required":["city","countryCode","firstName","houseNumber","lastName","salutation","street","zipCode"],"title":"Address"},"Amount__Orders-V4":{"type":"object","description":"Amount","properties":{"amount":{"type":"number","description":"The amount","example":15.99},"currency":{"type":"string","description":"The currency in ISO_4217 format","example":"EUR","minLength":1}},"required":["amount","currency"]},"Dimension__Orders-V4":{"type":"object","description":"Dimension","properties":{"displayName":{"type":"string","description":"The type description written out for displaying purposes","example":"Farbe"},"type":{"type":"string","description":"The standardized type description","example":"color"},"value":{"type":"string","description":"The actual value of the dimension","example":"schwarz"}},"title":"Dimension"},"InitialDeliveryFee__Orders-V4":{"type":"object","description":"InitialDeliveryFee","properties":{"deliveryFeeAmount":{"$ref":"#/components/schemas/Amount__Orders-V4"},"name":{"type":"string","description":"The type of this delivery fee","example":"DELIVERY_FEE_STANDARD"},"positionItemIds":{"type":"array","description":"The position item ids to which this delivery fee applies","example":["1cdef481-683c-4a4c-bf42-fa7f6bb00933","09532b32-6f4e-4277-988b-f5f721ca13c4"],"items":{"type":"string","description":"The position item ids to which this delivery fee applies","example":"[\"1cdef481-683c-4a4c-bf42-fa7f6bb00933\",\"09532b32-6f4e-4277-988b-f5f721ca13c4\"]"}},"vatRate":{"type":"number","description":"The highest VAT rate of the products of all the position items","example":19}},"required":["deliveryFeeAmount","name","positionItemIds","vatRate"],"title":"InitialDeliveryFee"},"InitialDiscount__Orders-V4":{"type":"object","description":"InitialDiscount","properties":{"discountAmount":{"$ref":"#/components/schemas/Amount__Orders-V4"},"discountId":{"type":"string","description":"The id of this discount","example":"9978"},"discountName":{"type":"string","description":"The name of this discount","example":"15% auf Technik"},"name":{"type":"string","description":"The type of this discount","example":"DISCOUNT"},"positionItemIds":{"type":"array","description":"The position item ids to which this discount applies","example":["1cdef481-683c-4a4c-bf42-fa7f6bb00933","09532b32-6f4e-4277-988b-f5f721ca13c4"],"items":{"type":"string","description":"The position item ids to which this discount applies","example":"[\"1cdef481-683c-4a4c-bf42-fa7f6bb00933\",\"09532b32-6f4e-4277-988b-f5f721ca13c4\"]"}},"vatRate":{"type":"number","description":"The highest VAT rate between discounted products","example":19}},"required":["discountAmount","discountId","discountName","name","positionItemIds","vatRate"],"title":"InitialDiscount"},"Link__Orders-V4":{"type":"object","description":"A link to various resources. A link can have different meanings and targets. The type of relation is specified with the property 'rel'.","properties":{"href":{"type":"string","description":"The url of the link","example":"/v4/orders/12345678,/v4/orders/?nextCursor=bsdjfvbkjdfv"},"rel":{"type":"string","description":"The relation type of the link. See also https://www.iana.org/assignments/link-relations/link-relations.xhtml. The relation type 'next' is used for paging. The relation type 'self' refers to the url of the resource","example":"next,self,describedby"}},"title":"Link"},"OrderLifecycleInformation__Orders-V4":{"type":"object","description":"OrderLifecycleInformation","properties":{"lifecycleChangeDate":{"type":"string","format":"date-time","description":"The date, when this order has been placed"}},"required":["lifecycleChangeDate"],"title":"OrderLifecycleInformation"},"PartnerOrder__Orders-V4":{"type":"object","properties":{"deliveryAddress":{"$ref":"#/components/schemas/Address__Orders-V4"},"initialDeliveryFees":{"type":"array","description":"The delivery fees on customer checkout","items":{"$ref":"#/components/schemas/InitialDeliveryFee__Orders-V4"}},"initialDiscounts":{"type":"array","description":"The initial discounts on customer checkout","items":{"$ref":"#/components/schemas/InitialDiscount__Orders-V4"}},"invoiceAddress":{"$ref":"#/components/schemas/Address__Orders-V4"},"lastModifiedDate":{"type":"string","format":"date-time","description":"Last order update date"},"links":{"type":"array","description":"Order related links like the link to fetch the single partner order","items":{"$ref":"#/components/schemas/Link__Orders-V4"}},"orderDate":{"type":"string","format":"date-time","description":"The date, when this order has been placed"},"orderLifecycleInformation":{"$ref":"#/components/schemas/OrderLifecycleInformation__Orders-V4"},"orderNumber":{"type":"string","description":"The order number. An unique human readable 10 character(alphanumeric) identifier referring to this order ","example":"p982bht4t29"},"payment":{"$ref":"#/components/schemas/Payment__Orders-V4"},"positionItems":{"type":"array","description":"The physical position items of this order. Multiple position item can refer to the same product","items":{"$ref":"#/components/schemas/PositionItem__Orders-V4"}},"salesOrderId":{"type":"string","description":"The id of the corresponding sales order. For one partner the sales order id is unique","example":"9864623c-42a4-4892-9270-cd733d32362e"},"suspectedFraudCase":{"type":"boolean","description":"Order is suspected fraud case or not"}},"required":["orderDate","orderLifecycleInformation","orderNumber","positionItems","salesOrderId"],"title":"PartnerOrder"},"PartnerOrderList__Orders-V4":{"type":"object","properties":{"links":{"type":"array","description":"Links related to the list. E.g. the link to the successive list used during paging.","items":{"$ref":"#/components/schemas/Link__Orders-V4"}},"resources":{"type":"array","description":"The list of queried resources. In this case partner orders.","items":{"$ref":"#/components/schemas/PartnerOrder__Orders-V4"}}},"title":"PartnerOrderList"},"Payment__Orders-V4":{"type":"object","description":"Payment","properties":{"paymentMethod":{"type":"string","description":"The payment method. Values currently in use are \"INVOICE_SINGLE\", \"INVOICE_INSTALLMENTS\", \"PREPAYMENT\", \"DIRECT_DEBIT\", \"DIRECT_DEBIT_INSTALLMENTS\", \"CREDIT_CARD_ONLINE\" (DEPRECATED), \"PAYPAL\", \"CREDIT_CARD\". These values are subject to change.","example":"INVOICE_SINGLE"}},"required":["paymentMethod"],"title":"Payment"},"PositionItem__Orders-V4":{"type":"object","description":"PositionItem","properties":{"cancellationDate":{"type":"string","format":"date-time","description":"Date the position item was cancelled"},"cancellationReason":{"type":"string","description":"Reason why a position was cancelled","enum":["CANCELLED_ON_CUSTOMER_WISH","CANCELLED_ON_PARTNER_WISH","PAYMENT_ABORTED","PAYMENT_FRAUD","PARTNER_TERMINATED","ILLEGAL_PRODUCT","MARKETPLACE_FRAUD","CANCELLED_ON_MARKETPLACE_WISH"]},"dealId":{"type":"string","description":"The unique id of the deal related to the position item","example":"d36cbfd9-b7b9-44d5-96d3-052d6fd97a44"},"dealName":{"type":"string","description":"The name of the deal related to the position item","example":"Deal der Woche 52"},"expectedDeliveryDate":{"type":"string","format":"date-time","description":"The date the position item should be delivered","example":"2018-10-30T12:00:00+01:00"},"fulfillmentStatus":{"type":"string","description":"The fulfillment status of the position item","enum":["ANNOUNCED","PROCESSABLE","SENT","RETURNED","CANCELLED_BY_PARTNER","CANCELLED_BY_MARKETPLACE"]},"itemValueDiscount":{"$ref":"#/components/schemas/Amount__Orders-V4"},"itemValueGrossPrice":{"$ref":"#/components/schemas/Amount__Orders-V4"},"itemValueReducedGrossPrice":{"$ref":"#/components/schemas/Amount__Orders-V4"},"positionItemId":{"type":"string","description":"The unique id of the position item","example":"7323981b-14b4-7123-7812-ac783d98132c"},"processableDate":{"type":"string","format":"date-time","description":"Date the position item has reached PROCESSABLE fulfillment status"},"product":{"$ref":"#/components/schemas/Product__Orders-V4"},"returnAcceptedByMarketplace":{"type":"boolean","description":"Flag to indicate that the return has been accepted by the marketplace","example":true},"returnedDate":{"type":"string","format":"date-time","description":"Date the position item was returned"},"sentDate":{"type":"string","format":"date-time","description":"Date the position item was sent"},"trackingInfo":{"$ref":"#/components/schemas/TrackingInfo__Orders-V4"},"weeePickup":{"type":"boolean","description":"Position item has electrical and electronic equipment disposal service (WEEE)"}},"required":["fulfillmentStatus","itemValueGrossPrice","positionItemId","product"],"title":"PositionItem"},"Product__Orders-V4":{"type":"object","description":"Product","properties":{"articleNumber":{"type":"string","description":"The external identifier of the product, it is shown as \"article number\" on the product detail page of otto.de to the customer.","example":"S000003AXQU"},"dimensions":{"type":"array","description":"List of dimensions that are individual for each product type","items":{"$ref":"#/components/schemas/Dimension__Orders-V4"}},"ean":{"type":"string","description":"EAN number of this product","example":"233232323"},"productTitle":{"type":"string","description":"The title of this product","example":"Black T-Shirt"},"shopUrl":{"type":"string","description":"Shop link for the product"},"sku":{"type":"string","description":"The external identifier of the variation, uniquely identifies a variation in partner cataloq","example":"13033"},"vatRate":{"type":"number","description":"The VAT rate for ordered products and shipping costs","example":19}},"required":["articleNumber","productTitle","sku","vatRate"],"title":"Product"},"TrackingInfo__Orders-V4":{"type":"object","description":"TrackingInfo","properties":{"carrier":{"type":"string","description":"The name of the carrier","example":"DHL"},"carrierServiceCode":{"type":"string","description":"The service code provided by the carrier"},"trackingNumber":{"type":"string","description":"The tracking number provided by the carrier","example":"H1234567890123456789"}},"title":"TrackingInfo"},"TrackingKey__ReturnShipments-V1":{"type":"object","required":["carrier","trackingNumber"],"properties":{"carrier":{"description":"The carrier of the returnShipment.","type":"string","enum":["DHL","GLS","HERMES","HES"]},"trackingNumber":{"description":"The tracking number assigned by the carrier.","type":"string"}},"title":"TrackingKey","example":{"carrier":"HERMES","trackingNumber":"H1234567890123456789"}},"ReturnPositionItem__ReturnShipments-V1":{"description":"A single position item.","type":"object","required":["salesOrderId","salesOrderPositionItemId"],"properties":{"salesOrderId":{"description":"The ID of the sales order from the OTTO Market, as defined in the Order API.","type":"string","format":"uuid","example":"a46fb35b-9c77-41c9-af10-2676b756a9af"},"salesOrderPositionItemId":{"description":"The ID of a position item of the sales order from the OTTO Market, as defined in the Order API.","format":"uuid","type":"string","example":"e454dff5-a96f-4e96-9399-710cf59645c2"}},"title":"ReturnPositionItem"},"ReturnShipmentState__ReturnShipments-V1":{"type":"object","required":["state","occurredOn"],"properties":{"state":{"description":"The tracking state of the returnShipment.","type":"string","enum":["ANNOUNCED","ON_THE_WAY","DELIVERED"]},"occurredOn":{"type":"string","example":"2022-05-01T07:49:12.642Z"},"statusText":{"description":"Optional information from the carrier detailing the tracking state.","type":"string","example":"Retoure am PaketShop abgegeben"}}},"ReturnShipment__ReturnShipments-V1":{"description":"A returnShipment with full details.","type":"object","required":["returnShipmentId","createdAt","trackingKey","returnPositionItems"],"properties":{"returnShipmentId":{"description":"Internal returnShipment identifier assigned by OTTO Market.","type":"string","example":"602392a2e5c50d0cbfb18a6b"},"createdAt":{"type":"string","example":"2022-05-01T07:49:12.642Z"},"trackingKey":{"$ref":"#/components/schemas/TrackingKey__ReturnShipments-V1"},"returnPositionItems":{"description":"The position items included in the returnShipment.","minItems":1,"type":"array","items":{"$ref":"#/components/schemas/ReturnPositionItem__ReturnShipments-V1"}},"states":{"description":"The history of tracking states of the returnShipment","minItems":0,"type":"array","items":{"$ref":"#/components/schemas/ReturnShipmentState__ReturnShipments-V1"}}},"title":"ReturnShipment"},"ReturnShipmentList__ReturnShipments-V1":{"type":"object","properties":{"links":{"type":"array","description":"Contains one single link, which can be used as pointer for Cursor-based pagination.","items":{"$ref":"#/components/schemas/Link__ReturnShipments-V1"}},"resources":{"type":"array","items":{"$ref":"#/components/schemas/ReturnShipment__ReturnShipments-V1"}}},"title":"ReturnShipmentList"},"Link__ReturnShipments-V1":{"type":"object","properties":{"href":{"type":"string","example":"/v1/return-shipments?next=12345678&limit=25&datefrom=2019-05-02T07:49:12.642Z","description":"The url of the link"},"rel":{"type":"string","example":"next","description":"The relation type of the link. See also https://www.iana.org/assignments/link-relations/link-relations.xhtml. The relation type 'next' is used for paging. The relation type 'self' refers to the url of the ressource"}},"title":"Link","description":"A link to various resources. a Link can have different meanings and targets. The type of relation is specified with the property 'rel'. "},"Unauthorized__ReturnShipments-V1":{"description":"Authentication is required and has failed."},"BadRequest__ReturnShipments-V1":{"description":"The server received invalid request regarding params, payload, pathVariable, Etc.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__ReturnShipments-V1"}},"example":{"errors":[{"title":"BAD_REQUEST","detail":"Parameter XYZ is invalid.","path":"/return-shipments"}]}},"ForbiddenGetReturnShipmentByTrackingNumber__ReturnShipments-V1":{"description":"The partner does not have the required permissions.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__ReturnShipments-V1"}},"example":{"errors":[{"title":"INSUFFICIENT_PERMISSION","detail":"The partner is not allowed to get shipment with carrier DHL and tracking number 00340434268030693122","path":"/return-shipments/carriers/DHL/trackingnumbers/00340434268030693122"}]}},"ForbiddenGetReturnShipmentByReturnShipmentId__ReturnShipments-V1":{"description":"The partner does not have the required permissions.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__ReturnShipments-V1"}},"example":{"errors":[{"title":"INSUFFICIENT_PERMISSION","detail":"The partner is not allowed to get shipment with id 101069930815","path":"/return-shipments/101069930815"}]}},"NotFoundGetReturnShipmentByTrackingNumber__ReturnShipments-V1":{"description":"Server can not find requested resource.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__ReturnShipments-V1"}},"example":{"errors":[{"title":"RESOURCE_NOT_FOUND","detail":"Found no shipment with carrier DHL and tracking number 003404342680306931225","path":"/return-shipments/carriers/DHL/trackingnumbers/003404342680306931225"}]}},"NotFoundGetReturnShipmentByReturnShipmentId__ReturnShipments-V1":{"description":"Server can not find requested resource.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__ReturnShipments-V1"}},"example":{"errors":[{"title":"RESOURCE_NOT_FOUND","detail":"Found no shipment with id 1010699308155","path":"/return-shipments/1010699308155"}]}},"InternalServerErrorGetReturnShipmentList__ReturnShipments-V1":{"description":"An internal server error occurred.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__ReturnShipments-V1"}},"example":{"errors":[{"title":"INTERNAL_SERVER_ERROR","path":"/return-shipments?datefrom=2022-05-01T07:49:12.642Z"}]}},"InternalServerErrorGetReturnShipmentByTrackingNumber__ReturnShipments-V1":{"description":"An internal server error occurred.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__ReturnShipments-V1"}},"example":{"errors":[{"title":"INTERNAL_SERVER_ERROR","path":"/return-shipments/carriers/DHL/trackingnumbers/00340434268030693122"}]}},"InternalServerErrorGetReturnShipmentByReturnShipmentId__ReturnShipments-V1":{"description":"An internal server error occurred.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__ReturnShipments-V1"}},"example":{"errors":[{"title":"INTERNAL_SERVER_ERROR","path":"/return-shipments/101069930815"}]}},"ErrorDescription__ReturnShipments-V1":{"description":"Describes one single error.","type":"object","required":["title","path"],"properties":{"title":{"description":"The short description of the error.","type":"string"},"detail":{"description":"The long description of the error.","type":"string"},"path":{"description":"The called REST path.","type":"string"},"jsonPath":{"description":"The JSON path points either to the object or the value that caused the error. The JSON path could consists of JSON properties and indexes.","type":"string","example":"trackingKey.trackingNumber"}}},"Address__Shipments-V1":{"type":"object","required":["city","countryCode","zipCode"],"properties":{"city":{"type":"string","example":"Dresden","description":"The city from where the shipment is sent.","minLength":1,"maxLength":60},"countryCode":{"type":"string","example":"DEU","pattern":"^[A-Z]{3}$","description":"The country code according to [iso-3166-1-alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) from where the shipment is sent."},"zipCode":{"type":"string","example":"01067","description":"The zip code from where the shipment is sent.","minLength":1,"maxLength":10}},"title":"Address","description":"The warehouse or location from which the shipment will be picked up for final delivery."},"MultiparcelCreateShipmentRequest__Shipments-V1":{"type":"object","required":["shipDate","shipFromAddress","positionItems","trackingKey"],"properties":{"trackingKey":{"$ref":"#/components/schemas/MultiparcelTrackingKey__Shipments-V1"},"shipDate":{"type":"string","format":"date-time","description":"The date that the shipment is handed over to the carrier. Must be a valid UTC dateTime according to ISO 8601.","example":"2019-10-11T07:49:12.642Z"},"shipFromAddress":{"$ref":"#/components/schemas/Address__Shipments-V1"},"positionItems":{"description":"The position items included in shipment.","minItems":1,"type":"array","items":{"$ref":"#/components/schemas/MultiparcelPositionItem__Shipments-V1"},"example":[{"positionItemId":"b01b8ad2-a49c-47fc-8ade-8629ec000020","salesOrderId":"bf43d748-f13d-49ca-b2e2-1824e9000021","returnTrackingKey":{"carrier":"DHL","trackingNumber":"577546565072"}},{"positionItemId":"b01b8ad2-a49c-47fc-8ade-8629ec000022","salesOrderId":"bf43d748-f13d-49ca-b2e2-1824e9000021","returnTrackingKey":{"carrier":"DHL","trackingNumber":"577546565072"}}]}},"title":"MultiparcelCreateShipmentRequest"},"CreateShipmentRequest__Shipments-V1":{"type":"object","required":["shipDate","shipFromAddress","positionItems","trackingKey"],"properties":{"trackingKey":{"$ref":"#/components/schemas/TrackingKey__Shipments-V1"},"shipDate":{"type":"string","format":"date-time","description":"The date that the shipment is handed over to the carrier. Must be a valid UTC dateTime according to ISO 8601.","example":"2019-10-11T07:49:12.642Z"},"shipFromAddress":{"$ref":"#/components/schemas/Address__Shipments-V1"},"positionItems":{"description":"The position items included in shipment.","minItems":1,"type":"array","items":{"$ref":"#/components/schemas/PositionItem__Shipments-V1"},"example":[{"positionItemId":"b01b8ad2-a49c-47fc-8ade-8629ec000020","salesOrderId":"bf43d748-f13d-49ca-b2e2-1824e9000021","returnTrackingKey":{"carrier":"DHL","trackingNumber":"577546565072"}},{"positionItemId":"b01b8ad2-a49c-47fc-8ade-8629ec000022","salesOrderId":"bf43d748-f13d-49ca-b2e2-1824e9000021","returnTrackingKey":{"carrier":"DHL","trackingNumber":"577546565072"}}]}},"title":"CreateShipmentRequest"},"CreateShipmentResponse__Shipments-V1":{"type":"object","properties":{"shipmentId":{"description":"Internal shipment identifier assigned by OTTO Market.","type":"string","example":"100000294699"}},"title":"CreateShipmentResponse"},"CreateMultiparcelShipmentRequest__Shipments-V1":{"minItems":2,"type":"array","items":{"$ref":"#/components/schemas/MultiparcelCreateShipmentRequest__Shipments-V1"},"title":"CreateMultiparcelShipmentRequest"},"CreateMultiparcelShipmentResponse__Shipments-V1":{"type":"object","properties":{"multiParcelShipmentId":{"description":"Internal multiparcel shipment identifier assigned by OTTO Market.","type":"string","example":"100000294699"}},"title":"CreateMultiparcelShipmentResponse"},"PositionItem__Shipments-V1":{"description":"A single position item.","type":"object","required":["positionItemId","salesOrderId","returnTrackingKey"],"properties":{"positionItemId":{"description":"The ID of a position item of the sales order from the OTTO Market, as defined in the Order API.","format":"uuid","type":"string","example":"e454dff5-a96f-4e96-9399-710cf59645c2"},"salesOrderId":{"description":"The ID of the sales order from the OTTO Market, as defined in the Order API.","type":"string","format":"uuid","example":"a46fb35b-9c77-41c9-af10-2676b756a9af"},"returnTrackingKey":{"$ref":"#/components/schemas/ReturnTrackingKey__Shipments-V1"},"returnAddressCarrierId":{"description":"Unique id for the return address and the return carrier combination (not yet deployed in live).","format":"uuid","type":"string","example":"7423afd2-e7ab-4bae-ac30-048b7c0346c1"}},"title":"PositionItem"},"MultiparcelPositionItem__Shipments-V1":{"description":"A single position item.","type":"object","required":["positionItemId","salesOrderId","returnTrackingKey"],"properties":{"positionItemId":{"description":"The ID of a position item of the sales order from the OTTO Market, as defined in the Order API.","format":"uuid","type":"string","example":"e454dff5-a96f-4e96-9399-710cf59645c2"},"salesOrderId":{"description":"The ID of the sales order from the OTTO Market, as defined in the Order API.","type":"string","format":"uuid","example":"a46fb35b-9c77-41c9-af10-2676b756a9af"},"returnTrackingKey":{"$ref":"#/components/schemas/MultiparcelReturnTrackingKey__Shipments-V1"},"returnAddressCarrierId":{"description":"Unique id for the return address and the return carrier combination (not yet deployed in live).","format":"uuid","type":"string","example":"7423afd2-e7ab-4bae-ac30-048b7c0346c1"}},"title":"PositionItem"},"ShipmentState__Shipments-V1":{"type":"object","required":["state","occurredOn"],"properties":{"state":{"description":"The tracking state of the shipment.","type":"string","enum":["SENT","ON_THE_WAY","DELIVERED","DELIVERED_FOR_PICKUP","DELIVERY_ATTEMPT_FAILED"]},"occurredOn":{"type":"string","example":"2022-05-01T07:49:12.642Z"}}},"ReturnTrackingKey__Shipments-V1":{"description":"The return tracking key for the return process.
**Required for parcel deliveries.**
**Optional for forwarder deliveries.**
Each position item can have its own return tracking key.","type":"object","required":["carrier","trackingNumber"],"properties":{"carrier":{"description":"The carrier for the return process, which can differ from the carrier used to deliver the shipment to the customer. Please be aware that this carrier can not differ from the chosen carrier in the OPC portal.","type":"string","enum":["DHL","GLS","HERMES"]},"trackingNumber":{"description":"The tracking number (or return tracking number) assigned by the carrier.","type":"string"}},"title":"ReturnTrackingKey","example":{"carrier":"DHL","trackingNumber":"577546565072"}},"MultiparcelReturnTrackingKey__Shipments-V1":{"description":"The return tracking key for the return process.
**Required for parcel deliveries.**
Each position item can have its own return tracking key.","type":"object","required":["carrier","trackingNumber"],"properties":{"carrier":{"description":"The carrier for the return process, which can differ from the carrier used to deliver the shipment to the customer. Please be aware that this carrier can not differ from the chosen carrier in the OPC portal.","type":"string","enum":["DHL","GLS","HERMES"]},"trackingNumber":{"description":"The tracking number (or return tracking number) assigned by the carrier.","type":"string"}},"title":"ReturnTrackingKey","example":{"carrier":"DHL","trackingNumber":"577546565072"}},"Shipment__Shipments-V1":{"description":"A shipment with full details.","type":"object","properties":{"shipmentId":{"description":"Internal shipment identifier assigned by OTTO Market.","type":"string","example":"101068391469"},"creationDate":{"type":"string","example":"2019-10-11T07:49:12.642Z"},"trackingKey":{"$ref":"#/components/schemas/TrackingKey__Shipments-V1"},"shipDate":{"type":"string","example":"2019-09-19T13:00:00.000Z"},"shipFromAddress":{"$ref":"#/components/schemas/Address__Shipments-V1"},"positionItems":{"description":"The position items included in the shipment.","minItems":1,"type":"array","items":{"$ref":"#/components/schemas/PositionItem__Shipments-V1"}},"states":{"description":"The history of tracking states of the shipment","minItems":0,"type":"array","items":{"$ref":"#/components/schemas/ShipmentState__Shipments-V1"}}},"title":"Shipment"},"ShipmentList__Shipments-V1":{"type":"object","properties":{"links":{"type":"array","description":"Contains one single link, which can be used as pointer for Cursor-based pagination.","items":{"$ref":"#/components/schemas/Link__Shipments-V1"}},"resources":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentWithMinimumDetails__Shipments-V1"}}},"title":"ShipmentList"},"Link__Shipments-V1":{"type":"object","properties":{"href":{"type":"string","example":"/v1/shipments?next=12345678&limit=25&datefrom=2019-05-02T00:00:00Z","description":"The url of the link"},"rel":{"type":"string","example":"next","description":"The relation type of the link. See also https://www.iana.org/assignments/link-relations/link-relations.xhtml. The relation type 'next' is used for paging. The relation type 'self' refers to the url of the ressource"}},"title":"Link","description":"A link to various resources. a Link can have different meanings and targets. The type of relation is specified with the property 'rel'. "},"ShipmentWithMinimumDetails__Shipments-V1":{"description":"A shipment with a reduced number of fields.","type":"object","properties":{"creationDate":{"type":"string","example":"2019-10-11T07:49:12.642Z"},"shipmentId":{"description":"Internal shipment identifier assigned by OTTO Market.","type":"string","example":"101068626890"},"trackingKey":{"$ref":"#/components/schemas/TrackingKey__Shipments-V1"},"states":{"description":"The history of tracking states of the shipment","minItems":0,"type":"array","items":{"$ref":"#/components/schemas/ShipmentState__Shipments-V1"}}},"title":"ShipmentWithMinimumDetails"},"MultiparcelTrackingKey__Shipments-V1":{"type":"object","required":["carrier","trackingNumber"],"properties":{"carrier":{"description":"The carrier of the shipment.","type":"string","enum":["DHL","DHL_EXPRESS","DHL_FREIGHT","DHL_HOME_DELIVERY","GLS","HERMES","DPD","UPS","BTW","BURSPED","CARGOLINE","DACHSER","DB_SCHENKER","DSV","EMONS","EPH_DIREKT","IDS","GEIS","GEL","GUETTLER","HES","HELLMANN","HEUEL","KOCH","KUEHNE_NAGEL","LOGWIN","MEYER_JUMBO","RABEN_LOGISTIK","RHENUS","REIMER","REITHMEIER","SCHOCKEMOEHLE","SCHMIDT_GEVELSBERG","ZUFALL","OTHER_FORWARDER"]},"trackingNumber":{"description":"The tracking number assigned by the carrier.
Required for parcel deliveries.","type":"string"}},"title":"TrackingKey","example":{"carrier":"HERMES","trackingNumber":"H1234567890123456789"}},"TrackingKey__Shipments-V1":{"type":"object","required":["carrier","trackingNumber"],"properties":{"carrier":{"description":"The carrier of the shipment.","type":"string","enum":["DHL","DHL_EXPRESS","DHL_FREIGHT","DHL_HOME_DELIVERY","GLS","HERMES","DPD","UPS","BTW","BURSPED","CARGOLINE","DACHSER","DB_SCHENKER","DSV","EMONS","EPH_DIREKT","IDS","GEIS","GEL","GUETTLER","HES","HELLMANN","HEUEL","KOCH","KUEHNE_NAGEL","LOGWIN","MEYER_JUMBO","RABEN_LOGISTIK","RHENUS","REIMER","REITHMEIER","SCHOCKEMOEHLE","SCHMIDT_GEVELSBERG","ZUFALL","OTHER_FORWARDER"]},"trackingNumber":{"description":"The tracking number assigned by the carrier.
Required for parcel deliveries.
Optional for forwarder deliveries.","type":"string"}},"title":"TrackingKey","example":{"carrier":"HERMES","trackingNumber":"H1234567890123456789"}},"BadRequest__Shipments-V1":{"description":"The partner sent a bad request.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__Shipments-V1"}}},"BadRequestAddPositionItemByTrackingNumber__Shipments-V1":{"description":"The partner sent a bad request.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__Shipments-V1"}}},"BadRequestAddPositionItemByShipmentId__Shipments-V1":{"description":"The partner sent a bad request.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__Shipments-V1"}}},"Unauthorized__Shipments-V1":{"description":"Authentication is required and has failed."},"ForbiddenGetShipmentByTrackingNumber__Shipments-V1":{"description":"The partner does not have the required permissions.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__Shipments-V1"}},"example":{"errors":[{"title":"INSUFFICIENT_PERMISSION","detail":"The partner is not allowed to get shipment with carrier DHL and tracking number 00340434268030693122","path":"/shipments/carriers/DHL/trackingnumbers/00340434268030693122"}]}},"ForbiddenGetShipmentByShipmentId__Shipments-V1":{"description":"The partner does not have the required permissions.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__Shipments-V1"}},"example":{"errors":[{"title":"INSUFFICIENT_PERMISSION","detail":"The partner is not allowed to get shipment with id 101069930815","path":"/shipments/101069930815"}]}},"NotFoundGetShipmentByTrackingNumber__Shipments-V1":{"description":"Server can not find requested resource.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__Shipments-V1"}},"example":{"errors":[{"title":"RESOURCE_NOT_FOUND","detail":"Found no shipment with carrier DHL and tracking number 003404342680306931225","path":"/shipments/carriers/DHL/trackingnumbers/003404342680306931225"}]}},"NotFoundGetShipmentByShipmentId__Shipments-V1":{"description":"Server can not find requested resource.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__Shipments-V1"}},"example":{"errors":[{"title":"RESOURCE_NOT_FOUND","detail":"Found no shipment with id 1010699308155","path":"/shipments/1010699308155"}]}},"NotFoundAddPositionItemByTrackingNumber__Shipments-V1":{"description":"Server can not find requested resource.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__Shipments-V1"}},"example":{"errors":[{"title":"RESOURCE_NOT_FOUND","detail":"Found no shipment with carrier DHL and tracking number 003404342680306931252","path":"/shipments/carriers/DHL/trackingnumbers/003404342680306931252/positionitems"}]}},"NotFoundAddPositionItemByShipmentId__Shipments-V1":{"description":"Server can not find requested resource.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__Shipments-V1"}},"example":{"errors":[{"title":"RESOURCE_NOT_FOUND","detail":"Found no shipment with id 1010699308155","path":"/shipments/1010699308155/positionitems"}]}},"Conflict__Shipments-V1":{"description":"The request could not be completed due to a conflict with the current state of the target resource. The client should not repeat this request without modification.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__Shipments-V1"}},"example":{"errors":[{"title":"DUPLICATE_TRACKING_KEY","detail":"Tracking key already exists for another shipment.","path":"/shipments"}]}},"ConflictMultiparcel__Shipments-V1":{"description":"The request could not be completed due to a conflict with the current state of the target resource. The client should not repeat this request without modification.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__Shipments-V1"}},"example":{"errors":[{"title":"DUPLICATE_TRACKING_KEY","detail":"Tracking key already exists for another shipment.","path":"/multiparcel-shipments[0].shipments"}]}},"ConflictAddPositionItemByTrackingNumber__Shipments-V1":{"description":"The request could not be completed due to a conflict with the current state of the target resource. The client should not repeat this request without modification.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__Shipments-V1"}},"example":{"errors":[{"title":"POSITION_ITEM_INCLUDED_IN_OTHER_SHIPMENT","detail":"One or more of the given position item ids already exist in another shipment","path":"/shipments/carriers/DHL/trackingnumbers/00340434268030693122/positionitems"}]}},"ConflictAddPositionItemByShipmentId__Shipments-V1":{"description":"The request could not be completed due to a conflict with the current state of the target resource. The client should not repeat this request without modification.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__Shipments-V1"}},"example":{"errors":[{"title":"POSITION_ITEM_INCLUDED_IN_OTHER_SHIPMENT","detail":"One or more of the given position item ids already exist in another shipment","path":"/shipments/101069930815/positionitems"}]}},"InternalServerError__Shipments-V1":{"description":"An internal server error occurred.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__Shipments-V1"}},"example":{"errors":[{"title":"INTERNAL_SERVER_ERROR","path":"/shipments"}]}},"InternalServerErrorMultiparcel__Shipments-V1":{"description":"An internal server error occurred.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__Shipments-V1"}},"example":{"errors":[{"title":"INTERNAL_SERVER_ERROR","path":"/multiparcel-shipments"}]}},"InternalServerErrorGetShipmentList__Shipments-V1":{"description":"An internal server error occurred.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__Shipments-V1"}},"example":{"errors":[{"title":"INTERNAL_SERVER_ERROR","path":"/shipments?datefrom=2019-10-10"}]}},"InternalServerErrorGetShipmentByTrackingNumber__Shipments-V1":{"description":"An internal server error occurred.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__Shipments-V1"}},"example":{"errors":[{"title":"INTERNAL_SERVER_ERROR","path":"shipments/carriers/DHL/trackingnumbers/00340434268030693122"}]}},"InternalServerErrorGetShipmentByShipmentId__Shipments-V1":{"description":"An internal server error occurred.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__Shipments-V1"}},"example":{"errors":[{"title":"INTERNAL_SERVER_ERROR","path":"/shipments/101069930815"}]}},"InternalServerErrorAddPositionItemByTrackingNumber__Shipments-V1":{"description":"An internal server error occurred.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__Shipments-V1"}},"example":{"errors":[{"title":"INTERNAL_SERVER_ERROR","path":"/shipments/carriers/DHL/trackingnumbers/00340434268030693122/positionitem"}]}},"InternalServerErrorAddPositionItemByShipmentId__Shipments-V1":{"description":"An internal server error occurred.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/ErrorDescription__Shipments-V1"}},"example":{"errors":[{"title":"INTERNAL_SERVER_ERROR","path":"/shipments/101069930815/positionitems"}]}},"ErrorDescription__Shipments-V1":{"description":"Details of the occurred errors.","type":"object","required":["title","path"],"properties":{"title":{"description":"The short description of the error.","type":"string"},"detail":{"description":"The long description of the error.","type":"string"},"path":{"description":"The called REST path.","type":"string"},"jsonPath":{"description":"The JSON path points either to the object or the value that caused the error. The JSON path could consists of JSON properties and indexes.","type":"string","example":"positionItems[0].returnTrackingKey.trackingNumber"}}},"ApiErrorV3__Returns-V3":{"type":"object","properties":{"detail":{"type":"string"},"logref":{"type":"string"},"path":{"type":"string"},"title":{"type":"string"}},"title":"ApiError"},"ApiErrorResponseV3__Returns-V3":{"type":"object","properties":{"errors":{"type":"array","example":[{"path":"/v3/returns/rejection","title":"Error message with positionItemId","detail":"details of error with positionItemId","logref":"positionItemId"}],"description":"List of all the items received from partner","items":{"$ref":"#/components/schemas/ApiErrorV3__Returns-V3"}}},"title":"ApiErrorResponseV3"},"AcceptedPartnerReturnV3__Returns-V3":{"type":"object","required":["positionItems"],"properties":{"positionItems":{"type":"array","example":[{"positionItemId":"942e2a36-9112-444e-92e3-3bc3cd93011","salesOrderId":"7423afd2-e7ab-4bae-ac30-048b7c0346c1","condition":"A","reason":"RETURN_RECEIVED"}],"description":"List of all the items received from partner","items":{"$ref":"#/components/schemas/AcceptedPositionItem__Returns-V3"}}},"title":"AcceptedPartnerReturnV3"},"AcceptedPositionItem__Returns-V3":{"type":"object","required":["positionItemId","salesOrderId"],"properties":{"positionItemId":{"type":"string","example":"76737ae6-c316-4880-b1ff-a1a92b4866e9","description":"Sales position item ID"},"salesOrderId":{"type":"string","example":"ff2e3713-e28e-492c-b6cd-d076e4b68ef5","description":"Sales order ID"},"condition":{"type":"string","example":"A for originalverpackt / in original packaging; B for wie neu / in mint condition; C for leicht gebraucht / slightly used; D for stark gebraucht / heavily used; E for Irrtum (Ware unvollständig, nicht vorhanden, …) / mistake (Delivery incomplete, not available,...)","description":"Condition of the returned item","enum":["A/B/C/D/E"]},"reason":{"type":"string","example":"RETURN_RECEIVED","description":"Reason for Rejection","enum":["RETURN_RECEIVED","STATUS_SENT_BY_ACCIDENT","CANCEL_REQUEST_BY_CUSTOMER","REFUND_AFTER_AFFIDAVIT","COMPLAINT","SHIPMENT_LOST","RETURN_LOST","UNDELIVERABLE"]}},"title":"AcceptedPositionItem"},"AcceptedReturnMultiStatusResponse__Returns-V3":{"type":"object","required":["results"],"properties":{"results":{"type":"array","example":[{"positionItemId":"942e2a36-9112-444e-92e3-3bc3cd93011","salesOrderId":"7423afd2-e7ab-4bae-ac30-048b7c0346c1","condition":"A","reason":"RETURN_RECEIVED"}],"description":"List of all the items received from partner","items":{"$ref":"#/components/schemas/AcceptedPositionItem__Returns-V3"}},"errors":{"type":"array","example":[{"path":"/v3/returns/acceptance","title":"Error message with positionItemId","detail":"details of error with positionItemId","logref":"positionItemId"},{"path":"/v3/returns/acceptance","title":"Error while processing request: 942e2a36-9112-444e-92e3-3bc3cd93011","detail":"Error: Product Not Sent By The Partner for positionItemId: 942e2a36-9112-444e-92e3-3bc3cd93011","logref":"positionItemId"},{"path":"/v3/returns/acceptance","title":"Error while processing request: 942e2a36-9112-444e-92e3-3bc3cd93011","detail":"Error: Product Does Not Belong To Sales Order Id for positionItemId: 942e2a36-9112-444e-92e3-3bc3cd93011","logref":"positionItemId"},{"path":"/v3/returns/acceptance","title":"Error while processing request: 942e2a36-9112-444e-92e3-3bc3cd93011","detail":"Product Is Already Accepted By The Partner for 942e2a36-9112-444e-92e3-3bc3cd93011: positionItemId","logref":"positionItemId"}],"items":{"$ref":"#/components/schemas/ApiErrorV3__Returns-V3"}}},"title":"AcceptedReturnMultiStatusResponse"},"RejectedPartnerReturnV3__Returns-V3":{"type":"object","required":["positionItems"],"properties":{"positionItems":{"type":"array","example":[{"positionItemId":"942e2a36-9112-444e-92e3-3bc3cd93011","salesOrderId":"7423afd2-e7ab-4bae-ac30-048b7c0346c1","condition":"A","reason":"WRONG_ITEM"}],"description":"List of all the items received from partner","items":{"$ref":"#/components/schemas/RejectedPositionItem__Returns-V3"}}},"title":"RejectedPartnerReturnV3"},"RejectedPositionItem__Returns-V3":{"type":"object","required":["positionItemId","reason","salesOrderId"],"properties":{"positionItemId":{"type":"string","example":"76737ae6-c316-4880-b1ff-a1a92b4866e9","description":"Sales position item ID"},"salesOrderId":{"type":"string","example":"ff2e3713-e28e-492c-b6cd-d076e4b68ef5","description":"Sales order ID"},"condition":{"type":"string","example":"A for originalverpackt / in original packaging; B for wie neu / in mint condition; C for leicht gebraucht / slightly used; D for stark gebraucht / heavily used; E for Irrtum (Ware unvollständig, nicht vorhanden, …) / mistake (Delivery incomplete, not available,...)","description":"Condition of the returned item","enum":["A/B/C/D/E"]},"reason":{"type":"string","example":"WRONG_ITEM","description":"Reason for Rejection","enum":["THIRD_PARTY_ITEM","WRONG_ITEM","EXCHANGE","DAMAGE_TO_THE_HYGIENE_SEAL","ITEM_DAMAGED","RETURN_PERIOD_EXCEEDED","ITEM_NOT_IN_THE_PARCEL"]}},"title":"RejectedPositionItem"},"RejectedReturnMultiStatusResponse__Returns-V3":{"type":"object","required":["results"],"properties":{"results":{"type":"array","example":[{"positionItemId":"942e2a36-9112-444e-92e3-3bc3cd93011","salesOrderId":"7423afd2-e7ab-4bae-ac30-048b7c0346c1","condition":"A","reason":"WRONG_ITEM"}],"description":"List of all the items received from partner","items":{"$ref":"#/components/schemas/RejectedPositionItem__Returns-V3"}},"errors":{"type":"array","example":[{"path":"/v3/returns/rejection","title":"Error message with positionItemId","detail":"details of error with positionItemId","logref":"positionItemId"},{"path":"/v3/returns/rejection","title":"Error while processing request: positionItemId","detail":"Error: Product Not Sent By The Partner for positionItemId: positionItemId","logref":"positionItemId"},{"path":"/v3/returns/rejection","title":"Error while processing request: positionItemId","detail":"Error: Product Does Not Belong To Sales Order Id for positionItemId: positionItemId","logref":"positionItemId"},{"path":"/v3/returns/rejection","title":"Error while processing request: positionItemId","detail":"Product Is Already Accepted By The Partner for positionItemId: positionItemId","logref":"positionItemId"}],"items":{"$ref":"#/components/schemas/ApiErrorV3__Returns-V3"}}},"title":"RejectedReturnMultiStatusResponse"},"Link__Returns-V3":{"type":"object","properties":{"href":{"type":"string","example":"/v3/returns?status=Accepted","description":"The url of the link"},"rel":{"type":"string","example":"next","description":"The relation type of the link. See also https://www.iana.org/assignments/link-relations/link-relations.xhtml. The relation type 'next' is used for paging. The relation type 'self' refers to the url of the resource"}},"title":"Link","description":"A link to various resources. A Link can have different meanings and targets. The type of relation is specified with the property 'rel'. "},"ReturnTrackingKey__Returns-V3":{"title":"ReturnTrackingKey","type":"object","properties":{"trackingNumbers":{"type":"array","example":[406522044488,406522044489],"description":"The list of return tracking numbers for the announced item","items":{"type":"string"}},"carrier":{"type":"string","example":"DHL","description":"The carrier for the announced item"}},"description":"Return tracking details of the returned item."},"AcceptedStatusData__Returns-V3":{"title":"AcceptedStatusData","type":"object","properties":{"condition":{"type":"string","example":"A for originalverpackt / in original packaging; B for wie neu / in mint condition; C for leicht gebraucht / slightly used; D for stark gebraucht / heavily used; E for Irrtum (Ware unvollständig, nicht vorhanden, …) / mistake (Delivery incomplete, not available,...)","description":"Condition of the returned item"},"reason":{"type":"string","example":"RETURN_RECEIVED","description":"Reason for acceptance","enum":["RETURN_RECEIVED","STATUS_SENT_BY_ACCIDENT","CANCEL_REQUEST_BY_CUSTOMER","REFUND_AFTER_AFFIDAVIT","COMPLAINT","SHIPMENT_LOST","RETURN_LOST","UNDELIVERABLE"]}},"description":"Details specific to a 'accepted' return status."},"AnnouncedStatusData__Returns-V3":{"title":"AnnouncedStatusData","type":"object","properties":{"returnTrackingKey":{"$ref":"#/components/schemas/ReturnTrackingKey__Returns-V3"}},"description":"Details specific to a 'announced' return status."},"MisdirectedStatusData__Returns-V3":{"title":"MisdirectedStatusData","type":"object","properties":{"orderNumber":{"type":"string","example":"b7c0346c1","description":"Order Number"},"ottoWarehouseID":{"type":"string","example":"e4fae5b7e4fae5b7d4","description":"This is the unique id which helps partner identify the misdirected item"}},"description":"Details specific to a 'misdirected' return status."},"RejectedStatusData__Returns-V3":{"title":"RejectedStatusData","type":"object","required":["reason"],"properties":{"condition":{"type":"string","example":"A for originalverpackt / in original packaging; B for wie neu / in mint condition; C for leicht gebraucht / slightly used; D for stark gebraucht / heavily used; E for Irrtum (Ware unvollständig, nicht vorhanden, …) / mistake (Delivery incomplete, not available,...)","description":"Condition of the returned item"},"reason":{"type":"string","example":"WRONG_ITEM","description":"Reason for Rejection","enum":["THIRD_PARTY_ITEM","WRONG_ITEM","EXCHANGE","DAMAGE_TO_THE_HYGIENE_SEAL","ITEM_DAMAGED","RETURN_PERIOD_EXCEEDED","ITEM_NOT_IN_THE_PARCEL"]}},"description":"Details specific to a 'rejected' return status."},"PositionItem__Returns-V3":{"type":"object","properties":{"positionItemId":{"type":"string","example":"7423afd2-e7ab-4bae-ac30-048b7c0346c1","description":"Sales position item ID"},"salesOrderId":{"type":"string","example":"7423afd2-e7ab-4bae-ac30-048b7c0346c1","description":"Sales order ID"},"status":{"type":"string","example":"MISDIRECTED","description":"Current return status of item.","enum":["ANNOUNCED","ACCEPTED","REJECTED","MISDIRECTED"]},"occurredTime":{"type":"string","example":"2019-08-04T22:00:00.00Z","description":"Date when the last status was updated."},"details":{"$ref":"#/components/schemas/ReturnedItemStatusData__Returns-V3"}},"title":"PositionItem","description":"Details about a positionItem."},"PositionItemList__Returns-V3":{"type":"object","properties":{"positionItems":{"type":"array","description":"The list of queried items.","items":{"$ref":"#/components/schemas/PositionItem__Returns-V3"}},"links":{"type":"array","description":"Links related to the list. E.g. the link to the successive list used during paging.","items":{"$ref":"#/components/schemas/Link__Returns-V3"}}},"title":"PositionItemList"},"ReturnedItemStatusData__Returns-V3":{"type":"object","title":"ReturnedItemStatusData","description":"UnionType: One of ReturnAnnounced, Misdirected Return, Accepted Return, Rejected Return. This type is never returned to the client only the subtypes are","oneOf":[{"$ref":"#/components/schemas/AcceptedStatusData__Returns-V3"},{"$ref":"#/components/schemas/AnnouncedStatusData__Returns-V3"},{"$ref":"#/components/schemas/MisdirectedStatusData__Returns-V3"},{"$ref":"#/components/schemas/RejectedStatusData__Returns-V3"}]},"Address__Receipts-V3":{"title":"Address","required":["city","countryCode","firstName","lastName","street","zipCode"],"type":"object","properties":{"firstName":{"type":"string","description":"First name of person or name of a pick point","example":"Iris"},"lastName":{"type":"string","description":"Last name of a person or a pick point id","example":"Muster"},"street":{"type":"string","description":"Street of address.
For sales orders were placed before 23rd Sep. 2021 street and house number are both parts of this field","example":"Washingtonallee"},"houseNumber":{"type":"string","description":"House number of address
Available for sales orders placed after 23rd Sep. 2021. For older sales orders the house number is part of the field street and this field is not shown at all","example":"42"},"addition":{"type":"string","description":"Additional information of the address
Can be used to provide additional information of address","example":"Hinterhof, 1. Stock"},"zipCode":{"type":"string","description":"Zip code of address","example":"22885"},"city":{"type":"string","description":"City of address","example":"Bremerhaven"},"countryCode":{"type":"string","description":"Country of address represented as country code (ISO 3166-1 alpha-3)","example":"DEU"}},"description":"There are different definitions of Address objects in Receipt structure:\n* **invoiceAddress** - Address of the customer to be billed\n* **deliveryAddress** - Address of the recipient entered by the customer when placing the order. Recipient can be a person or a pickup point.
Only available on receipts of receiptType PURCHASE."},"AddressInformation__Receipts-V3":{"title":"AddressInformation","required":["countryCode","zipCode"],"type":"object","properties":{"zipCode":{"type":"string","description":"Zip code of shipFromAddress","example":"60437"},"countryCode":{"type":"string","description":"Country of shipFromAddress represented as country code (ISO 3166-1 alpha-3)","example":"DEU"}},"description":"Place of departure from shipment notification send to OTTO market for items.
ATTENTION: If data in shipment notification is not unique per item, it is taken by default."},"Benefit__Receipts-V3":{"title":"Benefit","type":"object","properties":{"id":{"type":"string","description":"Discount code applied to the order to get a reduction. Available when reduction is of type PARTNER_DISCOUNT\n"},"description":{"type":"string","description":"Additional info often printed on the pdf for a PriceModification object (on German receipts always in German)If PriceModification object is of type:\n\n* **PARTNER_DISCOUNT**- discount name, provided with sales order event as part of positionGroupPrice-
(What we print on the pdf )- e.g. \"1 € Rabatt\"\n"}},"description":"Additional information about the applied customer benefit.\n"},"Customer__Receipts-V3":{"title":"Customer","required":["invoiceAddress"],"type":"object","properties":{"invoiceAddress":{"$ref":"#/components/schemas/Address__Receipts-V3"}},"description":"Customer details"},"DeliveryCost__Receipts-V3":{"title":"DeliveryCost","required":["deliveryCostType","positionSum","priceModifications","unitPrice"],"type":"object","properties":{"lineNumber":{"type":"integer","description":"Number of line item in which the information is printed on the pdf document of the receipt.\n
This information is not reliably provided for older receipts","format":"int32","example":5},"deliveryCostType":{"type":"string","description":"Type of delivery costs for the shipment of physical goods.
\nPossible values:\n* **DELIVERY_FEE_STANDARD** - basic shipping costs\n* **DELIVERY_FEE_FREIGHT_SURCHARGE** - additional freight surcharge for bulky goods\n","example":"DELIVERY_FEE_STANDARD","enum":["DELIVERY_FEE_STANDARD","DELIVERY_FEE_FREIGHT_SURCHARGE"]},"unitPrice":{"$ref":"#/components/schemas/Price__Receipts-V3"},"positionSum":{"$ref":"#/components/schemas/Price__Receipts-V3"},"priceModifications":{"type":"array","description":"List of additional fees and reductions represented as price modifications.\n
If there are no price modifications, an empty list is displayed","items":{"$ref":"#/components/schemas/PriceModification__Receipts-V3"}}},"description":"List of billed logistic costs, if exists for this receipt.\n
This list is only used in context of receiptType PURCHASE or REFUND.\n
If there are no entries the lists is displayed as empty"},"DeliveryCostPartialRefundPosition__Receipts-V3":{"title":"DeliveryCostPartialRefundPosition","type":"object","description":"This information is currently not available, will be an empty array."},"Details__Receipts-V3":{"title":"Details","required":["description"],"type":"object","properties":{"description":{"type":"string","description":"Additional info often printed on the pdf for a PriceModification object (on German receipts always in German)
\nIf PriceModification object is of type:\n* **PARTNER_DISCOUNT** - discount name, provided with sales order event as part of positionGroupPrice: (What we print on the pdf ): e.g. \"1 € Rabatt\"\n* **DEFECT_COMPENSATION** - ( German translation of defect compensation) \"**Mängelausgleich**\"\n* **REFUND_COMPLAINT_ITEM** - hard coded \"Preisnachlass Reklamation Artikel\"\n* **REFUND_PAYPAL_DISPUTE** - hard coded “Preisnachlass PayPal Disput“\n* **REFUND_ESCALATION** - hard coded “Preisnachlass Escalation“\n* **REFUND_CREDIT_CARD_DISPUTE** - hard coded \"Preisnachlass CREDIT_CARD Disput\"\n","example":"1 € Rabatt"},"id":{"type":"string","description":"Discount code applied to the order to get a reduction. Available when reduction is of type PARTNER_DISCOUNT","example":"82ffff8f-8709-4060-bcd3-ebdabbbc6514"},"linkedReceiptNumber":{"type":"string","description":"Allows to link an earlier purchase or (partial)refund receipt by human-readable identifier.\n
If PriceModification object is of type:\n* **DEFECT_COMPENSATION**: In case of previous (partial) refunds this field contains the human-readable identifier of the partial refund with which the previous refund was made","example":"E-DE-123456789-2020-7"},"linkedReceiptCreationDate":{"type":"string","description":"Allows to show creation date of linked earlier purchase or (partial)refund receipt.\n
If PriceModification object is of type:\n* **DEFECT_COMPENSATION**: In case of previous (partial) refunds this field contains the creation date of linked receipt with which the previous refund was made. (ISO-8601 format)","format":"date-time","example":"2022-06-30T14:35:00.221Z"},"type":{"type":"string","description":"The specific types of discounts provided for Marketplace. This field is only applicable when the priceModificationType for the item is PARTNER_DISCOUNT\n
Possible values:\n* **PARTNER_DISCOUNT** - a Partner Discount provided because of a booked service \"Rabattaktion\" by the partner\n* **PLATFORM_DISCOUNT** - a Discount for a platform frame provided because of a booked service \"Marktplatz Rabattaktion\" by the partner\n","example":"PARTNER_DISCOUNT","enum":["PARTNER_DISCOUNT","PLATFORM_DISCOUNT"]},"reason":{"type":"string","description":"Detailed reason of priceModifications of priceModificationType REFUND_GOODWILL_ITEM.\n\nPossible values:\n* **GOODWILL_ITEM_FOR_FREE** - Refund item price as goodwill\n* **GOODWILL_ITEM_RETURN_REJECTED** - Price reduction after return rejection as goodwill\n* **GOODWILL_ITEM_DISCOUNT_EXPIRED** - Price reduction after using old discount code as goodwill\n* **GOODWILL_OTHER** - Individual price reduction as goodwill\n","example":"GOODWILL_ITEM_REFUND_REJECTED","enum":["GOODWILL_ITEM_FOR_FREE","GOODWILL_ITEM_RETURN_REJECTED","GOODWILL_ITEM_DISCOUNT_EXPIRED","GOODWILL_OTHER"]},"linkedPositionItemId":{"type":"string","description":"Allows to show the unique identifier (salesOrder)PositionItem of an earlier (partial)refund receipt of items.
\nA (salesOrder)PositionItem is the smallest unit of an item that can be ordered.\n\nIt will be present in refund receipts for those _“priceModificationType” which are applicable after purchase receipts are generated_.","example":"d76533b7-9c98-4be5-97a2-c54ba1929b33"}},"description":"Additional information of increase or decrease of the line item described by this PriceModification object"},"ItemPartialRefundPosition__Receipts-V3":{"title":"ItemPartialRefundPosition","required":["articleNumber","partialRefundAmount","positionItemIds","productTitle"],"type":"object","properties":{"partialRefundDetails":{"$ref":"#/components/schemas/PartialRefundDetails__Receipts-V3"},"lineNumber":{"type":"integer","description":"Number of line item in which the information is printed on the pdf document of the receipt.\n
This information is not reliably provided for older receipts","format":"int32","example":3},"sku":{"type":"string","description":"Stock keeping unit of item. Unique item identifier on partner side","example":"123e4567-e89b-12d3-a456-426652340000"},"articleNumber":{"type":"string","description":"Unique Identifier of item the customer knows from order process","example":"S081B05AP2"},"productTitle":{"type":"string","description":"Product description of item the customer knows from the order process","example":"Bobux »Baby Halbschuhe DIMENSION II für Mädchen« Schnürschuh"},"variationAttributes":{"type":"string","description":"Additional attributes for unique description of item, if different variants of the item are possible. (String of comma seperated dimensions)\n\nATTENTION: In previous version, the information exists as dimensions","example":"Weiß, 19"},"positionItemIds":{"type":"array","description":"List of unique identifiers of specific instances of ordered items.\n
A (salesOrder)PositionItem is the smallest unit of an item that can be ordered","example":["476bb1ac-a227-4710-8ee4-f297a38a309c"],"items":{"type":"string","description":"List of unique identifiers of specific instances of ordered items.\n
A (salesOrder)PositionItem is the smallest unit of an item that can be ordered","example":"[\"476bb1ac-a227-4710-8ee4-f297a38a309c\"]"}},"partialRefundAmount":{"$ref":"#/components/schemas/Price__Receipts-V3"}},"description":"List of billed partial refunds of items.\n
This list is only used in context of receiptType PARTIAL_REFUND.\n
If there are no entries the lists is displayed as empty"},"ItemPosition__Receipts-V3":{"title":"ItemPosition","required":["articleNumber","positionItemIds","positionSum","priceModifications","productTitle","quantity","unitPrice"],"type":"object","properties":{"lineNumber":{"type":"integer","description":"Number of line item in which the information is printed on the pdf document.\n
This information is not reliably provided for older receipts","format":"int32","example":1},"sku":{"type":"string","description":"Stock keeping unit of item. Unique item identifier on partner side.\n
This information is not reliably provided for older receipts","example":"123e4567-e89b-12d3-a456-426652340000"},"expectedPerformancePeriod":{"type":"string","description":"Vague performance date. As the exact date is not known when generating the receipt, this information gives an indication when the item will be shipped","example":"Nach Zahlung wird die Lieferung vorbereitet."},"articleNumber":{"type":"string","description":"Unique Identifier of item the customer knows from order process.\n\nATTENTION: Different from the previous version, the field also contains the promotion. In last version the promotion was provided separately","example":"S081B05AP2"},"productTitle":{"type":"string","description":"Product description of item the customer knows from the order process","example":"Bobux »Baby Halbschuhe DIMENSION II für Mädchen« Schnürschuh"},"variationAttributes":{"type":"string","description":"Additional attributes for unique description of an item, if different variants of the item are possible. (String of comma seperated dimensions)\n\nATTENTION: In previous version the information was called dimensions","example":"Weiß, 19"},"positionItemIds":{"type":"array","description":"List of unique identifiers of specific instances of ordered items.\nA (salesOrder)PositionItem is the smallest unit of an item that can be ordered.\n
If quantity of the specific LineItem object is bigger than one the list contains more than one entry","example":["476bb1ac-a227-4710-8ee4-f297a38a309c","34gfb1ac-4f45-4710-4ef4-t555a38a309g"],"items":{"type":"string","description":"List of unique identifiers of specific instances of ordered items.\nA (salesOrder)PositionItem is the smallest unit of an item that can be ordered.\n
If quantity of the specific LineItem object is bigger than one the list contains more than one entry","example":"[\"476bb1ac-a227-4710-8ee4-f297a38a309c\",\"34gfb1ac-4f45-4710-4ef4-t555a38a309g\"]"}},"quantity":{"type":"integer","description":"Quantity","format":"int32","example":2},"unitPrice":{"$ref":"#/components/schemas/Price__Receipts-V3"},"priceToPayPerPositionItems":{"type":"array","description":"Price of each unit of the item i.e., price of each positionItemId.
It will be available only for PURCHASE receipt","items":{"$ref":"#/components/schemas/PriceToPayPerPositionItem__Receipts-V3"}},"positionSum":{"$ref":"#/components/schemas/Price__Receipts-V3"},"priceModifications":{"type":"array","description":"List of additional fees and reductions represented as price modifications.\n
Currently we only know reductions.\n
If there are no entries the list is displayed as empty","items":{"$ref":"#/components/schemas/PriceModification__Receipts-V3"}}},"description":"List of billed items, if exists.\n
This list is only used in context of receiptType PURCHASE or REFUND.\n
If there are no entries the lists is displayed as empty"},"LineItems__Receipts-V3":{"title":"LineItems","required":["deliveryCosts","deliveryFeePartialRefundPositions","itemPartialRefundPositions","itemPositions","servicePartialRefundPositions","servicePositions"],"type":"object","properties":{"itemPositions":{"type":"array","description":"List of billed items, if exists.\n
This list is only used in context of receiptType PURCHASE or REFUND.\n
If there are no entries the lists is displayed as empty","items":{"$ref":"#/components/schemas/ItemPosition__Receipts-V3"}},"itemPartialRefundPositions":{"type":"array","description":"List of billed partial refunds of items.\n
This list is only used in context of receiptType PARTIAL_REFUND.\n
If there are no entries the lists is displayed as empty","items":{"$ref":"#/components/schemas/ItemPartialRefundPosition__Receipts-V3"}},"servicePositions":{"type":"array","description":"List of billed B2C services, if exists for this receipt.\n
This list is only used in context of receiptType PURCHASE or REFUND.\n
If there are no entries the lists is displayed as empty","items":{"$ref":"#/components/schemas/ServicePosition__Receipts-V3"}},"servicePartialRefundPositions":{"type":"array","description":"List of billed partial refunds of services.","items":{"$ref":"#/components/schemas/ServicePartialRefundPosition__Receipts-V3"}},"deliveryCosts":{"type":"array","description":"List of billed logistic costs, if exists for this receipt.\n
This list is only used in context of receiptType PURCHASE or REFUND.\n
If there are no entries the lists is displayed as empty","items":{"$ref":"#/components/schemas/DeliveryCost__Receipts-V3"}},"deliveryFeePartialRefundPositions":{"type":"array","description":"This information is currently not available, will be an empty array.","items":{"$ref":"#/components/schemas/DeliveryCostPartialRefundPosition__Receipts-V3"}}},"description":"Line items for which settlement is made.\n\nATTENTION:\n* In previous version this name was used for itemPositions only. Now there is a substructure that cares about all billing object of a receipt\n* The object is currently define by mistake as required, we will change it in future as it’s possible that we introduce new receiptTypes without lineItems. For current receiptTypes PURCHASE, PARTIAL_REFUND and REFUND lineItems will always exists."},"LinkedItemDetails__Receipts-V3":{"title":"LinkedItemDetails","required":["articleNumber","productTitle","serviceRelations"],"type":"object","properties":{"itemReceiptNumber":{"type":"string","description":"Human-readable identifier refers to the receipt the linked item was billed.
\nDisplayed only if item is billed with another receipt.
\nIn case of receiptType\n* **PURCHASE** - **receiptNumber of purchase receipt**.
\nIf this field is not present, you will find information in receipt.receiptNumber\n* **REFUND** - **receiptNumber of purchase receipt**.
\nIf this field is not present ,you will find information in receipt.linkedReceiptNumber\n","example":"R-DE-123456789-2020-715"},"itemPartnerName":{"type":"string","description":"Name of the partner who sold the linked item.\n
Displayed only if the partner is different from partner of the receipt","example":"Tonio Mertez e.K."},"sku":{"type":"string","description":"Stock keeping unit of the linked item. Unique item identifier on partner side\n
This information is not reliably provided for older receipts.\n","example":"123e4567-e89b-12d3-a456-426652340000"},"articleNumber":{"type":"string","description":"Unique Identifier of linked item the customer knows from order process.\n\nATTENTION: Different from the previous version, the field also contains the promotion. In last version the promotion was provided separately","example":"S081B05AP2"},"productTitle":{"type":"string","description":"Product description of linked item the customer knows from the order process","example":"Bobux »Baby Halbschuhe DIMENSION II für Mädchen« Schnürschuh"},"serviceRelations":{"type":"array","description":"List of ServiceRelation objects.\n
Contains entries if services were sold together with items otherwise list is empty","items":{"$ref":"#/components/schemas/ServiceRelation__Receipts-V3"}}},"description":"Additional information to an item directly related to the service.\n
Object exists only if the service was sold together with an item"},"PartialRefundDetails__Receipts-V3":{"title":"PartialRefundDetails","type":"object","properties":{"benefit":{"$ref":"#/components/schemas/Benefit__Receipts-V3"}},"description":"Additional information about the granted partial refund to this item.\n"},"Partner__Receipts-V3":{"title":"Partner","required":["city","countryCode","partnerName","representedBy","street","vatId","zipCode"],"type":"object","properties":{"partnerName":{"type":"string","description":"Name of the selling partner/company.\n\nATTENTION: In previous version the information was called name","example":"Funky Staff GmbH & Co. KG"},"street":{"type":"string","description":"Street and house number of company address","example":"Berner Straße 109"},"zipCode":{"type":"string","description":"Zip code of company address","example":"60437"},"city":{"type":"string","description":"City of company address","example":"Hamburg"},"countryCode":{"type":"string","description":"Country of company address represented as country code (ISO 3166-1 alpha-3)","example":"DEU"},"vatId":{"type":"string","description":"Value added tax identification number of partner","example":"DE215947224"},"representedBy":{"type":"string","description":"The partner's representative(s).\n\nATTENTION: In previous version the information was called legalRepresentatives","example":"Monika Sievers, Paul Ackermann"},"registerCourt":{"type":"string","description":"Court where the company is registered.
Information exists if it's maintained in partner core data.\n\nATTENTION: In previous version the information was called districtCourt","example":"Amtsgericht Hamburg"},"commercialRegisterNumber":{"type":"string","description":"Commercial register number. Unique in context of register court.
Information exists if it's maintained in partner core data.\n\nATTENTION: In previous version the information was called registerNumber","example":"HRB 5433221"},"headOfSupervisoryBoard":{"type":"string","description":"The partner's head of supervisory board.
Information exists if it's maintained in partner core data","example":"Hugo Steiner"},"shopName":{"type":"string","description":"Alias name of partner.
Information exists if it's maintained in partner core data","example":"Fun-Shop"},"weeeRegistrationNumber":{"type":"string","description":"WEEE registration number of partner.
Information exists if it's maintained in partner core data"}},"description":"Partner for whom the receipt is created"},"Payment__Receipts-V3":{"title":"Payment","required":["paymentMethod","paymentProvider"],"type":"object","properties":{"paymentProvider":{"type":"string","description":"Payment Provider chosen for the order.
\nPossible values:\n* **PLAZA** - Ratepay\n* **OTTOPAYMENTS** - OTTO Payments\n","example":"OTTOPAYMENTS","enum":["PLAZA","OTTOPAYMENTS"]},"paymentMethod":{"type":"string","description":"Payment method chosen by the customer to pay for this order.\n\nPossible values:\n* **INVOICE_SINGLE / INVOICE_INSTALLMENT** - payment on invoice (with or without installments)\n* **DIRECT_DEBIT / DIRECT_DEBIT_INSTALLMENTS** - payment by direct debit (with or without installments)\n* **PREPAYMENT** - payment by prepayment\n* **PAYPAL** - payment by PayPal\n* **CREDIT_CARD** - payment by credit or debit card (only applicable for paymentProvider = OTTOPAYMENTS)\n* **CREDIT_CARD_ONLINE** - payment by credit card (only applicable for old paymentProvider = PLAZA)","example":"CREDIT_CARD_ONLINE","enum":["CREDIT_CARD_ONLINE","INVOICE_SINGLE","INVOICE_INSTALLMENTS","DIRECT_DEBIT_INSTALLMENTS","PREPAYMENT","PAYPAL","DIRECT_DEBIT","CREDIT_CARD"]},"installmentCount":{"type":"integer","description":"For payment methods with installments, this attribute indicates how many installments the customer has chosen when placing the order.\n
Only available on receipts of receiptType PURCHASE.\n
This information is not reliably provided for older receipts","format":"int32","example":3},"paymentBreak":{"type":"boolean","description":"The field indicates whether customer has chosen paymentBreak

Set to true, if customer has chose paymentBreak
Set to false, if customer hasn’t chosen paymentBreak

"}},"description":"Payment details"},"Price__Receipts-V3":{"title":"Price","required":["gross","taxRate","taxType"],"type":"object","properties":{"taxType":{"type":"string","description":"The fields indicates what kind of tax the price object includes.
\nCurrently prices of the following taxTypes are possible.\n* **VAT** - vat rate\n* **INSURANCE** - insurance tax\n","example":"VAT","enum":["VAT","INSURANCE"]},"taxRate":{"type":"string","description":"Applied tax rate, if there is any.
\nCurrently the entry can only be a decimal number.\n","example":"19.0"},"gross":{"description":"Calculated gross value","allOf":[{"title":"MonetaryAmount","required":["amount","currency"],"type":"object","properties":{"amount":{"type":"number","description":"Value of the monetary amount expressed in currency.
\nThe number format expects a decimal point, like 10.99. Numbers without a decimal point are taken as a unit of the given currency,\nE.g. 10.05 EUR = 10 Euro and 5 Cent\n","example":209.82},"currency":{"type":"string","description":"Currency of monetary amount (ISO-4217)","example":"EUR"}}}]},"net":{"description":"Calculated net value
\nThis information is not reliably provided for older receipts.This information is not reliably provided for older receipts for all Price objects.. In the beginning we only provides this value for receipt.totals. \n
In receipts generated after the 01-01-2023 data should always be set in all Price objects.\n","allOf":[{"title":"MonetaryAmount","required":["amount","currency"],"type":"object","properties":{"amount":{"type":"number","description":"Value of the monetary amount expressed in currency.
\nThe number format expects a decimal point, like 10.99. Numbers without a decimal point are taken as a unit of the given currency,\nE.g. 10.05 EUR = 10 Euro and 5 Cent\n","example":174.85},"currency":{"type":"string","description":"Currency of monetary amount (ISO-4217)","example":"EUR"}}}]},"tax":{"description":" Calculated tax value
\n This information is not reliably provided for older receipts.This information is not reliably provided for older receipts for all Price objects.. In the beginning we only provides this value for receipt.totals. \n
In receipts generated after the 01-01-2023 data should always be set in all Price objects.\n","allOf":[{"title":"MonetaryAmount","required":["amount","currency"],"type":"object","properties":{"amount":{"type":"number","description":"Value of the monetary amount expressed in currency.
\nThe number format expects a decimal point, like 10.99. Numbers without a decimal point are taken as a unit of the given currency,\nE.g. 10.05 EUR = 10 Euro and 5 Cent\n","example":34.97},"currency":{"type":"string","description":"Currency of monetary amount (ISO-4217)","example":"EUR"}}}]}},"description":"Costs of an object\nThere are different definitions of Price objects in Receipt structure:\n * **unitPrice** - Original price for quantity a line item object\n * **positionSum** - Price for quantity x unitPrice of a line item object minus reductions of all sub priceModification objects, if exist\n * **partialRefundAmount** - Granted reduction by the partner on line item object\n * **priceModificationAmount** - Total reduction for the super ordinated line item object. If the line item object has a quantity, this is already been taken into account in this amount.\n * **priceToPay** - Price for quantity one minus all instant reductions like partner discount ... when selling (excl. earlier partial refunds).
Only available on receipts of receiptType PURCHASE.\n"},"PriceModification__Receipts-V3":{"title":"PriceModification","required":["details","priceModificationAmount","priceModificationType"],"type":"object","properties":{"lineNumber":{"type":"integer","description":"Number of line item in which the information is printed on the pdf document of the receipt.\n
On the pdf documents increases and decreases do not necessarily have to be shown on the same line. If there is a discrepancy, it is visible by different line numbers of this object and the parent line item object\n
This information is not reliably provided for older receipts","format":"int32","example":1},"priceModificationType":{"type":"string","description":"This type describes the special increases or decreases in detail and how to deal with it.\n\nThe following priceModificationTypes are possible:\n* **PARTNER_DISCOUNT** - Partner-financed immediate discount granted to the customer at the time of purchase.
Reduction of parent object item position on PURCHASE and REFUND receipt\n* **DEFECT_COMPENSATION** / **REFUND_COMPLAINT_ITEM** - Partial refund already refunded by a partial refund receipt to compensate a defect.
Reduction of parent object item position on REFUND receipt\n* **REFUND_PAYPAL_DISPUTE** - Partial or full amount of item price was refunded due to a dispute in Paypal payment.
Reduction of parent object item or service position on REFUND receipt\n* **REFUND_ESCALATION** - Refund already refunded by a partial refund receipt due to an escalation.
Reduction of parent object item position on REFUND receipt\n* **REFUND_PARTIAL_AMOUNT_AFTER_SERVICE_CANCELLATION** - A partial refund already refunded after service could not fulfilled completely.
Reduction of parent object item and service position on REFUND receipt\n* **REFUND_CREDIT_CARD_DISPUTE** - Refund already refunded by a partial refund receipt due to dispute in CREDIT_CARD payment. Reduction of parent object item or service position on REFUND receipt\n","example":"PARTNER_DISCOUNT","enum":["PARTNER_DISCOUNT","DEFECT_COMPENSATION","REFUND_COMPLAINT_ITEM","REFUND_PAYPAL_DISPUTE","REFUND_ESCALATION","REFUND_PARTIAL_AMOUNT_AFTER_SERVICE_CANCELLATION","REFUND_CREDIT_CARD_DISPUTE"]},"details":{"$ref":"#/components/schemas/Details__Receipts-V3"},"priceModificationAmount":{"$ref":"#/components/schemas/Price__Receipts-V3"}},"description":"List of additional fees and reductions represented as price modifications.\n
If there are no price modifications, an empty list is displayed"},"PriceToPayPerPositionItem__Receipts-V3":{"title":"PriceToPayPerPositionItem","required":["positionItemIds","priceToPay"],"type":"object","properties":{"positionItemIds":{"type":"array","description":"List of unique identifiers of specific instances of ordered items.\n
A (salesOrder)PositionItem is the smallest unit of an item that can be ordered.\n","example":["476bb1ac-a227-4710-8ee4-f297a38a309c","34gfb1ac-4f45-4710-4ef4-t555a38a309g"],"items":{"type":"string","description":"List of unique identifiers of specific instances of ordered items.\n
A (salesOrder)PositionItem is the smallest unit of an item that can be ordered.\n","example":"[\"476bb1ac-a227-4710-8ee4-f297a38a309c\",\"34gfb1ac-4f45-4710-4ef4-t555a38a309g\"]"}},"priceToPay":{"$ref":"#/components/schemas/Price__Receipts-V3"}},"description":"Price of each unit of the item i.e., price of each positionItemId.
It will be available only for PURCHASE receipt"},"Receipt__Receipts-V3":{"title":"Receipt","required":["amountDue","creationDate","customer","isRealReceipt","lineItems","orderDate","orderNumber","partner","payment","receiptNumber","receiptType","salesOrderId","totals"],"type":"object","properties":{"receiptType":{"type":"string","description":"Categorisation that classifies the receipts according to the main characteristics\n\nATTENTION: In previous version the information was called type\n","example":"REFUND","enum":["PURCHASE","REFUND","PARTIAL_REFUND"]},"isRealReceipt":{"type":"boolean","description":" Counterpart to the sentence \"Dies ist kein Beleg/keine Rechnung im Sinne des Umsatzsteuergesetzes und berechtigt nicht zum Vorsteuerabzug.\" on pdf document.\n * Set to **true** since real customer invoices/refunds for shipments to locations in domestic tax territory are created.\n * Set to **false** for technical receipts not visible to customer or on receipts with delivery addresses on Helgoland or in Büsingen\n","example":true},"receiptNumber":{"type":"string","description":"Human readable identifier of a receipt known by customer.
Guaranteed to be unique per partner","example":"E-DE-123456789-2020-7"},"creationDate":{"type":"string","description":"Date when receipt is created by system (UTC in ISO-8601 format)","format":"date-time"},"fulfillmentDate":{"type":"string","description":"Date when service fulfilled.","format":"date-time"},"salesOrderId":{"type":"string","description":"Technical identifier of corresponding sales order","example":"80ec6483-4d53-44d8-9ba7-e846ab24da38"},"orderNumber":{"type":"string","description":"Order number of corresponding sales order","example":"1224567"},"orderDate":{"type":"string","description":"Order date of corresponding sales order (UTC in ISO-8601 format)","format":"date-time"},"shipmentDate":{"type":"string","description":"Date when physical items of this receipt were handed over to the carrier to be delivered to the customer (UTC in ISO-8601 format).
Only available on receipts of receiptType PURCHASE.","format":"date-time"},"shipment":{"$ref":"#/components/schemas/Shipment__Receipts-V3"},"linkedReceiptNumber":{"type":"string","description":"Human-readable identifier of linked receipt.
In case of receiptType PARTIAL_REFUND or REFUND it is the receiptINumber of purchase receipt.\n\nATTENTION: In previous version the information was called originalReceiptNumber","example":"R-DE-123456789-2020-1507"},"linkedCreationDate":{"type":"string","description":"Creation date of linked receipt (UTC in ISO-8601 format).
Only available if there is a linked receipt.\n\nATTENTION: In previous version the information was called originalCreatedDate","format":"date-time"},"payment":{"$ref":"#/components/schemas/Payment__Receipts-V3"},"partner":{"$ref":"#/components/schemas/Partner__Receipts-V3"},"customer":{"$ref":"#/components/schemas/Customer__Receipts-V3"},"deliveryAddress":{"$ref":"#/components/schemas/Address__Receipts-V3"},"lineItems":{"$ref":"#/components/schemas/LineItems__Receipts-V3"},"totals":{"type":"array","description":"Total amounts of receipt per tax type and tax rate","items":{"$ref":"#/components/schemas/Price__Receipts-V3"}},"refundType":{"type":"string","description":" Field describes the business case of a refund in more detail.\n
Only available on receipts of receiptType REFUND and not reliable provided on older partial refund receipts.\n\n The following refundTypes are possible:\n * **RETURN** - Refund due to a return of an item\n * **CANCELLATION** - Refund of delivery fees due to a cancellation\n * **SERVICE_FULL_REFUND_CANCELLED_BY_SDU** - Refund of a service without item\n * **SERVICE_FULL_REFUND_PRODUCT_RETURNED** - Refund a service parallel to an item return\n","enum":["RETURN","CANCELLATION","SERVICE_FULL_REFUND_CANCELLED_BY_SDU","SERVICE_FULL_REFUND_PRODUCT_RETURNED"]},"partialRefundType":{"type":"string","description":"Business case of partial refund chosen by partner. Has an impact on the business flow and the PDF.\n
Only available on receipts of receiptType PARTIAL_REFUND and not reliable provides on older partial refunds receipts.\n\nPossible values:\n* **REFUND_COMPLAINT_ITEM** - Refund because of justified customer complaint on item\n* **REFUND_PAYPAL_DISPUTE** - Partial or full amount of item price was refunded due to a dispute in Paypal payment\n* **REFUND_ESCALATION** - Partial amount of item price was refunded due to an escalation\n* **REFUND_PARTIAL_AMOUNT_AFTER_SERVICE_CANCELLATION** - Lowering of service price after service was not fulfilled completely\n* **REFUND_CREDIT_CARD_DISPUTE** - Partial or full amount of item price was refunded due to a dispute in CREDIT_CARD payment\n","example":"REFUND_COMPLAINT_ITEM","enum":["REFUND_COMPLAINT_ITEM","REFUND_PAYPAL_DISPUTE","REFUND_ESCALATION","REFUND_PARTIAL_AMOUNT_AFTER_SERVICE_CANCELLATION","REFUND_CREDIT_CARD_DISPUTE"]},"amountDue":{"description":"The amountDue documents the gross amount a customer still has to pay or will be refunded respectively owes less (the latter decision depends on the chosen payment method) with this receipt.\n
As in case of receiptType PURCHASE and a prepaid payment method we know for sure that the customer has already paid in advance, so the amount is 0 € otherwise the content is identically with totalsGrossAmount","allOf":[{"title":"MonetaryAmount","required":["amount","currency"],"type":"object","properties":{"amount":{"type":"number","description":"Value of the monetary amount expressed in currency.
\nThe number format expects a decimal point, like 10.99. Numbers without a decimal point are taken as a unit of the given currency,\nE.g. 10.05 EUR = 10 Euro and 5 Cent\n","example":209.82},"currency":{"type":"string","description":"Currency of monetary amount (ISO-4217)","example":"EUR"}}}]},"totalsGrossAmount":{"description":"Gross amounts of totals summed up over all prices. Only available on receipts of receiptType PURCHASE","allOf":[{"title":"MonetaryAmount","required":["amount","currency"],"type":"object","properties":{"amount":{"type":"number","description":"Value of the monetary amount expressed in currency.
\nThe number format expects a decimal point, like 10.99. Numbers without a decimal point are taken as a unit of the given currency,\nE.g. 10.05 EUR = 10 Euro and 5 Cent\n","example":209.82},"currency":{"type":"string","description":"Currency of monetary amount (ISO-4217)","example":"EUR"}}}]},"totalsReductions":{"type":"array","description":"Reduction amounts on total value of receipts (currently it includes voucher reduction)","items":{"$ref":"#/components/schemas/TotalsReduction__Receipts-V3"}}},"description":"Collection of all details of a receipt"},"ServicePartialRefundPosition__Receipts-V3":{"title":"ServicePartialRefundPosition","type":"object","properties":{"lineNumber":{"type":"integer","description":"Number of line item in which the information is printed on the pdf document of the receipt.\n
This information is not reliably provided for older receipts","format":"int32"},"serviceType":{"type":"string","description":"Categorization that classifies services according to their main characteristics. Services of the same type are often treated in the same way.\nCurrently, the processing of the following types are possible:\n* **DISPOSAL** - Free take away of old technical devices required by law\n* **INSURANCE** - Product insurance","enum":["DISPOSAL","INSURANCE"]},"serviceName":{"type":"string","description":"Service name of a special specification of a service type that the customer has seen in the ordering process."},"servicePositionItemIds":{"type":"array","description":"List of unique identifiers of specific instances of services. A servicePositionItem is the smallest unit of a service that can be ordered. If quantity of this object is bigger than one the list contains more than one entry.","items":{"type":"string","description":"List of unique identifiers of specific instances of services. A servicePositionItem is the smallest unit of a service that can be ordered. If quantity of this object is bigger than one the list contains more than one entry."}},"partialRefundAmount":{"$ref":"#/components/schemas/Price__Receipts-V3"},"insurancePeriod":{"type":"integer","description":"Services of serviceType WARRANTY or INSURANCE could be offered with different durations. This field will show the duration as month.","format":"int32"}},"description":"List of billed partial refunds of services."},"ServicePosition__Receipts-V3":{"title":"ServicePosition","required":["positionSum","priceModifications","quantity","serviceName","servicePositionItemIds","unitPrice"],"type":"object","properties":{"lineNumber":{"type":"integer","description":"Number of line item in which the information is printed on the pdf document of the receipt.\n
This information is not reliably provided for older receipts","format":"int32","example":3},"serviceType":{"type":"string","description":"Categorization that classifies services according to their main characteristics. Services of the same type are often treated in the same way.\nCurrently, the processing of the following types are possible:\n* **DISPOSAL** - Free take away of old technical devices required by law\n* **INSURANCE** - Product insurance\n","example":"DISPOSAL","enum":["DISPOSAL","INSURANCE"]},"expectedPerformancePeriod":{"type":"string","description":"Vague performance date.
As the exact date is not known when generating the receipt, this information gives an indication when the service is expected to be fulfilled"},"serviceName":{"type":"string","description":"Service name the customer knows from the order process","example":"48 Monate Langzeitgarantie Personal Care"},"servicePositionItemIds":{"type":"array","description":"List of unique identifiers of specific instances of services.\n
A servicePositionItem is the smallest unit of a service that can be ordered.\n
If quantity of this object is bigger than one, the list contains more than one entry","example":["476bb1ac-a2277-4710-8ee4-f297a38a309c","476bb1ac-a227-4710-8ee4-f297a38a309b"],"items":{"type":"string","description":"List of unique identifiers of specific instances of services.\n
A servicePositionItem is the smallest unit of a service that can be ordered.\n
If quantity of this object is bigger than one, the list contains more than one entry","example":"[\"476bb1ac-a2277-4710-8ee4-f297a38a309c\",\"476bb1ac-a227-4710-8ee4-f297a38a309b\"]"}},"linkedItemDetails":{"$ref":"#/components/schemas/LinkedItemDetails__Receipts-V3"},"quantity":{"type":"integer","description":"Quantity","format":"int32","example":2},"unitPrice":{"$ref":"#/components/schemas/Price__Receipts-V3"},"positionSum":{"$ref":"#/components/schemas/Price__Receipts-V3"},"priceModifications":{"type":"array","description":"List of additional fees and reductions represented as price modifications.\n
Currently we only know reductions.\n
If there are no entries the list is displayed as empty","items":{"$ref":"#/components/schemas/PriceModification__Receipts-V3"}},"insurancePeriod":{"type":"integer","description":"Services of serviceType WARRANTY or INSURANCE could be offered with different durations. This field will show the duration as month.","format":"int32"}},"description":"List of billed B2C services and insurances."},"ServiceRelation__Receipts-V3":{"title":"ServiceRelation","required":["positionItemId","servicePositionItemId"],"type":"object","properties":{"servicePositionItemId":{"type":"string","description":"Unique identifier of a specific instance of a service. ServicePositionItem is the smallest unit of service that can be ordered","example":"476bb1ac-a2277-4710-8ee4-f297a38a309c"},"positionItemId":{"type":"string","description":"Unique identifier of a specific instance of an ordered item (salesOrder)PositionItem is the smallest unit of an item that can be ordered","example":"476bb1ac-a2277-4710-8ee4-f297a38a309b"}},"description":"A ServiceRelation object describes the relationship between a specific instance of a servicePositionItem object and a specific instance of a (salesOrder)PositionItem object"},"Shipment__Receipts-V3":{"title":"Shipment","required":["shipFromAddress"],"type":"object","properties":{"shipFromAddress":{"$ref":"#/components/schemas/AddressInformation__Receipts-V3"}},"description":"Shipment details.
Only provided on receipts of receiptType PURCHASE containing items.
This information is not reliably provided for receipts before 01.03.2024."},"TotalsReduction__Receipts-V3":{"title":"TotalsReduction","required":["gross","type"],"type":"object","properties":{"type":{"type":"string","description":"Type of reductions applied on total value of receipts.\n\nPossible types:\n* **VOUCHER** - voucher used to pay the receipt\n","example":"VOUCHER","enum":["VOUCHER"]},"details":{"$ref":"#/components/schemas/TotalsReductionDetails__Receipts-V3"},"gross":{"description":"Gross value of reductions. This will lower the amountDue","allOf":[{"title":"MonetaryAmount","required":["amount","currency"],"type":"object","properties":{"amount":{"type":"number","description":"Value of the monetary amount expressed in currency.
\nThe number format expects a decimal point, like 10.99. Numbers without a decimal point are taken as a unit of the given currency,\nE.g. 10.05 EUR = 10 Euro and 5 Cent\n"},"currency":{"type":"string","description":"Currency of monetary amount (ISO-4217)","example":"EUR"}}}]}},"description":"Reduction amounts on total value of receipts (currently it includes voucher reduction)"},"TotalsReductionDetails__Receipts-V3":{"title":"TotalsReductionDetails","type":"object","properties":{"voucherCode":{"type":"string","description":"The code of voucher associated with the receipt (contains only last 4 digits of code)","example":"****EFGH"}},"description":"Additional information of reductions"},"Link__Receipts-V3":{"title":"Link","type":"object","properties":{"href":{"type":"string","description":"The url of the link","example":"/v3/receipts?limit=128&page=2"},"rel":{"type":"string","description":"The relation type of the link. See also https://www.iana.org/assignments/link-relations/link-relations.xhtml. The relation type 'next' is used for paging. The relation type 'self' refers to the url of the resource","example":"next,self,describedby"}},"description":"A link to various resources. a Link can have different meanings and targets. The type of relation is specified with the property 'rel'. "},"ReceiptsList__Receipts-V3":{"title":"ReceiptsList","type":"object","properties":{"resources":{"type":"array","description":"The list of queried resources. In this case partner receipts.","items":{"$ref":"#/components/schemas/Receipt__Receipts-V3"}},"links":{"type":"array","description":"Links related to the list. E.g. the link to the successive list used during paging.","items":{"$ref":"#/components/schemas/Link__Receipts-V3"}}}},"PriceReductionResponse__Price-Reductions-V1":{"title":"PriceReductionResponse","type":"object","properties":{"salesOrderId":{"type":"string","description":"salesOrderId for an item","format":"uuid"},"totalPriceReduction":{"description":"sum of all the price reductions for a positionItemId.","allOf":[{"title":"MonetaryAmount","type":"object","properties":{"amount":{"type":"number","description":"Holds the value of the monetary amount expressed in a currency, e.g. euros. The number format expects a decimal point, like 10.99. Numbers without a decimal point are taken as a unit of the given currency, e.g. 10 is taken as 10 euros","example":121.01},"currency":{"type":"string","description":"Holds the currency of the monetary amount expressed as a shortcut according to ISO 4217 and http://publications.europa.eu/code/de/de-5000700.htm. Currently Only EUR is supported as a currency","example":"EUR"}}}]},"invoicePrice":{"description":"the price of the positionItemId as per the invoice generated for the order.","allOf":[{"title":"MonetaryAmount","type":"object","properties":{"amount":{"type":"number","description":"Holds the value of the monetary amount expressed in a currency, e.g. euros. The number format expects a decimal point, like 10.99. Numbers without a decimal point are taken as a unit of the given currency, e.g. 10 is taken as 10 euros","example":121.01},"currency":{"type":"string","description":"Holds the currency of the monetary amount expressed as a shortcut according to ISO 4217 and http://publications.europa.eu/code/de/de-5000700.htm. Currently Only EUR is supported as a currency","example":"EUR"}}}]},"priceReductions":{"type":"array","description":"all price reductions applied for an item","items":{"$ref":"#/components/schemas/PriceReductionDetail__Price-Reductions-V1"}},"positionItemId":{"type":"string","description":"positionItemId for an item","format":"uuid"}}},"APIErrorResponse__Price-Reductions-V1":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/APIResponse__Price-Reductions-V1"}}}},"APIResponse__Price-Reductions-V1":{"type":"object","properties":{"path":{"type":"string"},"title":{"type":"string"},"code":{"type":"integer","format":"int32"},"detail":{"type":"string"},"logref":{"type":"string"}}},"PriceReductionDetail__Price-Reductions-V1":{"type":"object","properties":{"receiptNumber":{"type":"string","description":"receiptNumber of the receipt generated for the price reduction. The receiptNumber would be null is the status of the price reduction is Initiated"},"priceReduction":{"description":"the price reduction amount for a positionItemId.","allOf":[{"title":"MonetaryAmount","type":"object","properties":{"amount":{"type":"number","description":"Holds the value of the monetary amount expressed in a currency, e.g. euros. The number format expects a decimal point, like 10.99. Numbers without a decimal point are taken as a unit of the given currency, e.g. 10 is taken as 10 euros","example":121.01},"currency":{"type":"string","description":"Holds the currency of the monetary amount expressed as a shortcut according to ISO 4217 and http://publications.europa.eu/code/de/de-5000700.htm. Currently Only EUR is supported as a currency","example":"EUR"}}}]},"creationDateTime":{"type":"string"},"status":{"description":"Status of the price reduction.\n- INITIATED: This status implies that the reduction are pending for receipt generation, and receiptId and receiptNumber would be null for INITIATED reductions.\n- PROCESSED: This status implies that the reductions for which receipts are generated.\n- REJECTED: This status implies that the reductions which failed validations and were not processed. eg. reductions applied on the positionItemId after it is marked as returned.\n","enum":["PROCESSED","INITIATED","REJECTED"]}},"description":"all price reductions applied for an item"},"Link__Price-Reductions-V1":{"title":"Link","type":"object","properties":{"href":{"type":"string","description":"The url of the link","example":"/v1/price-reductions?limit=1&page=2"},"rel":{"type":"string","description":"The relation type of the link. See also https://www.iana.org/assignments/link-relations/link-relations.xhtml. The relation type 'next' is used for paging","example":"next"}},"description":"A link to various resources. a Link can have different meanings and targets. The type of relation is specified with the property 'rel'. "},"PriceReductionsResponse__Price-Reductions-V1":{"title":"PriceReductionsResponse","type":"object","properties":{"results":{"type":"array","description":"The list of queried resources. In this case partner reductions.","items":{"$ref":"#/components/schemas/PriceReductionResponse__Price-Reductions-V1"}},"links":{"type":"array","description":"Links related to the list. E.g. the link to the successive list used during paging.","items":{"$ref":"#/components/schemas/Link__Price-Reductions-V1"}}}},"PartnerPriceReductionRequest__Price-Reductions-V1":{"required":["positionItemId","priceReduction","salesOrderId"],"type":"object","properties":{"positionItemId":{"type":"string","format":"uuid"},"salesOrderId":{"type":"string","format":"uuid"},"priceReduction":{"description":"The price reduction amount to be applied on the positionItemId.","allOf":[{"title":"MonetaryAmount","type":"object","properties":{"amount":{"type":"number","description":"Holds the value of the monetary amount expressed in a currency, e.g. euros. The number format expects a decimal point, like 10.99. Numbers without a decimal point are taken as a unit of the given currency, e.g. 10 is taken as 10 euros","example":121.01},"currency":{"type":"string","description":"Holds the currency of the monetary amount expressed as a shortcut according to ISO 4217 and http://publications.europa.eu/code/de/de-5000700.htm. Currently Only EUR is supported as a currency","example":"EUR"}}}]}}},"ForbiddenApplyPriceReduction__Price-Reductions-V1":{"description":"The partner does not have the required permissions.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/APIErrorResponse__Price-Reductions-V1"}},"example":{"errors":[{"title":"Forbidden","code":403,"detail":"Access is denied, please make sure you have right permissions.","path":"/v1/price-reductions/{salesOrderId}/{positionItemId}"}]}},"ForbiddenGetPriceReduction__Price-Reductions-V1":{"description":"The partner does not have the required permissions.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/APIErrorResponse__Price-Reductions-V1"}},"example":{"errors":[{"title":"Forbidden","code":403,"detail":"Access is denied, please make sure you have right permissions","path":"/v1/price-reductions/"}]}},"NotFoundPriceReductionForPositionItemId__Price-Reductions-V1":{"description":"Price reduction for a positionItemId does not exist.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/APIErrorResponse__Price-Reductions-V1"}},"example":{"errors":[{"title":"Not Found","code":404,"detail":"No PriceReduction applied for item with positionItemId","path":"/v1/price-reductions/{salesOrderId}/{positionItemId}"}]}},"NotFoundPositionItemId__Price-Reductions-V1":{"description":"PositionItemId does not exist","type":"object","properties":{"errors":{"$ref":"#/components/schemas/APIErrorResponse__Price-Reductions-V1"}},"example":{"errors":[{"title":"Not Found","code":404,"detail":"PositionItemId does not exist","path":"/v1/price-reductions/{salesOrderId}/{positionItemId}"}]}},"ConflictPositionItemId__Price-Reductions-V1":{"description":"PositionItemId is not shipped or returned.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/APIErrorResponse__Price-Reductions-V1"}},"example":{"errors":[{"title":"Conflict","code":409,"detail":"Price reduction cannot be applied as sales order position item is not yet shipped or has been returned.","path":"/v1/price-reductions/{salesOrderId}/{positionItemId}"}]}},"AcceptedPriceReductionResponse__Price-Reductions-V1":{"description":"Price reduction has been initiated successfully. Please wait for sometime.","type":"object","properties":{"results":{"$ref":"#/components/schemas/APIResponse__Price-Reductions-V1"}},"example":{"results":[{"title":"Accepted","code":202,"detail":"Price reduction has been initiated successfully. Please wait for sometime.","path":"/v1/price-reductions/{salesOrderId}/{positionItemId}"}]}},"InternalServerErrorApplyPriceReduction__Price-Reductions-V1":{"description":"An unexpected error has occurred while applying price reduction. Please try again.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/APIErrorResponse__Price-Reductions-V1"}},"example":{"errors":[{"title":"Internal Server Error","code":500,"detail":"An unexpected error has occurred. Please try again.","path":"/v1/price-reductions"}]}},"FailedDependency__Price-Reductions-V1":{"description":"Unable to retrieve price discounts due to internal errors with downstream systems. Please try again later.","type":"object","properties":{"errors":{"$ref":"#/components/schemas/APIErrorResponse__Price-Reductions-V1"}},"example":{"errors":[{"title":"Failed Dependency","code":424,"detail":"Unable to retrieve price discounts due to internal errors with downstream systems. Please try again later.","path":"/v1/price-reductions"}]}},"GetAllShippingProfilesResponse__ShippingProfiles-V1":{"type":"object","required":["results"],"properties":{"results":{"type":"array","description":"List of maximum 300 shipping profiles. Returns a cursor field if there are more than 300 shipping profile to get the next results.","items":{"$ref":"#/components/schemas/GetShippingProfileResponse__ShippingProfiles-V1"}},"links":{"type":"object","description":"link to next page if there are more than 300 shipping profiles","properties":{"href":{"type":"string","example":"/v1/shipping-profiles?cursor=YmExMjU4MGMtZGJhNS00NTY5LWI4NWMtN2RmNmJmMmU2Mzc1sWkpQYnA=","description":"url to get next max 300 shipping profiles"},"rel":{"type":"string","example":"next","description":"link relation type"}}}}},"CreateShippingProfileRequest__ShippingProfiles-V1":{"type":"object","required":["shippingProfileName","workingDays","orderCutoff","transportTime","deliveryType","defaultProcessingTime"],"properties":{"shippingProfileName":{"type":"string","example":"TestShippingProfile","description":"ShippingProfileName allows the partner to assign a descriptive and unique name for a shipping profile"},"workingDays":{"type":"array","items":{"type":"string"},"example":["Monday","Wednesday"],"description":"WorkingDays describe the specific days of the week on which the partner is available to process orders"},"orderCutoff":{"type":"string","format":"HH:MM","example":"23:30","description":"OrderCutoff specifies the time for orders to be placed, so the ProcessingTime starts within the same day.
This must be in half hour duration in (HH:MM) 24 hours format. The cut-off time must be specified in CET time."},"deliveryType":{"type":"string","example":"PARCEL","enum":["PARCEL","FORWARDER_PREFERREDLOCATION","FORWARDER_CURBSIDE","FORWARDER_HEAVYDUTY"],"description":"DeliveryType describes how the product is being shipped. At the moment we support the enums shown above"},"defaultProcessingTime":{"type":"integer","format":"int64","example":2,"description":"DefaultProcessingTime describes the time the partner needs to prepare the order for a shipment. Must be between 1 to 99.
If more than 72 days are transmitted in the DefaultProcessingTime, the product is marked as sold out on otto.de and cannot be ordered.
This is also the case if the DefaultProcessingTime and TransportTime add up to a value greater than 72. \"1\" day is considered as same-day shipping (0 days) until the cut-off time is reached.","minimum":1,"maximum":99,"exclusiveMinimum":false,"exclusiveMaximum":false},"transportTime":{"type":"integer","format":"int64","example":2,"description":"TransportTime describes the time the carrier needs from collecting the order from partners warehouse until the first delivery attempt. Must be between 1 to 99.
If more than 72 days are transmitted in the TransportTime, the product is marked as sold out on otto.de and cannot be ordered.
This is also the case if the DefaultProcessingTime and TransportTime add up to a value greater than 72.","minimum":1,"maximum":99,"exclusiveMinimum":false,"exclusiveMaximum":false}},"title":"CreateShippingProfileRequest"},"GetShippingProfileResponse__ShippingProfiles-V1":{"type":"object","required":["shippingProfileId","shippingProfileName","workingDays","orderCutoff","deliveryType","transportTime","defaultProcessingTime"],"properties":{"shippingProfileId":{"type":"string","pattern":"UUID4 string","example":"38427776-7383-4d65-82c9-dbe949d0573a","description":"Unique identifier for each shipping profile"},"shippingProfileName":{"type":"string","example":"TestShippingProfile","description":"The name of the shipping profile"},"workingDays":{"type":"array","items":{"type":"string","enum":["Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday"]},"example":["Monday","Wednesday"],"description":"The days of the week on which the partner is available to process orders"},"orderCutoff":{"type":"string","format":"HH:MM, 24 hours format, CET timezone","example":"23:30","description":"OrderCutoff specifies the time for orders to be placed, so the ProcessingTime starts within the same day.
This must be in half hour duration in (HH:MM) 24 hours format and in CET time."},"deliveryType":{"type":"string","example":"PARCEL","enum":["PARCEL","FORWARDER_PREFERREDLOCATION","FORWARDER_CURBSIDE","FORWARDER_HEAVYDUTY"],"description":"DeliveryType describes how the product is being shipped. At the moment we support the enums shown above"},"defaultProcessingTime":{"type":"integer","format":"int64","minimum":1,"maximum":99,"exclusiveMinimum":false,"exclusiveMaximum":false,"example":2,"description":"DefaultProcessingTime describes the time the partner needs to prepare the order for a shipment."},"transportTime":{"type":"integer","format":"int64","minimum":1,"maximum":99,"exclusiveMinimum":false,"exclusiveMaximum":false,"example":2,"description":"The time the carrier needs from collecting the order from partners warehouse till the first delivery attempt."}},"title":"GetShippingProfileResponse"},"CreateShippingProfileResponse__ShippingProfiles-V1":{"type":"object","required":["message","shippingProfileId"],"properties":{"shippingProfileId":{"type":"string","pattern":"UUID4 string","example":"38427776-7383-4d65-82c9-dbe949d0573a","description":"Unique identifier for each shipping profile id"},"message":{"type":"string","example":"Shipping profile created successfully with id : 38427776-7383-4d65-82c9-dbe949d0573a","description":"successful message"}},"title":"CreateShippingProfileResponse"},"APIErrorResponseForNotFound__ShippingProfiles-V1":{"description":"Describes the error details","type":"object","required":["type","title","status","validationErrors"],"properties":{"type":{"description":"url of the request","example":"/v1/shipping-profiles","type":"string"},"title":{"description":"type of error","example":"Shipping profile not found","type":"string"},"status":{"description":"status code of response","example":404,"type":"number"},"validationErrors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorWithNotFoundSuggestions__ShippingProfiles-V1"}}}},"APIErrorResponseForBadRequest__ShippingProfiles-V1":{"description":"Describes the error details","type":"object","required":["type","title","status","validationErrors"],"properties":{"type":{"description":"url of the request","example":"/v1/shipping-profiles","type":"string"},"title":{"description":"type of error","example":"Validation Failure","type":"string"},"status":{"description":"status code of response","example":400,"type":"number"},"validationErrors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorWithBadRequestSuggestions__ShippingProfiles-V1"}}}},"ErrorWithNotFoundSuggestions__ShippingProfiles-V1":{"description":"Describes all the errors","type":"object","required":["detail","logref"],"properties":{"detail":{"description":"The description of the error.","example":"Shipping profile not found for 7bec0ef6-4324-4fa4-9fbf-42c54659ef04","type":"string"},"logref":{"type":"string","example":"shippingProfileNotFound","description":"key to find in the log"}}},"ErrorWithBadRequestSuggestions__ShippingProfiles-V1":{"description":"Describes all the errors","type":"object","required":["detail","logref"],"properties":{"detail":{"description":"The description of the error.","example":"Invalid transport time. Should be greater than 0 and less than 100","type":"string"},"logref":{"type":"string","example":"shippingProfileId","description":"key to find in the log"}}},"APIErrorResponseForConflict__ShippingProfiles-V1":{"description":"Describes the error details","type":"object","required":["type","title","status","validationErrors"],"properties":{"type":{"description":"url of the request","example":"/v1/shipping-profiles","type":"string"},"title":{"description":"type of error","example":"Conflict creating ShippingProfileId, Please try again","type":"string"},"status":{"description":"status code of response","example":409,"type":"number"},"validationErrors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorWithSuggestionsForConflict__ShippingProfiles-V1"}}}},"ErrorWithSuggestionsForConflict__ShippingProfiles-V1":{"description":"Describes all the errors","type":"object","required":["detail","logref"],"properties":{"detail":{"description":"The description of the error.","example":"There was a conflict while creating shippingProfileId","type":"string"},"logref":{"type":"string","example":"shippingProfileId","description":"key to find in the log"}}},"APIInternalServerErrorResponse__ShippingProfiles-V1":{"description":"Describes the error details","type":"object","required":["type","title","status","validationErrors"],"properties":{"type":{"description":"url of the request","example":"/v1/shipping-profiles","type":"string"},"title":{"description":"type of error","example":"Internal server error","type":"string"},"status":{"description":"status code of response","type":"number","example":500},"validationErrors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorForInternalServerError__ShippingProfiles-V1"}}}},"ErrorForInternalServerError__ShippingProfiles-V1":{"description":"Describes all the errors","type":"object","required":["detail","logref"],"properties":{"detail":{"description":"The description of the error.","example":"Internal server error","type":"string"},"logref":{"type":"string","example":"","description":"key to find in the log"}}},"APIErrorResponseForPrecondition__ShippingProfiles-V1":{"description":"Describes the error details","type":"object","required":["type","title","status","validationErrors"],"properties":{"type":{"description":"url of the request","example":"/v1/shipping-profiles","type":"string"},"title":{"description":"type of error","example":"Deletion Failed","type":"string"},"status":{"description":"status code of response","example":412,"type":"number"},"validationErrors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorWithPrecondition__ShippingProfiles-V1"}}}},"ErrorWithPrecondition__ShippingProfiles-V1":{"description":"Describes all the errors","type":"object","required":["detail","logref"],"properties":{"detail":{"description":"The description of the error.","example":"Shipping profile has one or more SKUs linked to it. Please link the SKUs to a another shipping profile.","type":"string"},"logref":{"type":"string","example":"shippingProfileInUse","description":"key to find in the log"}}},"ApiErrorResponse__Availability-V1":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","description":"list of errors","items":{"$ref":"#/components/schemas/QuantityApiError__Availability-V1"}}},"title":"ApiErrorResponse"},"PayloadTooLargeApiErrorResponseForQuantities__Availability-V1":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","description":"type of error","example":[{"code":413,"detail":"Payload too large","logref":"b35c4ef1-50dd-4765-9bcf-82cde57823d8","path":"/v1/availability/quantities","title":"Error while processing request"}],"items":{"$ref":"#/components/schemas/QuantityApiError__Availability-V1"}}},"title":"PayloadTooLargeApiErrorResponse"},"QuantityApiError__Availability-V1":{"type":"object","required":["code","detail","logref","path","title"],"properties":{"code":{"type":"integer","format":"int32","example":422,"description":"http status code"},"detail":{"type":"string","example":"Details of error message with SKU id","description":"details of the error"},"logref":{"type":"string","example":"b35c4ef1-50dd-4765-9bcf-82cde57823d8","description":"key to find in the log"},"path":{"type":"string","example":"/v1/availability/quantities","description":"api endpoint/uri"},"title":{"type":"string","example":"Error message with SKU id","description":"title of the error"}},"title":"ApiError"},"AvailableQuantityRequestDTO__Availability-V1":{"type":"object","required":["quantity","sku"],"properties":{"quantity":{"type":"integer","format":"int64","description":"The available quantity of a specific SKU.","minimum":0,"maximum":999999999,"exclusiveMinimum":false,"exclusiveMaximum":false,"example":123},"sku":{"type":"string","description":"StockKeepingUnit given by partner configuration. e.g. 'shirt-red-M', external identifier of article variation.","example":"123456789ABCDE"}},"title":"AvailableQuantityRequestDTO"},"AvailableQuantityResponseDTO__Availability-V1":{"type":"object","required":["lastModified","quantity","sku","links"],"properties":{"lastModified":{"type":"string","format":"YYYY-MM-DD'T'HH:mm:ss.SSS'Z'","description":"The last modified date and time of available quantity in a ISO8601 format","example":"2024-07-18T07:20:06.260124Z"},"quantity":{"type":"integer","format":"int64","example":123,"description":"The available quantity of a specific SKU, which can be any integer value >= 0.","minimum":0,"maximum":999999999,"exclusiveMinimum":false,"exclusiveMaximum":false},"sku":{"type":"string","example":"123456789ABCDE","description":"StockKeepingUnit. Identifier of a product variation.\n"},"links":{"type":"array","description":"contains links to prev, self and next page url's","items":{"$ref":"#/components/schemas/Link__Availability-V1"}}},"title":"AvailableQuantityResponseDTO"},"AvailableQuantitySingleResponseDTO__Availability-V1":{"type":"object","required":["lastModified","quantity","sku"],"properties":{"lastModified":{"type":"string","format":"YYYY-MM-DD'T'HH:mm:ss.SSS'Z'","example":"2024-07-18T07:20:06.260124Z","description":"The last modified date and time of available quantity as a ISO8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSX)."},"quantity":{"type":"integer","format":"int64","example":123,"description":"The available quantity of a specific SKU, which can be any integer value >= 0.","minimum":0,"maximum":999999999,"exclusiveMinimum":false,"exclusiveMaximum":false},"sku":{"type":"string","example":"123456789ABCDE","description":"StockKeepingUnit given by partner configuration. e.g. 'shirt-red-M', external identifier of article variation."}},"title":"AvailableQuantitySingleResponseDTO"},"UpdateQuantityMultiStatusResponse__Availability-V1":{"type":"object","required":["results"],"properties":{"results":{"type":"array","example":[{"lastModified":"2024-07-18T07:20:06.260124Z","quantity":"123","sku":"4007781056144"}],"description":"List of all the skus with available quantity","items":{"$ref":"#/components/schemas/AvailableQuantityResponseDTO__Availability-V1"}},"errors":{"type":"array","example":[{"path":"/v1/availability/quantities","title":"Error while processing request: sku","code":"207","detail":"Error: SKU is unknown for SKU: sku","logref":"sku"},{"path":"/v1/availability/quantities","title":"Error while processing request: sku","code":"207","detail":"Invalid quantity. Quantity should be an absolute number for SKU: sku","logref":"sku"},{"path":"/v1/availability/quantities","title":"Error while processing request: null","code":"207","detail":"Error: [sku must not be empty] for SKU: null","logref":"sku"}],"items":{"$ref":"#/components/schemas/QuantityApiError__Availability-V1"}}},"title":"UpdateQuantityMultiStatusResponse"},"ProductDeliveryInformationMultiStatusResponse__Availability-V1":{"type":"object","required":["results"],"properties":{"results":{"type":"array","example":[{"shippingProfileId":"2f236e76-543e-5a0b-ac79-53f5db132e44","processingTime":"12","sku":"4007781056144"}],"description":"List of all the skus with its shipping profile id and processing time","items":{"$ref":"#/components/schemas/ProductDeliveryInformationResponseDTO__Availability-V1"}},"errors":{"$ref":"#/components/schemas/ErrorDetailsForMultiStatus__Availability-V1"}},"title":"ProductDeliveryInformationMultiStatusResponse"},"AvailableQuantityResponse__Availability-V1":{"type":"object","required":["resources","links"],"properties":{"resources":{"type":"object","required":["variations"],"properties":{"variations":{"type":"array","example":[{"lastModified":"2024-07-18T07:20:06.260124Z","quantity":"123","sku":"MOCK-CABINET-1","links":[{"rel":"self","href":"/v1/availability/quantities/MOCK-CABINET-1"}]},{"lastModified":"2024-06-03T10:30:13.972203Z","quantity":"123","sku":"SANDWICH-1","links":[{"rel":"self","href":"/v1/availability/quantities/SANDWICH-1"}]}],"items":{"$ref":"#/components/schemas/AvailableQuantityResponseDTO__Availability-V1"}}}},"links":{"type":"array","description":"contains links to the next page","example":[{"rel":"next","href":"/v1/availability/quantities?cursor=SANDWICH-1"}],"items":{"$ref":"#/components/schemas/Link__Availability-V1"}}},"title":"AvailableQuantityRequestDTO"},"ProductDeliveryInformationRequestDTOList__Availability-V1":{"type":"object","required":["results"],"properties":{"results":{"type":"array","description":"Response","items":{"$ref":"#/components/schemas/ProductDeliveryInformationRequestDTO__Availability-V1"},"example":[{"shippingProfileId":"2f236e76-543e-5a0b-ac79-53f5db132e44","processingTime":"3","sku":"MOCK-CABINET-1"},{"shippingProfileId":"2f236e76-543e-5a0b-ac79-53f5db132e44","processingTime":"1","sku":"SANDWICH-1"}]},"links":{"type":"object","description":"Link to next response","properties":{"href":{"type":"string","description":"the linked reference as URI","example":"/v1/availability/product-delivery-information?cursor=MTIzNDU2"},"rel":{"type":"string","example":"next","description":"link relation type"}}}}},"ProductDeliveryInformationRequestDTO__Availability-V1":{"type":"object","required":["shippingProfileId","processingTime","sku"],"properties":{"shippingProfileId":{"type":"string","example":"2f236e76-543e-5a0b-ac79-53f5db132e44","description":"The ShippingProfileId is provided in the ShippingProfiles-API and is the PrimaryKey which is used to map a specific Profile to a SKU"},"processingTime":{"type":"string","format":"[1..99] or DEFAULT","example":"DEFAULT","description":"The processingTime of a specific SKU, which can be any value between 1 and 99 or 'DEFAULT'.
When it is set to DEFAULT the defaultProcessingTime used in the shipping profile will be considered
Otherwise the defaultProcessingTime is overwritten and is not reset even if the shipping profile is changed.
It describes the time the partner needs to prepare the order for a shipment."},"sku":{"type":"string","example":"123456789ABCDE","description":"StockKeepingUnit given by partner configuration. e.g. 'shirt-red-M', external identifier of article variation."}},"title":"ProductDeliveryInformationRequestDTO"},"ProductDeliveryInformationResponseDTO__Availability-V1":{"type":"object","required":["shippingProfileId","processingTime","sku"],"properties":{"shippingProfileId":{"type":"string","example":"2f236e76-543e-5a0b-ac79-53f5db132e44","description":"The ShippingProfileId is provided in the ShippingProfiles-API and is the PrimaryKey which is used to map a specific Profile to a SKU"},"processingTime":{"type":"string","example":"2","description":"The processingTime of a specific SKU, which can be any value between 1 and 99 or 'DEFAULT'.
When it is set to DEFAULT the defaultProcessingTime used in the shipping profile will be considered
Otherwise the defaultProcessingTime is overwritten and is not reset even if the shipping profile is changed.
It describes the time the partner needs to prepare the order for a shipment."},"sku":{"type":"string","example":"123456789ABCDE","description":"StockKeepingUnit given by partner configuration. e.g. 'shirt-red-M', external identifier of article variation."}},"title":"ProductDeliveryInformationResponseDTO"},"Link__Availability-V1":{"type":"object","properties":{"rel":{"type":"string","example":"self","description":"link relation type","enum":["next"]},"href":{"type":"string","example":".../v1/availability/quantities?cursor=MTIzNDU2","description":"the linked reference as URI"}}},"APIErrorResponseForBadRequest__Availability-V1":{"description":"Describes the error details","type":"object","required":["type","title","status","validationErrors"],"properties":{"type":{"description":"url of the request","example":"/v1/availability/product-delivery-information","type":"string"},"title":{"description":"type of error","example":"Validation Failure","type":"string"},"status":{"description":"status code of response","type":"number","example":400},"validationErrors":{"type":"array","example":[{"detail":"Error shippingProfileId: b35c4ef1-50dd-4765-9bcf-82cde57823d8 is unknown","logref":"shippingProfileId"},{"detail":"Error sku: TEST-SKU is unknown","logref":"sku"}],"items":{"$ref":"#/components/schemas/ErrorForUnknownSku__Availability-V1"}}}},"ErrorForUnknownSku__Availability-V1":{"description":"Describes all the errors","type":"object","required":["detail","logref"],"properties":{"detail":{"description":"The description of the error.","example":"Error sku: TEST-SKU is unknown","type":"string"},"logref":{"type":"string","example":"sku","description":"key to find in the log"}}},"ErrorDetailsForMultiStatus__Availability-V1":{"description":"Describes the error details","type":"object","required":["type","title","status","validationErrors"],"properties":{"type":{"description":"url of the request","example":"/v1/availability/product-delivery-information","type":"string"},"title":{"description":"type of error","example":"Validation Failure","type":"string"},"status":{"description":"status code of response","type":"number","example":404},"validationErrors":{"type":"array","example":[{"detail":"Error shippingProfileId: b35c4ef1-50dd-4765-9bcf-82cde57823d8 is unknown","logref":"shippingProfileId"},{"detail":"Error sku: TEST-SKU is unknown","logref":"sku"}],"items":{"$ref":"#/components/schemas/ErrorForUnknownSku__Availability-V1"}}}},"APIErrorResponseForNotFound__Availability-V1":{"description":"Describes the error details","type":"object","required":["type","title","status","validationErrors"],"properties":{"type":{"description":"url of the request","example":"/v1/availability/product-delivery-information","type":"string"},"title":{"description":"type of error","example":"Sku not found","type":"string"},"status":{"description":"status code of response","type":"number","example":404},"validationErrors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorForSKUNotFound__Availability-V1"}}}},"ErrorForSKUNotFound__Availability-V1":{"description":"Describes all the errors","type":"object","required":["detail","logref"],"properties":{"detail":{"description":"The description of the error.","example":"Sku not found for TEST_SKU","type":"string"},"logref":{"type":"string","example":"sku","description":"key to find in the log"}}},"ApiErrorResponseForPayloadTooLarge__Availability-V1":{"description":"Describes the error details","type":"object","required":["type","title","status","validationErrors"],"properties":{"type":{"description":"url of the request","example":"/v1/availability/product-delivery-information","type":"string"},"title":{"description":"type of error","example":"Payload too large, should contain max 200 items","type":"string"},"status":{"description":"status code of response","type":"number","example":413},"validationErrors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorForPayloadTooLarge__Availability-V1"}}}},"ErrorForPayloadTooLarge__Availability-V1":{"description":"Describes all the errors","type":"object","required":["detail","logref"],"properties":{"detail":{"description":"The description of the error.","example":"Payload too large, should contain max 200 items","type":"string"},"logref":{"type":"string","example":"","description":"key to find in the log"}}},"APIErrorResponseForInternalServer__Availability-V1":{"description":"Describes the error details","type":"object","required":["type","title","status","validationErrors"],"properties":{"type":{"description":"url of the request","example":"/v1/availability/product-delivery-information","type":"string"},"title":{"description":"type of error","example":"Internal server error","type":"string"},"status":{"description":"status code of response","type":"number","example":500},"validationErrors":{"type":"array","items":{"$ref":"#/components/schemas/InternalServerError__Availability-V1"}}}},"InternalServerError__Availability-V1":{"description":"Describes all the errors","type":"object","required":["detail","logref"],"properties":{"detail":{"description":"The description of the error.","example":"Internal server error","type":"string"},"logref":{"type":"string","example":"","description":"key to find in the log"}}},"GetAllProductDeliveryInfoResponse__Availability-V1":{"type":"object","required":["results"],"properties":{"results":{"type":"array","description":"List of maximum 200 sku-shipping profiles. Returns a cursor field if there are more than 200 sku-shipping profiles mapping to get the next results.","items":{"$ref":"#/components/schemas/ProductDeliveryInformationResponseDTO__Availability-V1"}},"links":{"type":"object","description":"link to next page if there are more than 200 mappings","properties":{"href":{"type":"string","example":"/v1/availability/product-delivery-information?cursor=MTIzNDU2","description":"url to get next max 200 results"},"rel":{"type":"string","example":"next","description":"link relation type"}}}}}},"examples":{"ShipmentCreateRequestParcelDelivery__Shipments-V1":{"value":{"trackingKey":{"carrier":"HERMES","trackingNumber":"H1234567890123456789"},"shipDate":"2019-10-11T07:49:12.642Z","shipFromAddress":{"city":"Dresden","countryCode":"DEU","zipCode":"01067"},"positionItems":[{"positionItemId":"b01b8ad2-a49c-47fc-8ade-8629ec000020","salesOrderId":"bf43d748-f13d-49ca-b2e2-1824e9000021","returnTrackingKey":{"carrier":"DHL","trackingNumber":"577546565072"}},{"positionItemId":"b01b8ad2-a49c-47fc-8ade-8629ec000022","salesOrderId":"bf43d748-f13d-49ca-b2e2-1824e9000021","returnTrackingKey":{"carrier":"DHL","trackingNumber":"577546565072"}}]}},"MultiparcelShipmentCreateRequestParcelDelivery__Shipments-V1":{"value":[{"trackingKey":{"carrier":"HERMES","trackingNumber":"H1234567890123456788"},"shipDate":"2019-10-11T07:49:12.642Z","shipFromAddress":{"city":"Dresden","countryCode":"DEU","zipCode":"01067"},"positionItems":[{"positionItemId":"b01b8ad2-a49c-47fc-8ade-8629ec000020","salesOrderId":"bf43d748-f13d-49ca-b2e2-1824e9000021","returnTrackingKey":{"carrier":"DHL","trackingNumber":"577546565072"}}]},{"trackingKey":{"carrier":"HERMES","trackingNumber":"H1234567890123456789"},"shipDate":"2019-10-11T07:49:12.643Z","shipFromAddress":{"city":"Dresden","countryCode":"DEU","zipCode":"01067"},"positionItems":[{"positionItemId":"b01b8ad2-a49c-47fc-8ade-8629ec000020","salesOrderId":"bf43d748-f13d-49ca-b2e2-1824e9000021","returnTrackingKey":{"carrier":"DHL","trackingNumber":"577546565073"}}]}]},"ShipmentCreateRequestForwarderDelivery__Shipments-V1":{"value":{"trackingKey":{"carrier":"OTHER_FORWARDER","trackingNumber":"FF12345678"},"shipDate":"2019-10-11T07:49:12.642Z","shipFromAddress":{"city":"Dresden","countryCode":"DEU","zipCode":"01067"},"positionItems":[{"positionItemId":"b01b8ad2-a49c-47fc-8ade-8629ec000020","salesOrderId":"bf43d748-f13d-49ca-b2e2-1824e9000021"},{"positionItemId":"b01b8ad2-a49c-47fc-8ade-8629ec000022","salesOrderId":"bf43d748-f13d-49ca-b2e2-1824e9000021"}]}},"ShipmentCreateRequestForwarderDeliveryWithoutTrackingNo__Shipments-V1":{"value":{"trackingKey":{"carrier":"OTHER_FORWARDER"},"shipDate":"2019-10-11T07:49:12.642Z","shipFromAddress":{"city":"Dresden","countryCode":"DEU","zipCode":"01067"},"positionItems":[{"positionItemId":"b01b8ad2-a49c-47fc-8ade-8629ec000020","salesOrderId":"bf43d748-f13d-49ca-b2e2-1824e9000021"},{"positionItemId":"b01b8ad2-a49c-47fc-8ade-8629ec000022","salesOrderId":"bf43d748-f13d-49ca-b2e2-1824e9000021"}]}},"ShipmentCreateInsufficientPermissionsResponse__Shipments-V1":{"description":"A position item in the request doesn't belong to the partner.","value":{"errors":[{"title":"INSUFFICIENT_PERMISSION","detail":"The partner is not allowed to create/update a shipment for position item ID","path":"/shipments","jsonPath":"positionItems[0].positionItemId"}]}},"MultiparcelShipmentCreateInsufficientPermissionsResponse__Shipments-V1":{"description":"A position item in the request doesn't belong to the partner.","value":{"errors":[{"title":"INSUFFICIENT_PERMISSION","detail":"The partner is not allowed to create/update a shipment for position item ID","path":"/multiparcel-shipments/shipments","jsonPath":"shipments[0].positionItems[0].positionItemId"}]}},"ShipmentCreateTrackingKeyMandatoryResponse__Shipments-V1":{"description":"The tracking key in the request is mandatory.","value":{"errors":[{"title":"PROPERTY_IS_MANDATORY","detail":"The property is mandatory","path":"/shipments","jsonPath":"trackingKey"}]}},"MultiparcelShipmentCreateTrackingKeyMandatoryResponse__Shipments-V1":{"description":"The tracking key in the request for a shipment is mandatory.","value":{"errors":[{"title":"PROPERTY_IS_MANDATORY","detail":"The property is mandatory","path":"/multiparcel-shipments/shipments","jsonPath":"shipments[0].trackingKey"}]}},"ShipmentAddPositionItemsInsufficientPermissionsResponse__Shipments-V1":{"description":"A position item in the request doesn't belong to the partner.","value":{"errors":[{"title":"INSUFFICIENT_PERMISSION","detail":"The partner is not allowed to create/update a shipment for position item ID","path":"/shipments","jsonPath":"[0].positionItemId"}]}}},"headers":{"ETag":{"description":"The RFC 7232 ETag header field in a response provides the entity-tag of a selected resource. The entity-tag is an opaque identifier for versions and representations of the same resource over time, regardless whether multiple versions are valid at the same time. An entity-tag consists of an opaque quoted string, possibly prefixed by a weakness indicator (see [RFC 7232 Section 2.3](https://tools.ietf.org/html/rfc7232#section-2.3).","schema":{"type":"string"},"required":false,"example":"7da7a728f910"},"Last-Modified":{"description":"TThe Last-Modified header field in a response provides a timestamp indicating the date and time at which the origin server believes the selected representation was last modified, as determined at the conclusion of handling the request (see [RFC 7232 Section 2.3](https://tools.ietf.org/html/rfc7232#section-2.2).","schema":{"type":"string"},"required":false,"example":"Tue, 15 Nov 1994 12:45:26 GMT"}},"parameters":{"If-Match":{"name":"If-Match","in":"header","description":"The RFC7232 If-Match header field in a request requires the server to only operate on the resource that matches at least one of the provided entity-tags. This allows clients express a precondition that prevent the method from being applied if there have been any changes to the resource (see [RFC 7232 Section 3.1](https://tools.ietf.org/html/rfc7232#section-3.1).","schema":{"type":"string"},"required":false,"example":"7da7a728f910"},"If-None-Match":{"name":"If-None-Match","in":"header","description":"The RFC7232 If-None-Match header field in a request requires the server to only operate on the resource if it does not match any of the provided entity-tags. If the provided entity-tag is `*`, it is required that the resource does not exist at all (see [RFC 7232 Section 3.2](https://tools.ietf.org/html/rfc7232#section-3.2)","schema":{"type":"string"},"required":false,"example":"7da7a728f910"},"If-Modified-Since":{"name":"If-Modified-Since","in":"header","description":"The RFC7232 If-Modified-Since header field makes a GET or HEAD request method conditional on the selected representation's modification date being more recent than the date provided in the field-value. Transfer of the selected representation's data is avoided if that data has not changed.","schema":{"type":"string"},"required":false,"example":"Sat, 29 Oct 1994 19:43:31 GMT"},"If-Unmodified-Since":{"name":"If-Unmodified-Since","in":"header","description":"The RFC7232 If-Unmodified-Since header field makes the request method conditional on the selected representation's last modification date being earlier than or equal to the date provided in the field-value. This field accomplishes the same purpose as If-Match for cases where the user agent does not have an entity-tag for the representation.","schema":{"type":"string"},"required":false,"example":"Sat, 29 Oct 1994 19:43:31 GMT"}},"requestBodies":{},"responses":{}},"tags":[{"name":"Products-V3","description":"### Product interfaces\nThe 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.\n\nThe API offers endpoints for different aspects of product data management:\n\n- The \"Products\" endpoint can be used to send the products to the OTTO Market. 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 (like \"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. The GET operation of the \"Products\" endpoint can be used after the end of the processing to watch the representation of the product in the exact state sent by you. The state changes to \"DONE\", when the operation is finished and you get an executive summary of the operation. 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.\n\n- The \"Product Active Status\" 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. There is also a GET operation to view the state of products.\n\n- Use the \"Marketplace Status\" 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.\n\n- The \"Brands\" 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.\n\n- The \"Categories\" 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.\n\n### Example\nA typical sequence dealing with our interfaces would be:\n```\n1. You query the Brands interface and match the brand names in Your products to the names in the received brands.\n2. You query the Categories interface and match the category names in Your products to the names in the received categories.\n3. You use the POST endpoints from the Products interface to send Your products to Otto Market\n4. You will receive 202 HTTP return code and a body like:\n{\n \"state\": \"pending\",\n \"message\": \"The process is currently in progress\",\n \"progress\": 0,\n \"total\": 2,\n \"pingAfter\": \"2020-05-13T10:40:01.815Z\",\n \"links\": [\n {\n \"rel\": \"self\",\n \"href\": \"/v3/products/update-tasks/09abe6ca-9c36-45bb-9cd3-a7de7f93284b\"\n },\n {\n \"rel\": \"failed\",\n \"href\": \"/v3/products/update-tasks/09abe6ca-9c36-45bb-9cd3-a7de7f93284b/failed\"\n },\n {\n \"rel\": \"succeeded\",\n \"href\": \"/v3/products/update-tasks/09abe6ca-9c36-45bb-9cd3-a7de7f93284b/succeeded\"\n },\n {\n \"rel\": \"unchanged\",\n \"href\": \"/v3/products/update-tasks/09abe6ca-9c36-45bb-9cd3-a7de7f93284b/unchanged\"\n }\n ]\n}\n5. You execute /v3/products/update-tasks/09abe6ca-9c36-45bb-9cd3-a7de7f93284b until the state changes to \"done\". Usually this will happen very fast.\n6. 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).\n7. 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.\n```\n\n### Authentication\nAll interfaces expect the consumer to add a valid JWT token to the request, otherwise the request will fail with HTTP 401 or 403\n\n### Rate Limits\nThe OTTO 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:\n\n| Endpoint path | HTTP method | Max requests per time unit |\n| ------------- | ----------- | -------------------------- |\n| /products | GET | 10 per second |\n| /products | POST | 20 per second |\n| /products/prices | GET | 10 per second |\n| /products/prices | POST | 10 per second |\n| /products/active-status | GET | 10 per second |\n| /products/active-status | POST | 3600 per day |\n| /products/marketplace-status | GET | 10 per second |\n| /products/categories | GET | 10 per second |\n| /products/brands | GET | 10 per second |\n\n#### What to do if you hit the rate limits?\nIf 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.\n\n\n### HTML markup in free texts\nAll fields with free text values (like e.g. description, bullet points, certain category-dependent attributes) do only accept some of\nthe available HTML markup tags - every other markup will be removed,\n\nThe allowed tags are:\n\n* formatting tags
\n ```, , , , , , ^{, _{, , , , , , , , ,
, , ```\n* block tags
\n ```,
, ,
,
,
,
,
, , , , ```\n\nPLEASE 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.\n\n\n\n\n\n### Changelog\n\n| Date | Description |\n|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| 2024-10-07 | **Added**
The product safety information now includes the additional properties regionCode and url. Specifying the email and/or url is mandatory when providing product safety information. | \n| 2024-05-28 | **Added**
Possibility to add information for product safety
- productSafety is a new top level container for providing manufacturer / importer information. Will be obligatory from V4. |\n| 2022-09-22 | We are proudly introducing our products API v3 with a lot of changes compared to v2, that we will describe here. Further information for v3 can also be found in the OPC-helpdesk. **v2 will be supported until 31th of March 2023.** After this date, the products interface will reject requests via v2.

**Changed**
- handling brands: We introduce the brandId, which will replace the name of the brand. You can find the brandIds and the matching brand-names at `v3/products/brands`. The new brandId keeps stable, even if the name of a brand will be adjusted in the future. The brandId allows us to seperate between different brands with the same name. The `usable`-tag at every brand gives you the information, if you are allowed to setup products from this brand or you need a special permission for that.
- restrict the length of the attributes `productLine`, `Besondere Merkmale` and `Set-Info` to 70 characters each. The product-title on otto.de is composed based on the selected category. You can find the title-templates in the category-endpoint. These 3 attributes are part of most title-templates. We need to restrict the length to avoid overly long product-titles, which have a bad influence on the customer experience.
- the status of an upload is now more transparent. We now differenciate just between the upload-state \"in progress\" and \"done\". The state \"failed\" isn't shown any more. For your convenience, we also show a more detailed status of the processing, which were included in the upload.
- The asset-links may contain a maximum of 2083 characters.
- Prices should be transmitted with Euro as currency and may contain 2 decimal places.

**Added**
- `deliveryType` offers a new value for goods, which have to be transported to customers by heavy trucks. It is called `FORWARDER_HEAVYDUTY`.
- You can now, if you wish, limit a customer's order in the number of items per order. This can make sense for products where demand is greater than supply. Additionally to the attribute `maxOrderQuantity` known from v2, you can limit the order with a specific period `periodInDays`. A `maxOrderQuantity` with a `quantity` of 5 and a `periodInDays` of 30 means, that a customer can order 5 pieces of this variation in 30 days.

**Removed**
- the attribute `offeringStartDate` is deleted
- `UPC` and `ISBN` are deleted |\n"},{"name":"Products-V4","description":"### Product interfaces\nThe 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.\n\nThe API offers endpoints for different aspects of product data management:\n\n- The \"Products\" endpoint can be used to send the products to the OTTO Market. 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 (like \"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. The GET operation of the \"Products\" endpoint can be used after the end of the processing to watch the representation of the product in the exact state sent by you. The state changes to \"DONE\", when the operation is finished and you get an executive summary of the operation. 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.\n\n- The \"Product Active Status\" 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. There is also a GET operation to view the state of products.\n\n- Use the \"Marketplace Status\" 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.\n\n- The \"Brands\" 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.\n\n- The \"Categories\" 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.\n\n### Example\nA typical sequence dealing with our interfaces would be:\n```\n1. You query the Brands interface and match the brand names in Your products to the names in the received brands.\n2. You query the Categories interface and match the category names in Your products to the names in the received categories.\n3. You use the POST endpoints from the Products interface to send Your products to Otto Market\n4. You will receive 202 HTTP return code and a body like:\n{\n \"state\": \"pending\",\n \"message\": \"The process is currently in progress\",\n \"progress\": 0,\n \"total\": 2,\n \"pingAfter\": \"2020-05-13T10:40:01.815Z\",\n \"links\": [\n {\n \"rel\": \"self\",\n \"href\": \"/v4/products/update-tasks/09abe6ca-9c36-45bb-9cd3-a7de7f93284b\"\n },\n {\n \"rel\": \"failed\",\n \"href\": \"/v4/products/update-tasks/09abe6ca-9c36-45bb-9cd3-a7de7f93284b/failed\"\n },\n {\n \"rel\": \"succeeded\",\n \"href\": \"/v4/products/update-tasks/09abe6ca-9c36-45bb-9cd3-a7de7f93284b/succeeded\"\n },\n {\n \"rel\": \"unchanged\",\n \"href\": \"/v4/products/update-tasks/09abe6ca-9c36-45bb-9cd3-a7de7f93284b/unchanged\"\n }\n ]\n}\n5. You execute /v4/products/update-tasks/09abe6ca-9c36-45bb-9cd3-a7de7f93284b until the state changes to \"done\". Usually this will happen very fast.\n6. You execute /v4/products/update-tasks/09abe6ca-9c36-45bb-9cd3-a7de7f93284b/succeeded and /v4/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).\n7. You may browse /v4/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.\n```\n\n### Authentication\nAll interfaces expect the consumer to add a valid JWT token to the request, otherwise the request will fail with HTTP 401 or 403\n\n### Rate Limits\nThe OTTO 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:\n\n| Endpoint path | HTTP method | Max requests per time unit |\n| ------------- | ----------- | -------------------------- |\n| /products | GET | 10 per second |\n| /products | POST | 20 per second |\n| /products/prices | GET | 10 per second |\n| /products/prices | POST | 10 per second |\n| /products/active-status | GET | 10 per second |\n| /products/active-status | POST | 3600 per day |\n| /products/marketplace-status | GET | 10 per second |\n| /products/categories | GET | 10 per second |\n| /products/brands | GET | 10 per second |\n\n#### What to do if you hit the rate limits?\nIf 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.\n\n\n### HTML markup in free texts\nAll fields with free text values (like e.g. description, bullet points, certain category-dependent attributes) do only accept some of\nthe available HTML markup tags - every other markup will be removed,\n\nThe allowed tags are:\n\n* formatting tags
\n ```, , , , , , ^{, _{, , , , , , , , ,
, , ```\n* block tags
\n ```,
, ,
,
,
,
,
, , , , ```\n\nPLEASE 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.\n\n\n\n\n\n### Changelog\n\n| Date | Description |\n|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| 2024-10-07 | **Added**The product safety information now includes the additional properties regionCode and url. Specifying the email and url is mandatory.
|\n| 2024-08-01 | We are pleased to announce the release of our new Products API v4. Please note that this API is a draft that will be available via the sandbox from August 1, 2024. It will be available live on *August 20th 2024*. Besides the transition to shipping profiles and the legally required product safety information, there are also several other new features. Additional information on the new features can be found in the OPC-helpdesk. **API v3 will be supported until 30th of April 2025**. From this date onwards, the product interface will no longer accept requests via v3.

**Changed**The top-level delivery container becomes optional and will be removed in v4 in 2025. There is no need to transmit deliveryTypes and deliveryTimes, when you setup **shipping-profiles**. The **shipping-profiles** become mandatory, so take the chance and set them up as quickly as possible.
Due to legal requirements the productSafety container will becomes mandatory. Please start entering the safety information as soon as possible.
There is no need anymore to provide start- and end-periods for your sale-prices. These attributes become optional. To setup a reduction on otto.de it will be enough, to set the standardPrice and the salePrice.
The sale periods can still be used. In this case, both the start and end dates must still be set and must be valid.
New SKUs will be sanitized. It is not allowed to use leading or trailing spaces and the SKUs should be UTF8-compliant.
It will still be possible to update existing SKUs that were created with API v3 or older.
|\n\n"},{"name":"Orders-V4","description":"### Order Interface\n\nThis interface allows partners and service partners to view orders and associated position items. It also allows sending cancellations on order and position item level.\n\nThe term *sales order* refers to a customer's order with items from different partners. The term *partner order* refers to a customer's order containing only the positions of a single partner.
\nThis interface is only concerned with partner orders.\n\nA position item is the physical product a customer has ordered. A checkout with a product quantity greater than one will produce unique position items within the partner order.\n\n### Authentication\n\nEvery operation on this interface requires proper credentials. Partners only have visibility on their own orders.\n\n\n### Fulfillment States\n\nA position item can stay in different fulfillment states (attribute 'fulfillmentStatus'):\n\n1. ANNOUNCED -> An ordered position item which shall be reserved for the customer but shall not be shipped yet. The position item can still be cancelled by the marketplace and the customer. The address of the customer is not visible in this state. \n2. PROCESSABLE -> This position item is ready to be fulfilled.\n3. SENT -> This position item was shipped. It was processed by the [Shipments interface](./docs#tag/Shipments-V1).\n4. RETURNED -> This position item was returned. It was processed by the [Returns interface](./docs#tag/Returns-V2).\n5. CANCELLED\\_BY\\_PARTNER -> This position item was cancelled by the partner and won't be processed any further.\n6. CANCELLED\\_BY\\_MARKETPLACE -> This position item was cancelled by the marketplace and won't be processed any further. In case of a partner termination all position items in state ANNOUNCED or PROCESSABLE will be cancelled.\n\n### Possible State Transitions\n\n\n\nThe position item states determine the whole order's lifecycle state:\n\n* The order will be classified as ANNOUNCED, PROCESSABLE, SENT, or RETURNED if at least one position item is in an analogous state **AND** all other position items have the same or higher state according to above-mentioned list.\n* The order will also be classified as CANCELLED\\_BY\\_MARKETPLACE or CANCELLED\\_BY\\_PARTNER if it has at least one position item in fulfillment state CANCELLED\\_BY\\_MARKETPLACE resp. CANCELLED\\_BY\\_PARTNER.\n\nThe latest lifecycle change is recorded in order attribute 'lifecycleChangeDate'. You can choose to query by lifecycle state or position item state by using the ```mode```\n\n\n\n### Fetching Orders\n\nOrders can be fetched individually by ```salesOrderId```/ ```orderNumber``` or as a list by using different filter criteria.\n\n#### Common Use Cases\n\n##### Fetch open orders\n\nOrders can be constantly created. After the payment confirmation orders change to state PROCESSABLE. To fetch orders after they became processable this REST call can be used\n\n```\nGET /v4/orders?fulfillmentStatus=PROCESSABLE\n```\n\nIf there is a next link it can be followed until there are no new orders. To start at a certain date the fromDate can be used, which relates to the lifecycleChangeDate, which in this case is when order became PROCESSABLE. \n\n```\nGET /v4/orders?fulfillmentStatus=PROCESSABLE&orderColumnType=ORDER_LIFECYCLE_DATE&fromDate=2023-07-01T00:00:00Z\n```\n\nThis works in a similar way for other status and combinations, for example\n\n```\nGET /v4/orders?fulfillmentStatus=PROCESSABLE,SENT\n```\n\n##### Fetch all orders for a day\n\n```\nGET /v4/orders?fromOrderDate=2023-07-01T00:00:00Z&toOrderDate=2023-07-02T00:00:00Z&orderColumnType=ORDER_DATE\n```\n\nThe next link can be followed until there are no orders left. \n\n##### Fetch all orders with returned positions\n\nTo fetch orders with at least one returned position the following query can be used\n\n```\nGET /v4/orders?fulfillmentStatus=RETURNED&mode=AT_LEAST_ONE&orderColumnType=LAST_MODIFIED_DATE&fromDate=2023-07-01T00:00:00Z\n```\n\n##### Fetch a single order\n\nBy ```salesOrderId```\n\n```\nGET /v4/orders/82f3e02f-2f56-448d-8f3b-d42f5a475119\n```\n\nBy ```orderNumber```\n\n```\nGET /v4/orders/v8pnyhq2nh\n```\n\n#### Performance Hints\n\nThere can be a lot of combinations of parameters for the API which will result in varying response times. For best performance results try to use either ```fromDate``` or ```fromOrderDate```/ ```toOrderDate```, not both at the same time.\nFurthermore, the right orderColumnType can improve search performance.\n* The default ```orderColumnType```, ```orderColumnType=ORDER_LIFECYCLE_DATE``` or ```orderColumnType=LAST_MODIFIED_DATE``` works best with ```fromDate```\n* ```orderColumnType=ORDER_DATE``` works best with ```fromOrderDate```/ ```toOrderDate```.\n\nFor quicker results or with fewer data expected, a smaller ```limit``` could be used. The default limit is `128`.\n\n#### Pagination\n\nPaging will occur if the number of returned orders exceeds the current limit (request parameter ```limit```).\n\n#### Example\n\n```\n{\n \"resources\": [\n { \n ...\n }\n ...\n ],\n \"links\": [\n {\n \"href\": \"/v4/orders?nextcursor=eyJmZiI6MTY4ODU0Mzk5MDUxMCwicGlmIjoiMTAwNjI1MCIsIm0iOiJCVUNLRVQiLCJvY3QiOiJPUkRFUl9MSUZFQ1lDTEVfREFURSIsIm9kIjoiQVNDIiwic3RmIjoic2FsZXNPcmRlcklkIiwibHNvaSI6ImUxM2IwYTMyLWU1ZTMtNDEwYi05YWQ2LTliZWRlY2MwNzVjNiIsInNvaWNyIjpmYWxzZX0\",\n \"rel\": \"next\"\n }\n ]\n}\n```\n\nUsing ```/v4/orders?nextcursor=eyJmZiI6MTY4ODU0Mzk5MDUxMCwicGlmIjoiMTAwNjI1MCIsIm0iOiJCVUNLRVQiLCJvY3QiOiJPUkRFUl9MSUZFQ1lDTEVfREFURSIsIm9kIjoiQVNDIiwic3RmIjoic2FsZXNPcmRlcklkIiwibHNvaSI6ImUxM2IwYTMyLWU1ZTMtNDEwYi05YWQ2LTliZWRlY2MwNzVjNiIsInNvaWNyIjpmYWxzZX0``` here would receive the next slice of records; a missing next link indicates no further records.\n\n\n\n\n### Cancellation\n\nPosition items of an order can be cancelled. These position items must be in state PROCESSABLE or ANNOUNCED.
\n**Partner cancellations in general lead to customer dissatisfaction and should be avoided.**\n\nCancellation is possible for only a single position item or the whole order:\n\n- to cancel a single position item send a POST request '/v4/orders/{salesOrderId}/positionItems/{positionItemId}/cancellation'\n- to cancel the whole order send a POST request '/v4/orders/{salesOrderId}/cancellation'\n\nEvery position item which is in fulfillment status PROCESSABLE or ANNOUNCED will be changed to CANCELLED\\_BY\\_PARTNER. If there was a cancellation request from the customer the ```cancellationReason``` will be set to CANCELLED_ON_CUSTOMER_WISH\n\nThe cancellation operations might take a moment until the result is visible on a subsequent fetch request. Conflicts will be reported in an error response.\n\n\n### Changelog\n\nThis changelog will document all relevant changes in our interface. \nKudos to https://keepachangelog.com/de/1.0.0/\n\n\n| Date | Description |\n|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| 2024-09-26 | In this release a new ``paymentMethod`` has been added and other has been deprecated:
**Changed**
- New value ``CREDIT_CARD`` had been added.
- Old value ``CREDIT_CARD_ONLINE`` has been deprecated. |\n| 2024-09-17 | In this release two new optional fields ``dealId`` and ``dealName`` have been added to the position item objects.
**Added**
- New field ``dealId``: the unique id of the deal related to the position item.
- New field ``dealName``: the name of the deal related to the position item. |\n| 2024-08-06 | To improve the customer communication in case of a marketplace cancellation, a new cancellation reason has been introduced:
**Added**
- The new cancellation reason is ``CANCELLED_ON_MARKETPLACE_WISH``. |\n| 2024-05-06 | To improve transparency in case of suspected fraud, in addition to ``PAYMENT_FRAUD``, a new cancellation reason has been introduced:
**Added**
- The new cancellation reason is ``MARKETPLACE_FRAUD``. |\n| 2024-04-08 | In this release, the new field ``returnAcceptedByMarketplace`` has been introduced:
**Added**
- If the return of a position item has been accepted by the marketplace, this flag is set to ``true``. |\n| 2024-02-07 | To improve transparency, 1 new cancellation reason has been introduced:
**Added**
- In case of illegal product, open orders will be cancelled with the fulfillment status set to ``CANCELLED_BY_MARKETPLACE`` and a cancellation reason of ``ILLEGAL_PRODUCT``. |\n| 2024-01-18 | In this release a new optional field ``shopUrl`` has been added to the product object in the position items.
**Added**
- New optional field ``shopUrl`` has been added to the product on the position item level. It contains the url of the product inside the webshop. |\n| 2023-11-09 | To improve transparency, 2 new cancellation reasons have been introduced:
**Changed**
- When the partner cancels an order after having received a fraud suspicion for that order, the cancellation reason will be set to ``PAYMENT_FRAUD`` while the fulfillment status remains ``CANCELLED_BY_PARTNER``.
- When the contract between the partner and OTTO Market has been terminated, open orders will be cancelled with the fulfillment status set to ``CANCELLED_BY_MARKETPLACE`` and a cancellation reason of ``PARTNER_TERMINATED``. |\n| 2022-10-04 | In this release the visibility of partner orders has been adapted.
**Changed**
- All partner orders will now show up instantly in the status ANNOUNCED (regardless of the payment method). Once the time period has exceeded in which the customer can still cancel an order, the respective position items will transition to PROCESSABLE status. If the customer has actually cancelled a position item or an entire order, the respective position items will change their status to CANCELLED_BY_MARKETPLACE with a cancellation reason of CANCELLED_ON_CUSTOMER_WISH. |\n| 2022-05-11 | In this release a new field ``dimensions`` has been added to the product object in the position items.
**Added**
- New field ``dimensions`` has been added to the product on the position item level. It describes the different dimensions of a product from the marketplace. |\n| 2021-11-04 | In this release a new field ``cancellationReason`` has been added to position items.
**Added**
- New field ``cancellationReason`` has been added on position item level, which describes the reason for a cancellation of an item. |\n| 2021-11-01 | In this release a new field ``weeePickup`` has been added to position items.
**Added**
- New optional field ``weeePickup`` has been added on position item level. This field indicates whether customer requested a disposal service as per \"Waste from Electrical and Electronic Equipment\" (WEEE) regulation. |\n| 2021-10-19 | In this release the error message handling has been expanded.
**Added**
- On all endpoints the error response 403 will be given if access role is missing; will include a body conforming to the common error message style. |\n| 2021-10-18 | In this release a new object ``payment`` has been added.
**Added**
- New optional object ``payment`` has been added on partner order level. It includes the ``paymentMethod`` field, which describes the chosen payment method. |\n| 2021-08-30 | In this release GDPR relevant changes were delivered.
**Changed**
- The objects ``deliveryAddress`` and ``invoiceAddress`` of an order (optional since v4) are not provided for orders after 8 weeks after all position items have reached either status SENT or any of the CANCELLED states, i.e. no position item is in BLOCKED or PROCESSABLE status. Both the fields ``email`` and ``phoneNumber`` are no longer provided after 4 weeks. |\n| 2021-08-25 | In this release new date field ``processableDate`` has been added.
**Added**
- New optional field ``processableDate`` has been added on partner position item level, which describes when a position item has reached PROCESSABLE status. |\n| 2021-05-21 | In this release new date field ``expectedDeliveryDate`` has been added.
**Added**
- New optional field ``expectedDeliveryDate`` has been added on partner position item level, which describes when the customer expects the delivery. |\n| 2021-04-30 | This is the first release of version 4 (v4) of the Orders API. Compared to version 3 (v3) we introduced the following changes. (v3 has been deprecated with the release of v4. It is planned to take v3 offline by 2021-10-31 at the earliest.)

**Added**
- Used customer discounts (optional field ``initialDiscounts``) are now part of the received order documents.
- All error responses (4xx) include a body conforming to the common error message style.

**Changed**
- The type of product items' VAT rate changed to *number* (used to be of type *string*).
- Delivery fees of an order are contained in array ``initialDeliveryFees`` instead of ``initialServiceFees``.
- Like prices, delivery fees and discounts now have a dedicated monetary object ``deliveryFeeAmount`` resp. ``discountAmount``.
- In case of a conflict while cancelling multiple position items the error response provides details for every failed item.
- The fields ``deliveryAddress`` and ``invoiceAddress`` of an order have become optional - these fields are not provided for orders with all position items in state ANNOUNCED or CANCELLED\\_BY\\_MARKETPLACE.
- In paginated responses the 'links' attribute will no longer appear if there are no further records (used to be an empty array)

**Removed**
- Within the query for orders the parameters 'searchTerm' and 'searchTermField' are no longer available. |\n\n\n"},{"name":"ReturnShipments-V1","description":"### ReturnShipments Interface\n\nThis interface should be used to find return shipments which have been handed over to the carrier for final delivery to the partner.\n\n### Changelog\n\nThis changelog will document all relevant changes in our interface.
\nKudos to https://keepachangelog.com/de/1.0.0/\n\n| Date | Description |\n|--------------|--------------------------------------------------------------------------------------------------------------------------------|\n| 2023-07-06 | **Changed**
- changed ReturnShipmentState order |\n| 2023-07-06 | **Changed**
- Add new ReturnShipmentState ANNOUNCED |\n| 2023-04-14 | **Changed**
- Fixed the name of 'creationDate' to 'createdAt' to match the actual implementation, added some documentation |\n| 2023-03-27 | **Changed**
- Go live of API Definition |\n| 2023-02-10 | **Changed**
- Change name of id consistently to returnShipmentId |\n| 2023-02-10 | **Changed**
- Fixed property names of ReturnPositionItems |\n| 2023-02-07 | **Changed**
- return-shipments endpoint returns list of full return-shipments, removed ReturnShipmentsWithMinimumDetails |\n| 2022-12-12 | **Added**
- first version of the API Definition |\n"},{"name":"Shipments-V1","description":"### Shipment Interface\n\nThis interface should be used to report that shipments have been handed over to the carrier for final delivery to the customer.\n\n### Changelog\n\nThis changelog will document all relevant changes in our interface.
\nKudos to https://keepachangelog.com/de/1.0.0/\n\n| Date | Description |\n|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| 2024-09-23 | **Changed**
- Changed description for multiparcel-shipments |\n| 2024-07-23 | **Added**
- added new carriers: RABEN_LOGISTIK, ZUFALL, GEIS, DSV, EPH_DIREKT, SCHMIDT_GEVELSBERG, GUETTLER, REIMER, HEUEL |\n| 2023-03-22 | **Changed**
- Added endpoint for multiparcel-shipments. |\n| 2022-09-12 | **Changed**
- Deleted field returnAddressCarrierId from the Documentation, field no longer needed in the request. |\n| 2022-07-12 | **Added**
- added new field returnAddressCarrierId, unique id for the return address and the return carrier combination. Backend logic not deployed in live yet. |\n| 2022-06-24 | **Added**
- added authorization to the endpoints and use new roles separated for read and write |\n| 2022-05-01 | **Added**
- add new ShipmentStates array to Shipments
- add add new ShipmentStates array to ShipmentWithMinimumDetails objects |\n| 2020-07-02 | **Added**
- add new carrier \"DHL_HOME_DELIVERY\"
- add new optional property _jsonPath_ to _ErrorDescription

**Changed**
rework of the validation of the request body for better user experience as version 1.1.0
- better error messages in _title_ and _detail_ properties of _ErrorDescription_
- a new optional property _jsonPath_ in _ErrorDescription_ to imply where the error happened
- multiple _ErrorDescription_ in _BadRequest_, _BadRequestAddPositionItemByTrackingNumber_ and _BadRequestAddPositionItemByShipmentId_ possible |\n| 2020-03-31 | **Changed**
- add length restriction to shipFromAddress.city and shipFromAddress.zipCode |\n| 2020-02-12 | **Added**
- add some examples for CreateShipmentRequest for carrier \"OTHER_FORWARDER\" |\n| 2020-01-14 | **Added**
- support of utc timestamps with offsets for shipDate |\n| 2019-11-07 | **Changed**
- changed carrier OTHER to OTHER_FORWARDER |\n| 2019-10-25 | **Added**
added new carrier or forwarder
- DHL_FREIGHT
- HES
- HELLMANN
- DB_SCHENKER
- IDS
- EMONS
- DACHSER
- LOGWIN
- KUEHNE_NAGEL
- SCHOCKEMOEHLE
- KOCH
- REITHMEIER
- OTHER

**Changed**
- added more detailed description

**Removed**
- removed carrier OTHERS |\n| 2019-08-29 | **Changed**
- renamed carrier and returnCarrier 'HERMES_GERMANY' to 'HERMES' |\n| 2019-08-14 | **Changed**
- type of shipmentId changed from integer to string |\n"},{"name":"Returns-V3","description":"### Returns Interface\n\nAfter you have sent the product to the customer, but the customer has unfortunately decided not to keep it, this Returns Interface allows you to report the return.\n\nIn principle, you will accept a return, so that we can trigger the customer payment immediately. \nIt would be great if you would also inform us about the condition of the return and the reason for acceptance.\n\nAccept reason is a set of values to tell us why you are accepting the return.
\nThis will help us understand and if possible, the business reason behind accept returns.
\nSome examples of accept reasons could be \"RETURN_RECEIVED\", \"CANCEL_REQUEST_BY_CUSTOMER\", \"SHIPMENT_LOST\", \"RETURN_LOST\", etc.
\n\nIn the rare case (e.g. if the return does not correspond to the correct article) that you do not want to accept a return, you also have the option to reject the return.
\nIn this case we would like to receive a reason in addition to the condition of the return.\n\nReject reason is a set of values where you can tell us why you are rejecting the return. This will help us understand and if possible, reduce \"bad\" returns.\nSome examples of reject reasons could be \"WRONG_ITEM\", \"EXCHANGE\", \"ITEM_NOT_IN_THE_PARCEL\", etc.

\n\n\nWe expect the following values for the condition:\n* A for \"in original packaging\" \n* B for \"in mint condition\"\n* C for \"slightly used\"\n* D for \"heavily used\"\n* E for \"mistake (Delivery incomplete, not available,...)\"\n\nIf you have already accepted a return, it cannot be rejected again afterwards.
\nHowever, if you feel you have changed your mind about a rejected return, you still have the option to accept the return afterwards.\n\n\n### Changelog\n\nThis changelog will document all relevant changes in our interface.
\nKudos to https://keepachangelog.com/de/1.0.0/\n\n\n| Date | Description |\n|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| 2024-03-18 | We are introducing API v3 in which **return rejection reason should be one of the enum values; rather than a free text earlier**.

From v3, return acceptance can also have a reason as an optional enum value.

**API version v2 will be supported till 30th September, 2024.

After this date, the returns interface will reject requests via v2 and only v3 will be supported. Please do the necessary changes to migrate to v3 version.** |\n"},{"name":"Receipts-V3","description":"### Receipts Interface\nThe API allows you to get all customer receipts generated in customer billing processes by OTTO Market in your name.\nAs long as you have regular access to OTTO Market you can get all receipts up to 4 years old. We cannot guarantee this forever, so it would be good, if you plan to get receipts regularly.\n\n### Receipt types\nYou will currently find customer receipts of the following receipt types:\n- PURCHASE
\n A purchase receipt (also known as an invoice) records the prices charged to the customer at the time of sale, taking into account any instant discounts.\n The receipt contains information per order, partner and shipment. It is generated when items are shipped to the customer, so there may be more than one receipt per order.\n Shipping costs are charged only once per partner and per order, and are billed with first purchase receipt of this partner order.\n Surcharges imposed by payment provider on the customer for using special payment conditions are not included in the OTTO Market receipts.\n- REFUND
\n We distinguish between different types of reimbursement documents. A refund receipt documents a credit note issued to a customer for a refund.\n This document is currently created when returns are accepted. In very rare cases, refund receipts may also be created during the cancellation process to reimburse shipping costs for full returns.\n Previous partial refunds will be taken into account.\n- PARTIAL_REFUND
\n We distinguish different types of reimbursement documents. A partial refund receipt documents a credit note issued to a customer without return.\n As a partner, you might offer a customer a partial refund if there is a legitimate complaint to avoid a return.\n\n### Representation of receipts\nCustomer receipts are provided in various formats. You decide which formats best support your processes. The following formats are available:\n- PDF document
\n Customer receipts in PDF format are graphically enhanced and contain some details in addition to the raw invoice data some details you can only find on PDF documents, like:\n - Company logo of OTTO (as operator of OTTO Market)\n - Company details of financial service partners\n - Contact details of OTTO (as relation center operator for customer inquiries and complaints)\n Dates on receipts in PDF format are always printed in format DD.MM.YYYY in German time zone(CET/CEST)\n- JSON format
\n Customer receipts in JSON format are presented in a structured easily readable technical format. It's particular suitable for you, if you want to use the data in your own technical applications.
\n In addition to billing information, the JSON format provides you with further information that can help you control or simplify your processes.
\n
\n __Rough class diagram of representation in JSON format__
\n ⚠ This class diagram only shows the main objects of general structure.
\n \n\n### Fetching Receipts\nA single receipt can be fetched individually by ```receiptNumber``` or as a list by using different filter criteria.\nWhen products are shipped, PURCHASE receipts(invoices) are generated. Before this happens, you will not find any customer receipts on OTTO Market.\nWhen products are returned or refunded, REFUND receipts are generated.\nYou have the possibility to grant price reduction to avoid refunds e.g. when there are customer complaints. If a subsequent discount is triggered a PARTIAL\\_REFUND is generated.\n\n#### Common Use Cases\nReceipts in JSON format are not visible for customers. To fetch a PDF document you need the ```receiptNumber``` first. There are different ways you can get it.\n\n##### Fetch all purchase receipts for a special order\nWhen products are shipped, purchase receipts(invoices) are created. This could take even in happy path some minutes because on OTTO Market we try to consolidate invoices from different shipments for the customers. As long as no purchase receipt is created, you will not find any customer receipts on OTTO Market.\nThis is how you can get receipts of any ```receiptType``` by ```salesOrderId```. Here an example for receipt type PURCHASE\n```\nGET v3/receipts?receiptTypes=PURCHASE&salesOrderId=82f3e02f-2f56-448d-8f3b-d42f5a475119\n```\nIf there is a next link follow it until there are no new receipts. To start at a certain date use ```from```\n```\nGET v3/receipts?receiptTypes=PURCHASE&salesOrderId=82f3e02f-2f56-448d-8f3b-d42f5a475119&from=2022-08-01\n```\n\n##### Fetch all partial refund receipts for a special order\nPartial refund receipts are generated in after sale, eg. to avoid returns by granting a subsequent price reduction when customers have complaints.\nIf there are any receipts of this type, the request from above will look like this.\n```\nGET /v3/receipts?receiptTypes=PARTIAL_REFUND&salesOrderId=82f3e02f-2f56-448d-8f3b-d42f5a475119\n```\n\n##### Fetch all refund receipt for a special order\nRefund receipt get generated, when e.g. products are refunded.\nIf there are any receipts of this type, the request from above will look like this.\n```\nGET /v3/receipts?receiptTypes=REFUND&salesOrderId=82f3e02f-2f56-448d-8f3b-d42f5a4751191\n```\n\n##### Fetch receipts of different types together\nFor sure, you can also fetch receipts of more than one receipt type at the same time by extending the array of ```receiptTypes```.\nThis is how it could look like\n```\nGET v3/receipts?receiptTypes=PURCHASE,REFUND&salesOrderId=82f3e02f-2f56-448d-8f3b-d42f5a475119&from=2022-08-01\n```\n\n##### Fetch all receipts generated in a month\nMaybe you want to archive all receipts generated in your name by OTTO Market monthly, fetch it this way:\n```\nGET /v3/receipts?receiptTypes=PURCHASE,PARTIAL_REFUND,REFUND&from=2022-08-01&to=2022-08-31\n```\nIf there is a next link follow it until there are no new receipts.\nIf you like to get also PDF documents, get the receipt numbers first as described above and use it to get the PDF documents in a second step.\n\n##### Fetch JSON representation by a single receipt\nThis is how you can get JSON representation by ```receiptNumber```= R-DE-123456789-2020-1507\n```\nGET /v3/receipts/R-DE-123456789-2020-1507\n```\n\n##### Fetch PDF document by a single receipt\nPDF documents are visible for customers in aftersales area. To fetch a PDF document you need the ```receiptNumber``` first. You can get it with one of the requests described above.\nThis is how you can get PDF document by ```receiptNumber```= R-DE-123456789-2020-1507\n```\nGET /v3/receipts/R-DE-123456789-2020-1507.pdf\n```\n\n#### Performance Hints\nThere can be a lot of combinations of parameters for the API which will result in varying response times. For best performance results try to use ```from``` & ```to``` and try to limit the duration between these dates.\nAvoid using ```page``` which is deprecated. Use ```next``` instead.\nFor quicker results or with fewer data expected, a smaller ```limit``` could be used. The default limit is `128`.\n\n#### Pagination\nPaging will occur if the number of returned receipts exceeds the current limit (request parameter ```limit```).\n\n##### Example\n```\n{\n \"resources\": [\n { \n ...\n }\n ...\n ],\n \"links\": [\n {\n \"href\": \"/v3/receipts?nextcursor=eyJmZiI6MTY4ODU0Mzk5MDUxMCwicGlmIjoiMTAwNjI1MCIsIm0iOiJCVUNLRVQiLCJvY3QiOiJPUkRFUl9MSUZFQ1lDTEVfREFURSIsIm9kIjoiQVNDIiwic3RmIjoic2FsZXNPcmRlcklkIiwibHNvaSI6ImUxM2IwYTMyLWU1ZTMtNDEwYi05YWQ2LTliZWRlY2MwNzVjNiIsInNvaWNyIjpmYWxzZX0\",\n \"rel\": \"next\"\n }\n ]\n}\n```\nUsing ```/v3/receipts?next=eyJmZiI6MTY4ODU0Mzk5MDUxMCwicGlmIjoiMTAwNjI1MCIsIm0iOiJCVUNLRVQiLCJvY3QiOiJPUkRFUl9MSUZFQ1lDTEVfREFURSIsIm9kIjoiQVNDIiwic3RmIjoic2FsZXNPcmRlcklkIiwibHNvaSI6ImUxM2IwYTMyLWU1ZTMtNDEwYi05YWQ2LTliZWRlY2MwNzVjNiIsInNvaWNyIjpmYWxzZX0``` here would receive the next slice of records; a missing next link indicates no further records.\n\n### Glossary\n* _Receipt_ - Collection of all details of a receipt. A receipt can have different receiptTypes\n* _Customer_ - Customer information\n* _Address_ - Address entered by customer during the order process. Recipient can be a person or a pickup point.\n* _Partner_ - Partner details when generating the receipt\n* _LineItems_ - Object, that contains all kinds of possible line items of a receipt, like:\n * _ItemPosition_ - Representation of an item
Never used in context of receipts of receiptType PARTIAL_REFUND\n * _DeliveryCost_ - Representation of delivery cost like delivery fee or freight surcharge
Never used in context of receipts of receiptType PARTIAL_REFUND\n * _ServicePosition_ - Representation of a service
Never used in context of receipts of receiptType PARTIAL_REFUND\n * _ItemPartialRefundPosition_ - Reduction of an item price granted by a receipt of receiptType PARTIAL_REFUND\n * _ServicePartialRefundPosition_ - Reduction on a service price granted by a receipt of receiptType PARTIAL_REFUND\n * _DeliveryFeePartialRefundPosition_ - Reduction on delivery costs granted by a receipt of receiptType PARTIAL_REFUND\n* _PriceModification_ - PriceModification objects represent price increases and decreases of individual line item objects. Currently we only know decreases.
\n On the pdf documents increases and decreases do not necessarily have to be shown on the same line. If there is a discrepancy, it is visible by different line numbers of this object and the parent line item object.
\n Different PriceModification objects of same type are possible.\n* _Payment_ - Payment details\n* _TotalsReduction_ - Reduction on receipt level\n* _Shipment_ - Additional information of shipment\n* _receiptNumber_ - The receipt number is unique per partner and is build up as follows ```---```\n with:\n * ``````: The reference is used to differentiate different sequence number ranges from each other. The following sequence number ranges can exist:\n R = Purchase receipts\n E = refund receipts\n * ``````: VAT Id = Value Added Tax identification number. We separate the country abbreviation from the rest of the number with a hyphen, i.e. as follows: DE-123456789\n * ``````: The year is determined on the basis of UTC time. The information is displayed in the format YYYY.\n * ``````: Sequence number ranges are assigned once a year. They start at 1 and have no fixed length\n\n### Changelog\n\nThis changelog will document all relevant changes in our interface.
\nKudos to https://keepachangelog.com/de/1.0.0/\n\n| Date | Description |\n|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| 2025-01-08 | **Added** Add new price modifications type ```REFUND_CREDIT_CARD_DISPUTE```
Add new partial refund type ```REFUND_CREDIT_CARD_DISPUTE```
|\n| 2024-10-11 | **Added** Add new value CREDIT\\_CARD to ```paymentMethod```
|\n| 2024-09-27 | **Added** Add field ```insurancePeriod``` to ```ServicePartialRefundPosition```
|\n| 2024-09-24 | **Added** Add new value INSURANCE to ```serviceType``` of ```ServicePosition```
Add new object schema ```ServicePartialRefundPosition```
Add field ```servicePartialRefundPositions``` as array of ```ServicePartialRefundPosition``` to ```LineItems```
|\n| 2024-09-20 | **Added** Add new values SERVICE\\_FULL\\_REFUND\\_CANCELLED\\_BY\\_SDU, SERVICE\\_FULL\\_REFUND\\_PRODUCT\\_RETURNED to ```refundType``` of ```Receipt```
Add new value REFUND\\_PARTIAL\\_AMOUNT\\_AFTER\\_SERVICE\\_CANCELLATION to ```partialRefundType``` of ```Receipt```
Add new value REFUND\\_PARTIAL\\_AMOUNT\\_AFTER\\_SERVICE\\_CANCELLATION to ```priceModificationType``` of ```PriceModification```

|\n| 2024-07-16 | **Added** Add field ```paymentBreak``` to ```Payment```
|\n| 2024-05-21 | **Added** Add field ```linkedPositionItemId``` to ```Details```
|\n| 2024-04-22 | **Added** Add new value REFUND\\_ESCALATION to ```priceModificationType``` of ```PriceModification```
Add new value REFUND\\_ESCALATION to ```partialRefundType``` of ```Receipt```
|\n| 2023-11-13 | **Added** Add new value REFUND\\_PAYPAL\\_DISPUTE to field ```priceModificationType``` of ```PriceModification```
|\n| 2023-11-09 | **Added** Add field ```shipment```
Add new object schema ```AddressInformation```
Add field ```shipment``` of object type ```Shipment``` to ```Receipt```
Add field ```shipFromAddress``` of object type ```AddressInformation``` to ```Shipment```
|\n| 2023-09-07 | **Added** Add new query parameter ```next``` to endpoint ```GET /v3/receipts```
**Deprecated** Set query parameter ```page``` of ```GET /v3/receipts``` to deprecated. **Please switch to new parameter ```next```**
|\n| 2023-08-09 | **Added** Add new value PAYPAL to field ```paymentMethod``` of ```Payment```
|\n| 2023-06-19 | **Added** Add field ```priceModifications``` as array of ```PriceModification``` to ```ServicePosition```
Add object schema ```ServicePartialRefundPosition```
Add field ```servicePartialRefundPositions``` as array of ```ServicePartialRefundPosition``` to ```LineItems```
Add object schema ```DeliveryFeePartialRefundPosition```
Add field ```deliveryFeePartialRefundPositions``` as array of ```DeliveryFeePartialRefundPosition``` to```LineItems```
Add object schema ```PartialRefundDetails```
Add field ```partialRefundDetails``` of ```PartialRefundDetails``` to ```ItemPartialRefundPosition```
Add field ```partialRefundType``` to ```Receipt``` for PARTIAL\\_REFUND receipts
Add field ```reason``` to ```Details``` for PARTIAL_REFUND receipts
Add field ```type``` to ```Details``` of ```PriceModification```
**Changed** Change description of field ```priceModificationType``` of ```PriceModification```
Change description of field ```description``` of ```Details```
|\n| 2023-05-31 | **Added** Add field ```totalsReductions``` to ```Receipt```
Add field ```priceToPayPerPositionItems``` to ```ItemPosition``` for PURCHASE receipts
|\n| 2023-04-26 | **Added** Add field ```refundType``` to ```Receipt``` for REFUND receipts
|\n| 2023-01-11 | We are proudly introducing our Receipts API v3 with a lot of changes compared to v2, that we will roughly describe here.
**v2 will be supported until 11th of July 2023.** After this date, the receipts interface will reject requests via v2.

**Changed** Query parameter ```sales_order_id``` of ```/receipts``` endpoint has been renamed to ```salesOrderId```
Field ```type```of ```Receipt``` has been renamed to ```receiptType```
Field ```originalReceiptNumber``` has been renamed to ```linkedReceiptNumber```
Field ```originalCreationDate``` has been renamed to ```linkedCreationDate```
Field ```name``` of ```Partner``` has been renamed to ```partnerName```
Field ```legalRepresentatives``` of ```Partner``` has been renamed to ```representedBy```
Field ```registerNumber``` of ```Partner``` has been renamed to ```commercialRegisterNumber```
Field ```street``` of ```Customer``` will not contain house number for newly created receipts
Field ```articleNumber``` will contain promotion as suffix
Array field ```lineItems``` was only used for item positions previously, now there is a sub structure that cares about all bill objects
Field ```dimensions``` of ```lineItem``` has been renamed to ```variationAttributes``` of ```ItemPosition```
Field ```amountDue``` will contain the actual amount due from customer
Array field ```shippingCosts``` has been renamed to ```deliveryCosts```
Field ```vatRate``` has been renamed to ```taxRate```
Field ```vat``` has been renamed to ```tax```
**Added** Add new query parmeter ```receiptTypes```, ```from``` and ```to``` to ```/receipts``` endpoint
New field ```isRealReceipt``` of ```Receipt``` indicates whether its a real invoice or technical invoice
New field ```houseNumber``` of ```Customer``` contains house number of the customer
New field ```houseNumber``` of ```DeliveryAddress``` contains house number of the delivery address
New field ```totals``` as array of ```Price``` contains total amount per tax type and tax rate
New field ```totalsGrossAmount``` contains summation of total receipt amount including all tax type
**Removed** Field ```url``` and field ```priceToPay``` has been removed
Query parameter ```type``` has been removed from ```/receipts``` endpoint
|\n"},{"name":"Price-Reductions-V1","description":"### Price Reductions Interface\n\nThis endpoint enables sellers to apply price reductions to shipped products if the product has issues, or the customer is unsatisfied. \nIt´s also possible to view previously applied price reductions. \nPrice reductions can only be applied after products have been marked as shipped.\n\n### Changelog\n\nThis changelog will document all relevant changes in our interface.
\nKudos to https://keepachangelog.com/de/1.0.0/\n\n\n| Date | Description |\n| ---- | ----------- |\n| 2022-01-19 | **Added**
- price reduction APIs"},{"name":"ShippingProfiles-V1","description":"### Partner endpoints for shipping profiles\n\nShippingProfiles can now be created, edited, and deleted using the ShippingProfiles-API. \nAdditionally, the API offers detailed control over delivery times, for example Cut-Off-Time and WorkingDays ensuring precise and efficient management of shipping details.\n\nTo link SKUs to shipping profiles, please use the: [Availability-interface](./docs#tag/Availability-V1).\n\n### Changelog\n\nThis changelog will document all relevant changes in our Partner interfaces.\n\n| Date | Description |\n|------------|-------------------------------------------------------|"},{"name":"Availability-V1","description":"### Partner endpoints for available quantities and linking shipping profiles\n\nThe Availability API allows for the assignment of shipping profiles at the SKU level.\nMoreover, it enables the adjustment of processing times for individual SKUs or multiple SKUs simultaneously, providing flexible and efficient management of product availability. \nThe Quantities-V2 API will be integrated into the Availability-V1 API at the end of March and the entire inventory will be managed through it afterwards. \nThis allows partners and service partners to update the available quantity for a specific SKU (up to 200 SKUs per request). The available quantity can be any integer value >= 0.\n\n### Changelog\n\nThis changelog will document all relevant changes in our Partner interfaces.\n\n| Date | Description |\n|------------|------------------------|\n| 2024-08-05 | Replaces Quantities v2 |\n"}]}}}}}