OTTO Market API documentation



Important: The new version v3 is released now! Please use v3 for now.

We plan to go offline with version 2 (v2) earliest by 01.11.2020.

Order Interface

The Order Interface allows partners and service providers to view orders and its position items. Furthermore it allows to send cancellations.

The term sales order refers to the order with the complete basket and items from different partners. The term partner order refers to an order containing only the positions of a single partner within one sales order. This interface delivers partner orders and unless specified all orders in this document are partner orders.

A position item is the physical product a customer ordered. A checkout with a product quantity of two will produce two unique position items within the partner order.

Orders are only visible to the partner after 45 minutes. The time period before is reserved for the customer, with the option to cancel the order.

Authentication

All interfaces expect the partner to be logged in. All endpoints only allow access to the orders of that partner.

Paging:

Click to expand

The list interfaces return a list with orders and a next link if more records exist. Use the next link to retrieve the next records.

Example:

  1. You query for all orders, which have at least one announced position item: /orders?fulfillmentStatus=ANNOUNCED, optional with a from date like /orders?fulfillmentStatus=ANNOUNCED&fromDate=2019-08-01T01%3A00%3A00Z
  2. In the response you get the first records and a next link like /orders?nextCursor=jdaisbhfisabdfsabdjfb { "resources": [ <--- List of resources { <--- Oldest matching order "salesOrderId": "9864623c-42a4-4892-9270-cd733d32362e", "orderNumber": 5nhxzdr88b, "orderDate": "2019-08-20T08:56:40.385Z", ... "links": [ { "href": "/v3/orders/9864623c-42a4-4892-9270-cd733d32362e", <--- Link to single order "rel": "self" } ] } ... ], "links": [ { "href": "/v3/orders?nextCursor=jdaisbhfisabdfsabdjfb", <--- Link to next list of resources. If not present, no more records exist, currently "rel": "next" } ] }
  3. You execute /orders?nextCursor=jdaisbhfisabdfsabdjfb and receive the next records. When there is no data left, no next link gets returned.

Fulfillment Status

Click to expand

A position item can reach seven different fulfillment status:
1. ANNOUNCED -> A position item which was ordered via payment method Prepayment will be announced, so that the item can be reserved for the customer in the logistics, but must not delivered yet. This position item can change to PROCESSABLE, when it can be fulfilled or to CANCELLED_BY_MARKETPLACE, when it should not be fulfilled.
2. PROCESSABLE -> This position item is ready to be processed.
3. SENT -> The contract is fulfilled, the item was sent. The partner reported the item via the interface Shipments as shipped.
4. RETURNED -> This position item was returned. The Partner has reported the item via the interface Returns as returned.
5. CANCELLED_BY_PARTNER -> This position item was cancelled and won't be fulfilled
6. CANCELLED_BY_MARKETPLACE -> This position item was cancelled by the marketplace and must not get delivered. This happens for example, if the marketplace finds out that a customer is not eligible anymore.

A diagram of the known state transitions:
state-model

Related to the fulfillment status of each position item, the whole order can be classified in lifecycle states, which reflect the processing state of the whole order from a business perspective. The whole order can be classified in the lifecycle states ANNOUNCED, PROCESSABLE, SENT or RETURNED when:

  • At least one position item of the order has one of the fulfillment status
  • AND all other position items have the same OR a higher status related to that sequence: ANNOUNCED -> PROCESSABLE -> SENT -> RETURNED OR one of the status CANCELLED_BY_MARKETPLACE or CANCELLED_BY_PARTNER

The whole order has the lifecycle state CANCELLED_BY_MARKETPLACE or CANCELLED_BY_PARTNER when:

  • At least one position item of the order has the fulfillment status CANCELLED_BY_MARKETPLACE or CANCELLED_BY_PARTNER

When an order switch its lifecycle state, the timestamp of that switch is provided in the attribute lifecycleChangeDate on this order.

Fetching

Click to expand

Orders can only be fetched, when they have an order date older than 45 minutes. The marketplace offers the customers the possibility to cancel during that time. As long as a customer can cancel, the order is not provided. Cancelled orders will also not be provided.

Orders can be fetched as lists by using the fulfillment status and/or lifecycleChangeDate as filter criteria and/or by fetching all existing orders for one partner. Filter criteria can be combined.

Additionally it is possible to fetch one specific order by using the order Id or a specific position item by using the position item Id.

Fetching orders for a specific Fulfillment status

Due to the fact, that the fulfillment status is an attribute on position item level you have to take care of the following conditions.

When a list of all orders in fulfillment status ANNOUNCED, PROCESSABLE, SENT or RETURNED is requested, the order will be part of the response when:

  • at least one position item of the order has the requested fulfillment status

  • and all other position items have the same status or a higher status.

The sequence of the fulfillment status is: ANNOUNCED -> PROCESSABLE -> SENT -> RETURNED.

Example:

 Given order with 2 position items, one with fulfillment status PROCESSABLE and one with fulfillment status SENT.

 When you request all orders with fulfillment status PROCESSABLE, the order is part of the response.

 When you request all orders with fulfillment status SENT, the order is NOT part of the response.

When a list of all orders in fulfillment status CANCELLED_BY_MARKETPLACE or CANCELLED_BY_PARTNER is requested, the order will be part of the response when at least one position item of the order has the requested fulfillment status.

The fulfillment status CANCELLED_BY_MARKETPLACE or CANCELLED_BY_PARTNER is an end state, so they count as highest status a position item can reach.

Example:

Given order with 2 position items, one with fulfillment status PROCESSABLE and one with fulfillment status CANCELLED_BY_PARTNER.

When you request all orders with fulfillment status CANCELLED_BY_PARTNER, the order is part of the response.

When you request all orders with fulfillment status PROCESSABLE, the order is part of the response.

Fetching orders via lifecycleChangeDate

Fetching orders by filter criteria lifecycleChangeDate is possible and you will always get all orders with a date which is younger than that you have requested with the parameter fromDate.

Fetching orders on position item fulfillment status

If you want to request a specific fulfillment status on position item level of an order, you can use the parameter MODE=AT_LEAST_ONE. Then you receive all orders where at least one position item has the requested fulfillment status.

Example:

By using this filter "?fulfillmentStatus=SENT&mode=AT_LEAST_ONE" you will receive all orders which at least one position item has the fulfillment status = SENT

Cancellation

Click to expand

Position items of an order can be cancelled by the partner. The position items must be in the states PROCESSABLE. Cancellations in general lead to customer dissatisfaction and should be avoided at all costs!

There are two different ways to cancel position items. It can be done on each single position item or on the whole order.

To cancel a single position item, send a POST request to the /orders/{salesOrderId}/positionItems/{positionItemId}/cancellation endpoint. The request will be accepted if the resource is present.

The whole order can be cancelled by sending a POST request to the /orders/{salesOrderId}/cancellation endpoint. Every position item which is in the fulfillment status PROCESSABLE will be changed to CANCELLED_BY_PARTNER. The request will be accepted if the resource is present.

The change can take a moment until it is visible on the GET endpoint.

Changelog

This changelog will document all relevant changes in our interface.
Kudos to https://keepachangelog.com/de/1.0.0/


Unreleased

Added

  • no changes

Changed

  • no changes

Removed

  • no changes

Deprecated

  • no changes

Released 2020-07-24

Added

In resources.positionItems added two new optional fields for better tracking when certain changes happened:

  • returnedDate: The date the position item was returned
  • cancellationDate: The date the position item was cancelled

Release 2020-07-21

Added

  • Added query parameters fromOrderDate and toOrderDate to endpoint /orders to filter by order date:

Changed

  • For the /orders endpoint, resources.positionItems.product.productTitle is also considered in the full-text search using the query parameter searchTerm.

Release 2020-04-14

This is the first release of version 3 (v3) of the Orders API. Compared to version 2 (v2) there are the following changes. v2 also has been deprecated with this release of v3. It's planned to take v2 offline by 2020-11-01 at the earliest.

Unreleased

Added

  • no changes

Changed

  • The endpoint for cancellation on positionItem level has been moved from /orders/{salesOrderId}/items/{positionItemId}/cancellation to /orders/{salesOrderId}/positionItems/{positionItemId}/cancellation.
  • In resources.deliveryAddress and resources.invoiceAddress the field country has been renamed to countryCode.

Removed

  • The fulfillment status CONFIRMED is no longer required. Orders can be directly transitioned from PROCESSABLE to SENT or CANCELLED_BY_PARTNER.
  • The endpoints for confirmation /orders/{salesOrderId}/confirmation and /orders/{salesOrderId}/items/{positionItemId}/confirmation have been removed accordingly.

Deprecated

  • no changes

Imprint | Privacy policy | Datenschutz