Best Practices

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!

1. Stay within the rate limits
2. Send data in Batch and fetch data as a list
3. Take action when getting back http 4** errors
4. Consider the two-step validation process for creating products
5. Consider the "Unchanged" status during product update or creation
6. Make sure product identifier stays the same
7. Maintain the most relevant attributes for your products
8. Keep information provided by OTTO up to date
9. Consider the content requirements for product data
10. Utilize the MOIN as an identifier for further processes
11. Use Announced Orders for stock reservation
12. Consider the delivery type in the shipments

Stay within the rate limits

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

Send data in Batch and fetch data as a list

To 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. If 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. In 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.

Take action when getting back http 4** errors

For 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. Each 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.

Consider the two-step validation process for creating products

Product 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) 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), and resolving these errors directly generates an offer on otto.de.

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

Consider the "Unchanged" status during product update or creation

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

Make sure product identifier stay the same

The 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/ active=false). After 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/ active=true). If the SKUs have changed, they will be treated as new SKUs and will start with active=true status.

Maintain the most relevant attributes for your products

The 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 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. You can also find information about attributes relevant for the variant building on otto.de. The right attributes will be shown withing the variationThemes. It is highly recommended to maintain as much attributes with relevance=HIGH to higher your visibility on otto.de.

Keep information provided by OTTO up to date

As 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). This ensures that only valid categories, attributes, and allowed values are transmitted. Similarly, the brand list (GET /products/brands should be kept up to date. Regularly retrieving these lists, ideally on a daily basis, ensures their accuracy and minimizes the potential for errors.

Consider the content requirements for product data

During the product transfer, certain mandatory fields (such as SKU, EAN, category, brandid - see "required" in the request body schema of the POST /products/ endpoint and attributes marked within the category list with featureRelevance=LEGAL must be provided. Additionally, 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.

Technical requirements for media data:

• File formats: ○ Images: JPG, PNG ○ Documents: PDF • Minimum dimensions for images: 500x1000 px (including color tiles and energy labels) • File name: No special characters or umlauts • Color space: RGB - Color spaces such as CMYK are not supported • Maximum image side for image: 4500 px • 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.).

Utilize the MOIN as an identifier for further processes

Always 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, 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.

Use Announced Orders for stock reservation

Before 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. It 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.

Consider the delivery type in the shipments

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