# Returns

Return requests and the steps that take them from request to completion

Section: api. Audience: public. Updated: 2026-10-10.

---
Return requests and the steps that take them from request to completion.

4 operations, generated from the [OpenAPI file](/openapi/horizon-api.yaml). Authentication and the base URL are described in the [API overview](/api/).

## <span class="nh-method nh-method-get" id="returns_requests_list">GET</span> `/api/returns/requests/`

List returns

Operation ID `returns_requests_list`. Authentication: `ApiKeyAuth`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `carrier` | query | string | No |  |
| `channel` | query | string | No |  |
| `country` | query | string | No |  |
| `page` | query | integer | No | A page number within the paginated result set. |
| `page_size` | query | integer | No | Number of results to return per page. |
| `q` | query | string | No | Search RMA number, order, customer, tracking number, SKU or product name. |
| `reason` | query | string | No |  |
| `status` | query | string | No | A return status, or `open` / `closed`. |

#### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` |  | [`PaginatedReturnRequestList`](#schema-PaginatedReturnRequestList) (`application/json`) |

#### Example

```bash
curl "https://api.horizonlogistics.eu/api/returns/requests/" \
  -H "Authorization: Api-Key $HORIZON_API_KEY"
```

## <span class="nh-method nh-method-get" id="returns_requests_export_retrieve">GET</span> `/api/returns/requests/export/`

Export returns as CSV

Operation ID `returns_requests_export_retrieve`. Authentication: `ApiKeyAuth`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `carrier` | query | string | No |  |
| `channel` | query | string | No |  |
| `country` | query | string | No |  |
| `q` | query | string | No | Search RMA number, order, customer, tracking number, SKU or product name. |
| `reason` | query | string | No |  |
| `status` | query | string | No | A return status, or `open` / `closed`. |

#### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` |  | string (`text/csv`) |

#### Example

```bash
curl "https://api.horizonlogistics.eu/api/returns/requests/export/" \
  -H "Authorization: Api-Key $HORIZON_API_KEY"
```

## <span class="nh-method nh-method-get" id="returns_requests_retrieve">GET</span> `/api/returns/requests/{id}/`

Retrieve a return

Operation ID `returns_requests_retrieve`. Authentication: `ApiKeyAuth`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | Yes |  |

#### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` |  | [`ReturnRequest`](#schema-ReturnRequest) (`application/json`) |

#### Example

```bash
curl "https://api.horizonlogistics.eu/api/returns/requests/{id}/" \
  -H "Authorization: Api-Key $HORIZON_API_KEY"
```

## <span class="nh-method nh-method-get" id="returns_requests_label_retrieve">GET</span> `/api/returns/requests/{id}/label/`

Download a return label

Operation ID `returns_requests_label_retrieve`. Authentication: `ApiKeyAuth`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | Yes |  |

#### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` |  | string (binary) (`application/pdf`, `image/png`, `image/gif`, `application/octet-stream`) |

#### Example

```bash
curl "https://api.horizonlogistics.eu/api/returns/requests/{id}/label/" \
  -H "Authorization: Api-Key $HORIZON_API_KEY"
```

## Schemas

The objects the operations above send and receive. Fields of a nested object are listed under their parent (`address.city`, `lines[].sku`); a nested named object links to its own entry.

### <span class="nh-anchor" id="schema-PaginatedReturnRequestList">PaginatedReturnRequestList</span>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `count` | integer | Yes |  |
| `next` | string (uri), nullable | No |  |
| `previous` | string (uri), nullable | No |  |
| `results` | array of [`ReturnRequest`](#schema-ReturnRequest) | Yes |  |

### <span class="nh-anchor" id="schema-ReturnRequest">ReturnRequest</span>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | Yes | Read-only. |
| `rma_number` | string | Yes | Read-only. |
| `order` | integer, nullable | No |  |
| `order_name` | any | Yes | Read-only. |
| `customer_name` | string | No | Max length 200. |
| `customer_email` | one of string (email), string | No |  |
| `country` | string | No | Max length 2. |
| `channel` | string | No | Max length 80. |
| `status` | string (enum) | Yes | One of: `REQUESTED`, `APPROVED`, `IN_TRANSIT`, `RECEIVED`, `COMPLETED`, `REJECTED`, `CANCELLED`. Read-only. |
| `source` | string (enum) | Yes | `MANUAL` - Manual; `PORTAL` - Portal; `API` - API; `SHOPIFY` - Shopify. Read-only. |
| `reason` | string (enum), may be blank | No | One of: `too_small`, `too_large`, `wrong_color`, `damaged`, `not_as_described`, `wrong_item`, `changed_mind`, `arrived_late`, `quality`, `other`. |
| `customer_note` | string | No |  |
| `resolution` | string (enum) | Yes | One of: `REFUND`, `STORE_CREDIT`, `EXCHANGE`, `KEEP_IT`. Read-only. |
| `refund_amount` | string (decimal), nullable | Yes | Pattern `^-?\d{0,8}(?:\.\d{0,2})?$`. Read-only. |
| `currency` | string | No | Max length 3. |
| `tags` | any | Yes | Read-only. |
| `fee_amount` | string (decimal), nullable | Yes | Pattern `^-?\d{0,6}(?:\.\d{0,2})?$`. Read-only. |
| `requested_resolution` | string (enum) | Yes | One of: `REFUND`, `STORE_CREDIT`, `EXCHANGE`, `KEEP_IT`. Read-only. |
| `credit_amount` | string (decimal), nullable | Yes | Pattern `^-?\d{0,8}(?:\.\d{0,2})?$`. Read-only. |
| `exchange_reference` | string | Yes | Read-only. |
| `risk_score` | integer, nullable | Yes | Read-only. |
| `risk_factors` | any | Yes | Read-only. |
| `co2e_estimate_kg` | any | Yes | Read-only. |
| `has_return_label` | any | Yes | Read-only. |
| `exchange_draft` | any | Yes | Read-only. |
| `store_credit_code` | any | Yes | Read-only. |
| `photos` | any | Yes | Read-only. |
| `suggested_refund` | any | Yes | Read-only. |
| `carrier` | string | No | Max length 64. |
| `shipping_method` | string | No | Max length 64. |
| `tracking_number` | string | No | Max length 64. |
| `label_cost` | string (decimal), nullable | No | Pattern `^-?\d{0,6}(?:\.\d{0,2})?$`. |
| `label_currency` | string | Yes | Read-only. |
| `shopify_return` | any | Yes | Read-only. |
| `shopify_money` | any | Yes | Read-only. |
| `adobe_writeback` | any | Yes | Read-only. |
| `requested_at` | string (date-time) | Yes | Read-only. |
| `approved_at` | string (date-time), nullable | Yes | Read-only. |
| `received_at` | string (date-time), nullable | Yes | Read-only. |
| `completed_at` | string (date-time), nullable | Yes | Read-only. |
| `closed_at` | string (date-time), nullable | Yes | Read-only. |
| `decision_note` | string | Yes | Read-only. |
| `warehouse_receipt` | integer, nullable | Yes | Read-only. |
| `warehouse_receipt_number` | any | Yes | Read-only. |
| `events` | any | Yes | Read-only. |
| `total_value` | string (decimal) | Yes | Pattern `^-?\d{0,10}(?:\.\d{0,2})?$`. Read-only. |
| `lines` | array of [`ReturnRequestLine`](#schema-ReturnRequestLine) | Yes |  |
| `created_at` | string (date-time) | Yes | Read-only. |
| `updated_at` | string (date-time) | Yes | Read-only. |

### <span class="nh-anchor" id="schema-ReturnRequestLine">ReturnRequestLine</span>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | Yes | Read-only. |
| `product` | integer, nullable | No |  |
| `sku` | string | No | Max length 64. |
| `name` | string | Yes | Max length 200. |
| `quantity` | integer | Yes | Min 0, max 2147483647. |
| `unit_price` | string (decimal), nullable | No | Pattern `^-?\d{0,8}(?:\.\d{0,2})?$`. |
| `reason` | string (enum), may be blank | No | One of: `too_small`, `too_large`, `wrong_color`, `damaged`, `not_as_described`, `wrong_item`, `changed_mind`, `arrived_late`, `quality`, `other`. |
| `customer_stated_unit_price` | string (decimal), nullable | Yes | Pattern `^-?\d{0,8}(?:\.\d{0,2})?$`. Read-only. |
| `passport_count` | any | Yes | Read-only. |