---
title: "Retrieve returnShipments."
method: GET
path: "/v1/return-shipments"
tags: ["ReturnShipments V1"]
---

# Retrieve returnShipments.

`GET /v1/return-shipments`

This endpoint can be used to retrieve the returned shipments for a given authorized partner.

## Query parameters

- `datefrom` string, date-time, required
- `limit` integer
- `next` string

## Response `200`

OK

- ReturnShipmentListReturnShipmentsV1
  - `links` LinkReturnShipmentsV1[] — Contains one single link, which can be used as pointer for Cursor-based pagination.
    - `href` string — The url of the link
    - `rel` string — The relation type of the link. See also https://www.iana.org/assignments/link-relations/link-relations.xhtml. The relation type 'next' is used for paging. The relation type 'self' refers to the url of the ressource
  - `resources` ReturnShipmentReturnShipmentsV1[]
    - `returnShipmentId` string, required — Internal returnShipment identifier assigned by OTTO Market.
    - `createdAt` string, required
    - `trackingKey` TrackingKeyReturnShipmentsV1, required
      - `carrier` 'DHL' | 'GLS' | 'HERMES' | 'HES', required — The carrier of the returnShipment.
      - `trackingNumber` string, required — The tracking number assigned by the carrier.
    - `returnPositionItems` ReturnPositionItemReturnShipmentsV1[], required — The position items included in the returnShipment.
      - `salesOrderId` string, uuid, required — The ID of the sales order from the OTTO Market, as defined in the Order API.
      - `salesOrderPositionItemId` string, uuid, required — The ID of a position item of the sales order from the OTTO Market, as defined in the Order API.
    - `states` ReturnShipmentStateReturnShipmentsV1[] — The history of tracking states of the returnShipment
      - `state` 'ANNOUNCED' | 'ON_THE_WAY' | 'DELIVERED', required — The tracking state of the returnShipment.
      - `occurredOn` string, required
      - `statusText` string — Optional information from the carrier detailing the tracking state.

## Other responses

- `400` — BadRequest
- `401` — Unauthorized
- `500` — Internal Server Error

---

[API](https://skmtc.dev/otto/apis/otto-market-api.md) · [All operations](https://skmtc.dev/otto/apis/otto-market-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/otto/otto-market-api/revisions/b1bc133112bd/schema)