OTTO Market API documentation



Order Interface

The Order Interface allows partners and service providers to view orders and its position items. Furthermore it allows to send confirmation and 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": 2313241, "orderDate": "2019-08-20T08:56:40.385Z", ... "links": [ { "href": "/v2/orders/9864623c-42a4-4892-9270-cd733d32362e", <--- Link to single order "rel": "self" } ] } ... ], "links": [ { "href": "/v2/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 and should be confirmed.
3. CONFIRMED -> This position item was confirmed to be fulfilled by the partner.
4. SENT -> The contract is fulfilled, the item was sent. The partner reported the item via the interface Shipments as shipped.
5. RETURNED -> This position item was returned. The Partner has reported the item via the interface Returns as returned.
6. CANCELLED_BY_PARTNER -> This position item was cancelled and won't be fulfilled
7. 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, CONFIRMED, 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 -> CONFIRMED -> 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, CONFIRMED, 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 -> CONFIRMED -> SENT -> RETURNED.

Example:

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

When you request all orders with fulfillment status CONFIRMED, 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.

Confirmation

Click to expand

position items of an order must be confirmed to show to the customer that the contract will be fulfilled from the partner side. The confirmation can just be made on a position item which is in the fulfillment status PROCESSABLE.

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

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

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

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

Cancellation

Click to expand

Position items of an order can be cancelled by the partner. The position items must be in the states PROCESSABLE or CONFIRMED. 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}/items/{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 or CONFIRMED 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 2019-10-28

Added

In request /orders added documentation regarding passing one or more fulfillmentStatuses which is required for UI requests.


Released 2019-10-22

Added

In resources.deliveryAddress & resources.invoiceAddress added the new optional field phoneNumber which is required for customer communication when 2-Man Handling product is involved in an order.


Released 2019-10-15

Added

In resources.positionItems.product added the new field ean for the ean number


Released 2019-09-18

Added

In the Array Field initialServiceFees which contains initial service fee costs

  • initialServiceFees[].positionItemIds[] -> List of positionItemIds which are connected to this service fee

Released 2019-09-10

Added

New Array Field initialServiceFees which contains initial service fee costs

  • initialServiceFees[].amount -> Price of this service fee
  • initialServiceFees[].currency -> Currency of this service fee
  • initialServiceFees[].name -> Name of this service fee

Imprint | Privacy policy | Datenschutz