Use-Cases
How to list your first product
This sections goal is to guide you through our API docs and help you list your first product on the OTTO Market. You´ll find short introductions to the steps to be taken followed by a link to the technical documentation for that step.
To list a product you´ll have to do the following:
- Authenticate
- Read valid brands
- Read valid categories
- Post product
- Check update-tasks
- Check marketplace status
- Create shipping profile
- Update product delivery information
- Update quantities
Authenticate
At first, you have to start by authenticating to the OTTO Market Server by posting your credentials to fetch an access token
Read valid brands
Next 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. getBrands
Read valid categories
Following that you´ll need to read the valid categories to know which category to list your products in. You are also 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. getCategoryGroups
Post product
When 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. By reading the documentation mentioned below you´ll learn which values (e.g. EAN, SKU, productDescription, ...) are required. Please 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". You´ll also find an example request for create or update product variants on this page. getPartnerProducts
Check update-tasks
If 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". To 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. Don´t forget to check the update-tasks another time before carrying on. 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. progressByProcessId
Check marketplace status
Last validation step for your product is to check the marketplace status of your SKU. Through 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". getMarketPlaceStatusList
Create shipping profile
After 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. You can either create your shipping profiles manually in the OTTO Partner Connect Portal or using the API. Besides the transportation and default processing time, you need to give information about the deliveryType, Cut-Off-Time and the working days. If you will offer products with different deliveryTypes, you would need to create more than one shipping profiles. Each shipping profile will get a shippingProfileId which should be used in the next step. You´ll also find an example request for create, update and get a shipping profile on this page. ShippingProfiles-V1
Update product delivery information
If you´ve created shipping profiles and successfully created your first SKUs, you can now add product delivery information to the correct SKUs. You can either work with the default processingTime configured in the shipping profile or update the processingTime for a specific SKU via the POST Request. To reduce error messages, just sent over product delivery information for SKU wherefore you have gotten a "moin" via the marketplace status. storeProductDeliveryInformationUsingPOST
Update quantities
Lastly 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. storeAvailableQuantitiesUsingPOST
Congratulations! You´ve successfully listed your first product on the OTTO Market. The 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.
Manage an order from start to finish
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. You´ll find short introductions to the steps to be taken followed by a link to the technical documentation for that step.
To fulfill your first order and manage subsequent activities you´ll have to do the following:
- Authenticate
- Regularly check for new orders
- Report order as shipped
- Fetch purchase receipt
- Regularly screen for return announcements
- Process returns
- Fetch refund receipt
Authenticate
You´ll have to start by authenticating to the OTTO Market Server by posting your credentials to fetch an access token
Regularly check for new orders
Next you´ll have to regurlarly check for new orders to fulfill. We recommend checking several times a day. You´ll find the different fulfillment states orders can have, their descriptions and common use-cases listed at this page. 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. To carry on with fulfilling your first order the state has to be = PROCESSABLE. findPartnerOrders
Report order as shipped
Packaging the ordered items is next before you can hand them to your carrier and mark the order as shipped. We´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. Please read the following endpoint for all technical information: createdAndSentShipmentUsingPOST
If you want to fulfill a sku with more than one package, you´ll need to split the shipment and use this endpoint.
Fetch purchase receipt
After 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 Please read the following endpoint for all technical information: getReceiptsUsingGET_5
Regularly screen for return announcements
Customers 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: getPositionItemsForUsingGETV3
Regularly screen for ReturnShipments
Return shipments which have been handed over to the carrier for final delivery to the partner, you can use the ReturnShipments interface. The customer starts the return process and creates a return label for the shipment. This triggers a continuous query of the tracking status with its specific carrier. Please read the following endpoint for all technical information: listReturnShipmentsUsingGET
Process returns
Received returns have to be checked by your warehouse and either accepted or rejected depending on the condition of the return. Accepting a return will lead to a customer repayment. You can accept returns using this endpoint: receiveAcceptedReturnsV3UsingPOSTV3
If 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: receiveRejectedReturnsV3UsingPOSTV3
Fetch refund receipt
After 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 Please read the following endpoint for all technical information: getReceiptsUsingGET_5
Congratulation! You´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. In the next step, we want to give you more information about after-sales processes. Click here to learn how to do that.
Manage your after sales actions
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. You´ll find short introductions to the steps to be taken followed by a link to the technical documentation for that step.
To manage your after sales activities you´ll have to do the following:
- Authenticate
- Get in touch with customer
- Get customer messages
- Give subsequent discounts (price-reductions)
Authenticate
You´ll have to start by authenticating to the OTTO Market Server by posting your credentials to fetch an access token /docs/category/getting-started
Get in touch with customer
After 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. Attention! You must use as sender e-mail address the one that has been stored in the seller information for customer communication.
There 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. 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.
Get customer messages
Customer 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.
Give subsequent discounts (price-reductions)
If 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. You can either grant discounts within the OTTO Partner Connect or via the API within the "price-reduction" endpoint. The following endpoint documentation describes how you´re able to provide such a "price-reduction": applyPriceReduction
Fetch partial refund receipt
After 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: getReceiptsUsingGET_5