Skip to main content

Shipments

You can use this interface to report that shipments have been handed over to the carrier for final delivery to the customer. At this point, the position items within the shipment are marked with the state SENT in the OTTO Market. This is the trigger for generating a purchase receipt.

Shipment States​

When retrieving a shipment that was already created, the response will include a list of states. If OTTO can track the shipment by its tracking number, the list will include not only the SENT state but also other states provided by the carrier.

  • SENT
    This status is set when a shipment is reported via Shipment-API and is successfully created in the OTTO Market.
  • Tracking States
    • ON THE WAY
      The shipment is under the carrier's responsibility and on its way to the customer.
    • DELIVERY ATTEMPT FAILED
      An attempt to deliver the shipment failed (e.g. customer was not at home or refused the shipment)
    • DELIVERED FOR PICKUP
      Shipment was delivered to be picked up by the customer, e.g. at a shop / store / post office / or a locker such as "DHL Packstation".
    • DELIVERED
      Shipment was delivered to the customer (or picked up by the customer).

states of shipments diagram

Common use cases​

Creating a Shipment​

The Shipments API allows you to report that a shipment has been handed over to the carrier for final delivery to the customer. To report a new shipment use the following endpoint:

POST /v1/shipments

If the shipment is reported successfully, the position items within the shipment are marked with the state SENT in the OTTO Market. This serves as the trigger for generating the purchase receipt.

The interface also allows you to correct an existing shipment by adding sent items that were not included in the original request. You can use the following endpoints for that purpose:

POST v1/shipments/carriers/{carrier}/trackingnumbers/{trackingNumber}/positionitems
POST v1/shipments/{shipmentId}/positionitems

Retrieving Shipments​

The Shipments API allows you to retrieve information for already created shipments by either trackingNumber or shipmentId. You can use the following endpoints to retrieve a shipment:

GET v1/shipments/carriers/{carrier}/trackingnumbers/{trackingNumber}
GET v1/shipments/{shipmentId}

Retrieving a list of Shipments after a specific creation date​

To get a list of shipments after a certain creation date, you can use the following endpoint. This endpoint supports pagination, allowing you to specify how many shipments to include in each response.

GET /v1/shipments

Creating a Multiparcel Shipment​

If a single article (position item) is sent in multiple shipments, each with its own tracking key, the Shipment-V1 interface allows you to create a multiparcel shipment with following endpoint:

POST v1/multiparcel-shipments

The typical use case involves 2 to 3 shipments for one article (e.g., furniture that cannot be sent in a single parcel).

Multiparcel shipments can only be created for items with a delivery type PARCEL. Forwarder deliveries with multiple pieces are not considered multiparcel, as the different pieces cannot be tracked or delivered separately.

Please note: If you have, for example, 3 articles sent in 3 different parcels, each with its own tracking number, each of the 3 shipments must be reported separately. You cannot use the Multiparcel Shipment endpoint for this purpose.

Pagination​

Pagination is managed using the following parameters:

  • datefrom - This parameter filters shipments that were created after the specified date.
  • limit - This sets the maximum number of shipments returned in each response. The default limit is 25.
  • next - This is a cursor that indicates the next shipmentId to be queried.

Example

If a partner has 28 shipments created after 2025-01-01T00:00:00, the following request

GET /v1/shipments?datefrom=2025-01-01&limit=25

will return the first 25 shipments created after that date. The response will include a link to retrieve the next set of resources:

{
  "links": [
    {
      "href": "/v1/shipments?next=118691951323&datefrom=2025-01-01T00:00:00Z&limit=25",
      "rel": "next"
    }
  ],
  "resources": [
    {
      "shipmentId": "118682798620",
      "creationDate": "2025-01-01T07:03:25.818Z",
      "trackingKey": {
        "carrier": "HERMES",
        "trackingNumber": "H999999999"
      }
    }
  ]
}

Using the following link provided in the previous response

GET /v1/shipments?next=118691951323&datefrom=2025-01-01T00:00:00Z&limit=25

it will return the remaining 3 shipments. If there are no more shipments to retrieve, the link for the next set of resources will be empty.

Glossary​

Sales Order - The sales order is a customer's order that can have items from different partners.

Position Item - The 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

Tracking Key - A tracking key consists of a carrier and a tracking number. Each shipment has a tracking key.

Carrier - Company engaged in transporting goods.

Tracking Number - An identifier for a given shipment assigned by the carrier. The tracking number is mandatory for parcel deliveries (i.e. for position items with a deliveryType PARCEL). The tracking number is optional for forwarder deliveries.

Shipment Id - Unique identifier of a shipment that is internally assigned by OTTO.

Forwarder - Among the carriers, we differentiate between standard parcel carriers (HERMES, DHL, UPS, GLS or DPD) and forwarders (e.g. Kühne + Nagel, Dachser). A forwarder is a transport company typically hired for larger bulky goods, such as furniture.

Parcel Deliveries - We refer to parcel deliveries when goods are transported by a standard parcel carrier like HERMES or DHL.

Forwarder Deliveries - We refer to forwarder deliveries when goods are transported by a forwarder like Kühne + Nagel or Dachser.

Multiparcel Shipments - We refer to a multiparcel shipment when one article (position item) is sent in several different shipments, each with its own tracking key. Forwarder deliveries with multiple pieces are not considered multiparcel, as they cannot be tracked or delivered separately.

ON THIS PAGE