Skip to main content

ReturnShipments

The ReturnShipments API allows you to retrieve information about return shipments that the customers have announced in the Otto Marketplace.

ReturnShipment States​

When retrieving a return shipment that was already created, the response will include a list of states. If OTTO can track the return shipment by its tracking number, the list of states in the response will include updates provided by the carrier. These are the possible states of a return shipment:

  • ANNOUNCED
    The customer has announced the return shipment in the OTTO Marketplace.
  • ON_THE_WAY
    The return shipment has been handed over to the carrier.
  • DELIVERED
    The return shipment has been delivered or is in the final delivery phase. Please note that this status may indicate that the return shipment has been delivered to a carrier hub or parcel center. OTTO does not always receive a final status indicating DELIVERED TO PARTNER, so it may take a few days for the shipment to reach the partner.

states of shipments diagram

Please note that this API exclusively provides information about the shipment of returns. The final state DELIVERED corresponds to a carrier scan.

This API does not include further information regarding the return processing, such as whether the return has been accepted or if the customer has been refunded.

Common use cases​

Retrieving a ReturnShipment​

To retrieve a specific return shipment, you can use one of the following endpoints. You can identify the shipment using either the carrier and trackingNumber or the returnShipmentId.

GET /v1/return-shipments/carriers/{carrier}/trackingnumbers/{trackingNumber}
GET /v1/return-shipments/{returnShipmentId}

When you request a list of return shipments with the endpoint described below, the returnShipmentId will be part of the response.

Please note that searching by tracking number will only find return shipments that were announced in the last 30 days or 42 days, depending on the carrier. This is because tracking numbers may be reused and are not unique over time. Searching by returnShipmentId will find return shipments announced within the past 12 months.

Retrieving a list of ReturnShipments after a specific date​

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

GET /v1/return-shipments

Pagination​

Pagination is managed using the following parameters:

  • datefrom: This parameter filters return shipments that were announced or had a status update after the specified date.
  • limit: This sets the maximum number of return shipments returned in each response. The default limit is 25.
  • next: This is a cursor that indicates the next return shipment to be queried.

Example

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

GET /v1/return-shipments/?datefrom=2025-01-01T00:00:00.000&limit=25&next=1

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

{
  "links": [
    {
      "href": "/v1/return-shipments/?datefrom=2024-01-01T00:00:00.000Z&limit=2&next=26",
      "rel": "next"
    }
  ],
  "resources": [
    {
      "returnShipmentId": "65cd4dca3a871e28d6937666",
      "createdAt": "2024-01-14T23:33:30.047Z",
      "returnPositionItems": [
        {
          "salesOrderId": "85bab3af-b08e-4a10-1234-8e8915f0453c",
          "salesOrderPositionItemId": "929d2939-8648-44b8-1234-ea88797a78f8"
        }
      ]
    }
  ]
}

Using the following link provided in the previous response

GET /v1/return-shipments/?datefrom=2024-01-01T00:00:00.000Z&limit=2&next=26

it will return the remaining 3 return-shipments. If there are no more return-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.

Return Shipment Id - The returnShipmentId is an internal identifier assigned by OTTO and is included in the response when you retrieve a return shipment using the carrier and trackingNumber.

ON THIS PAGE