# Shipments

## The Shipment resource

<table data-full-width="false"><thead><tr><th width="195">Property</th><th width="139">Type</th><th>Description</th></tr></thead><tbody><tr><td>created_at</td><td>ISO8601 datetime</td><td>When the shipment was created</td></tr><tr><td>delivered_at</td><td>ISO8601 datetime</td><td>When the shipment was delivered</td></tr><tr><td>delivery_status</td><td>String</td><td><p><strong>Information transmitted to the carrier</strong> - the shipment has been marked as shipped by Hive but no further statuses from the carrier yet</p><p><strong>In transit</strong> - the parcel is on the way to the carrier hub</p><p><strong>Out for delivery</strong> - the parcel has left the carrier hub and is in the process of being delivered</p><p><strong>Delivered</strong> - the parcel has been successfully delivered</p><p><strong>Returned to sender</strong> - the carrier initiated a return to the sender</p><p><strong>Action required</strong> - the parcel is going through an unconventional event (e.g. failed delivery attempt, shipment lost, address issues etc.)</p></td></tr><tr><td>id</td><td>Integer</td><td>The shipment's unique identifier in Hive</td></tr><tr><td>items</td><td>Array of <a href="#the-shipmentitem-resource">ShipmentItem</a> objects</td><td>Which line items this shipment includes</td></tr><tr><td>merchant_order_id</td><td>String</td><td>Related order's unique identifier provided by merchant</td></tr><tr><td>order_id</td><td>Integer</td><td>Related order's unique identifier in Hive</td></tr><tr><td>shipment_provider</td><td>String</td><td>Name of the shipment provider/carrier </td></tr><tr><td>shipped_at</td><td>ISO8601 datetime</td><td>When the shipment was shipped</td></tr><tr><td>status</td><td>String</td><td><p><strong>waiting_for_picking</strong> - initial status (normally shipment is created with this status during order import)</p><p><strong>on_hold</strong> - shipment is on hold for now, for example because shop is configured to start fulfillment in future or there are some issues (e.g. incorrect address or not enough inventory amount)</p><p><strong>picking_assigned</strong> - fulfillment center employee assigned themselves to pick this shipment's items</p><p><strong>in_picking</strong> - shipment items picking process has been started</p><p><strong>picked</strong> - shipment items have been picked and are ready for packing</p><p><strong>in_packing</strong> - shipment items packing process has been started</p><p><strong>packed</strong> - shipment items have been packed and are ready for shipping</p><p><strong>in_shipping</strong> - shipping process has been started</p><p><strong>shipped</strong> - a shipping label has been created for the shipment and it has left the packing station (and now the shipment is awaiting carrier pickup or is already picked up)</p><p><strong>cancelled</strong> - shipment is cancelled and will not be fulfilled, e.g. because the order was cancelled via Merchant API</p></td></tr><tr><td>tracking_number</td><td>String</td><td>Tracking number assigned by the shipment provider/carrier</td></tr><tr><td>tracking_url</td><td>String</td><td>Shipment provider website showing tracking information</td></tr><tr><td>updated_at</td><td>ISO8601 datetime</td><td>When the shipment was updated</td></tr></tbody></table>

## The ShipmentItem resource

<table><thead><tr><th width="182">Property</th><th width="248">Type</th><th>Description</th></tr></thead><tbody><tr><td>batches</td><td>Array of <a href="#the-shipmentitembatch-resource">ShipmentItemBatch</a> objects</td><td>Which batches were sent for this line item</td></tr><tr><td>id</td><td>Integer</td><td>The shipment item's unique identifier in Hive</td></tr><tr><td>merchant_item_id</td><td>String</td><td>The order line item identifier as provided by the merchant. Will be <code>null</code>for items added later (e.g. via add-on rules).</td></tr><tr><td>quantity</td><td>Integer</td><td>Number of SKUs in this line item</td></tr><tr><td>serial_numbers</td><td>Array of <a href="#the-shipmentitemserialnumber-resource">ShipmentItemSerialNumber</a> objects</td><td>Which serial numbers were sent for this line item</td></tr><tr><td>sku</td><td><a href="#the-shipmentitemsku-resource">A ShipmentItemSku object</a></td><td>SKU identifiers of this line item</td></tr></tbody></table>

## The ShipmentItemBatch resource

<table><thead><tr><th width="182">Property</th><th width="244">Type</th><th>Description</th></tr></thead><tbody><tr><td>expiry_date</td><td>ISO8601 date</td><td>Expiration date of the batch</td></tr><tr><td>name</td><td>String</td><td>Name of the batch</td></tr><tr><td>quantity</td><td>Integer</td><td>Number of items taken from this batch</td></tr><tr><td>tracking_code</td><td>String</td><td>Tracking code of the batch</td></tr></tbody></table>

## The ShipmentItemSerialNumber resource

| Property       | Type   | Description       |
| -------------- | ------ | ----------------- |
| serial\_number | String | The serial number |

## The ShipmentItemSku resource

| Property          | Type    | Description                                |
| ----------------- | ------- | ------------------------------------------ |
| id                | Integer | Hive unique identifier for the SKU         |
| merchant\_sku\_id | String  | SKU identifier as provided by the merchant |

## List all shipments

## Lists all shipments of an order&#x20;

<mark style="color:blue;">`GET`</mark> `https://app.hive.app/merchant_api/v1/shipments`

Returns shipments ordered by descending creation time.

#### Query Parameters

<table><thead><tr><th width="168">Name</th><th width="174">Type</th><th>Description</th></tr></thead><tbody><tr><td>order_id</td><td>Integer</td><td>The (Hive) ID of the order</td></tr><tr><td>created_at[lt]</td><td>ISO8601 datetime</td><td>Return results where the created_at field is less than this value.</td></tr><tr><td>created_at[lte]</td><td>ISO8601 datetime</td><td>Return results where the created_at field is less than or equal to this value.</td></tr><tr><td>created_at[gt]</td><td>ISO8601 datetime</td><td>Return results where the created_at field is greater than this value.</td></tr><tr><td>created_at[gte]</td><td>ISO8601 datetime</td><td>Return results where the created_at field is greater than or equal to this value.</td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK " %}

```json
{
  "data": [
    {
      "created_at": "2022-06-04T03:17:25.533+02:00",
      "delivered_at": "2022-06-06T22:17:46.000+02:00",
      "delivery_status": "Delivered",
      "id": 170,
      "items": [
        {
          "batches": [
            {
              "expiry_date": "2023-06-04",
              "name": "Batch 1",
              "quantity": 1,
              "tracking_code": "ABC123"
            }
          ],
          "id": 201,
          "merchant_item_id": "QWERTY0987",
          "quantity": 1,
          "serial_numbers": [
            {
              "serial_number": "1234567890"
            }
          ],
          "sku": {
            "id": 123000,
            "merchant_sku_id": "ABC123"
          }
        },
        {
          "batches": [],
          "id": 202,
          "merchant_item_id": "QWERTY6543",
          "quantity": 2,
          "serial_numbers": [],
          "sku": {
            "id": 123001,
            "merchant_sku_id": "DEF456"
          }
        }
      ],
      "merchant_order_id": "20220604-383",
      "order_id": 575,
      "shipment_provider": "DHL",
      "shipped_at": "2022-06-04T07:53:20.511+02:00",
      "status": "shipped",
      "tracking_number": "CR123456789DE",
      "tracking_url": "https://www.dhl.de/en/privatkunden/dhl-sendungsverfolgung.html?piececode=CR123456789DE",
      "updated_at": "2022-07-22T16:53:31.388+02:00"
    }
  ],
  "pagination": {
    "current_page": 1,
    "item_count": 2,
    "page_count": 1,
    "items_per_page": 20
  }
}
```

{% endtab %}

{% tab title="404: Not Found There was no order matching the given ID" %}

```json
{
  "success": false,
  "errors": [
    "record not found"
  ]
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.hive.app/reference/api-reference/shipments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.