# Shipments

Shipments bought through Horizon and their tracking events

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

---
Shipments bought through Horizon and their tracking events.

5 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="shipping_v1_shipments_list">GET</span> `/api/shipping/v1/shipments/`

List shipments

Operation ID `shipping_v1_shipments_list`. Authentication: `ApiKeyAuth`.

#### Responses

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

#### Example

```bash
curl "https://api.horizonlogistics.eu/api/shipping/v1/shipments/" \
  -H "Authorization: Api-Key $HORIZON_API_KEY"
```

## <span class="nh-method nh-method-get" id="shipping_v1_shipments_retrieve">GET</span> `/api/shipping/v1/shipments/{shipment_id}/`

Retrieve a shipment

Operation ID `shipping_v1_shipments_retrieve`. Authentication: `ApiKeyAuth`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shipment_id` | path | string | Yes |  |

#### Responses

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

#### Example

```bash
curl "https://api.horizonlogistics.eu/api/shipping/v1/shipments/{shipment_id}/" \
  -H "Authorization: Api-Key $HORIZON_API_KEY"
```

## <span class="nh-method nh-method-get" id="shipping_v1_shipments_label_retrieve">GET</span> `/api/shipping/v1/shipments/{shipment_id}/label/`

Retrieve a shipment's label

Operation ID `shipping_v1_shipments_label_retrieve`. Authentication: `ApiKeyAuth`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shipment_id` | path | string | Yes |  |

#### Responses

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

#### Example

```bash
curl "https://api.horizonlogistics.eu/api/shipping/v1/shipments/{shipment_id}/label/" \
  -H "Authorization: Api-Key $HORIZON_API_KEY"
```

## <span class="nh-method nh-method-get" id="shipping_v1_tracking_events_list">GET</span> `/api/shipping/v1/tracking-events/`

List tracking events

Operation ID `shipping_v1_tracking_events_list`. Authentication: `ApiKeyAuth`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `carrier` | query | string | No |  |
| `exception_code` | query | string | No |  |
| `package` | query | integer | No | Package id. |
| `shipment` | query | string | No | Shipment id. |
| `status` | query | string | No | Normalised tracking status. |

#### Responses

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

#### Example

```bash
curl "https://api.horizonlogistics.eu/api/shipping/v1/tracking-events/" \
  -H "Authorization: Api-Key $HORIZON_API_KEY"
```

## <span class="nh-method nh-method-get" id="shipping_v1_tracking_events_retrieve">GET</span> `/api/shipping/v1/tracking-events/{id}/`

Retrieve a tracking event

Operation ID `shipping_v1_tracking_events_retrieve`. Authentication: `ApiKeyAuth`.

#### Parameters

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

#### Responses

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

#### Example

```bash
curl "https://api.horizonlogistics.eu/api/shipping/v1/tracking-events/{id}/" \
  -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-Address">Address</span>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | Yes | Read-only. |
| `location_name` | string | Yes | Max length 255. |
| `line1` | string | Yes | Max length 255. |
| `line2` | string | No | Max length 255. |
| `line3` | string | No | Max length 255. |
| `city` | string | Yes | Max length 100. |
| `province` | string | No | Max length 100. |
| `postcode` | string | Yes | Max length 20. |
| `country_code` | string | Yes | Max length 2. |
| `is_residential` | boolean | No |  |

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | Yes | Read-only. |
| `length_cm` | string (decimal) | Yes | Pattern `^-?\d{0,6}(?:\.\d{0,2})?$`. |
| `width_cm` | string (decimal) | Yes | Pattern `^-?\d{0,6}(?:\.\d{0,2})?$`. |
| `height_cm` | string (decimal) | Yes | Pattern `^-?\d{0,6}(?:\.\d{0,2})?$`. |
| `weight_kg` | string (decimal) | Yes | Pattern `^-?\d{0,5}(?:\.\d{0,3})?$`. |
| `cost` | string (decimal) | No | Pattern `^-?\d{0,8}(?:\.\d{0,2})?$`. |
| `quantity` | integer | No | Min 0, max 2147483647. |
| `description` | string | No | Max length 50. |
| `tracking_code` | string | No | Max length 128. |
| `status` | string (enum) | Yes | One of: `not_received`, `with_carrier`, `delivered`. |
| `passport_id` | any | Yes | Read-only. |
| `rated_base_cost` | string (decimal), nullable | No | Pattern `^-?\d{0,10}(?:\.\d{0,2})?$`. |
| `rated_dim_weight_kg` | string (decimal), nullable | No | Pattern `^-?\d{0,5}(?:\.\d{0,3})?$`. |
| `rated_billable_weight_kg` | string (decimal), nullable | No | Pattern `^-?\d{0,5}(?:\.\d{0,3})?$`. |
| `rated_zone` | string | No | Max length 16. |
| `label_generated_ts` | string (date-time), nullable | No |  |
| `label_format` | string (enum), may be blank | No | One of: `ZPL`, `PDF`, `PNG`. |
| `delivery_attempts` | integer | No | Min 0, max 2147483647. |
| `delivered_ts` | string (date-time), nullable | No |  |
| `delivery_location_type` | string (enum), may be blank | No | One of: `DOOR`, `LCK`, `PUP`, `SAFE`. |
| `pod_signature_uri` | one of string (uri), string | No |  |
| `first_attempt_success_flag` | boolean, nullable | No |  |

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | Yes | Read-only. |
| `name` | string, nullable | No | Max length 255. |
| `phone_number` | string, nullable | No | Max length 20. |
| `phone_number_extension` | string, nullable | No | Max length 10. |
| `email` | one of string (email), string, nullable | No |  |
| `address` | [`Address`](#schema-Address) | Yes |  |
| `alternate_address` | [`Address`](#schema-Address), nullable | Yes |  |

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `shipment_id` | string | Yes | Max length 64. |
| `carrier` | string | Yes | Max length 32. |
| `service_code` | string | Yes | Max length 64. |
| `tracking_number` | string | Yes | Max length 128. |
| `status` | string (enum) | Yes | One of: `schedule_pickup`, `pickup_scheduled`, `waiting_for_dropoff`, `fulfilling`, `action_required`, `completed`. |
| `status_info` | any | No |  |
| `created_at` | string (date-time) | Yes | Read-only. |
| `ship_from` | [`ShipmentContact`](#schema-ShipmentContact) | Yes | Read-only. |
| `ship_to` | [`ShipmentContact`](#schema-ShipmentContact) | Yes | Read-only. |
| `packages` | array of [`Package`](#schema-Package) | Yes | Read-only. |
| `selection_reason_code` | string (enum), may be blank | No | One of: `COST`, `SLA`, `CO2`, `CAP`, `MAN`. |
| `alternative_carriers_considered` | any | No |  |
| `manifest_id` | string | No | Max length 64. |
| `tendered_to_carrier_ts` | string (date-time), nullable | No |  |
| `predicted_sla_miss_prob` | string (decimal), nullable | No | Pattern `^-?\d{0,1}(?:\.\d{0,4})?$`. |
| `sla_status` | string (enum) | No | `MET` - Met; `MISS` - Missed; `PND` - Pending. |

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `shipment_id` | string | Yes |  |
| `tracking_number` | string | Yes |  |
| `format` | string | Yes | The carrier's label format, such as PDF, GIF or ZPL. |
| `image_b64` | string | Yes | The label file, base64-encoded. |

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `shipment_id` | string | Yes | Max length 64. |
| `carrier` | string | Yes | Max length 32. |
| `service_code` | string | Yes | Max length 64. |
| `tracking_number` | string | Yes | Max length 128. |
| `status` | string (enum) | Yes | One of: `schedule_pickup`, `pickup_scheduled`, `waiting_for_dropoff`, `fulfilling`, `action_required`, `completed`. |
| `status_info` | any | No |  |
| `created_at` | string (date-time) | Yes | Read-only. |
| `package_count` | integer | Yes | Read-only. |
| `ship_from` | [`ShipmentContact`](#schema-ShipmentContact) | Yes | Read-only. |
| `ship_to` | [`ShipmentContact`](#schema-ShipmentContact) | Yes | Read-only. |
| `selection_reason_code` | string (enum), may be blank | No | One of: `COST`, `SLA`, `CO2`, `CAP`, `MAN`. |
| `alternative_carriers_considered` | any | No |  |
| `manifest_id` | string | No | Max length 64. |
| `tendered_to_carrier_ts` | string (date-time), nullable | No |  |
| `predicted_sla_miss_prob` | string (decimal), nullable | No | Pattern `^-?\d{0,1}(?:\.\d{0,4})?$`. |
| `sla_status` | string (enum) | No | `MET` - Met; `MISS` - Missed; `PND` - Pending. |

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | Yes | Read-only. |
| `package` | integer | Yes |  |
| `package_tracking_code` | string | Yes | Read-only. |
| `owner` | integer | Yes | Read-only. |
| `scan_event` | any | No |  |
| `scan_timestamp` | string (date-time) | Yes |  |
| `scan_location_code` | string | No | Max length 64. |
| `scan_status_code` | string | No | Max length 32. |
| `nh_normalized_status` | string (enum) | Yes | One of: `PICKED_UP`, `HUB`, `OUT`, `DEL`, `EXC`, `RTS`, `TENDER`, `LABEL`. |
| `hub_dwell_minutes` | integer, nullable | No | Min 0, max 2147483647. |
| `geo_breadcrumb` | any | No |  |
| `exception_code` | string | No | Max length 32. |
| `idempotency_key` | string | Yes | Default: `""`. Read-only. |
| `created_at` | string (date-time) | Yes | Read-only. |
| `updated_at` | string (date-time) | Yes | Read-only. |