# List shipments

Returns all shipments across all sales channels belonging to the authenticated merchant.

See the Pagination section in the API overview above for details on how pagination works.

Endpoint: GET /shipments
Version: 2.0.0
Security: BearerAuth

## Query parameters:

  - `limit` (integer)
    Number of items to return per page (for pagination)

  - `order_id[in]` (array)
    Filter results by one or more Hive order IDs

  - `merchant_order_id[in]` (array)
    Filter results by one or more merchant order IDs

## Response 200 fields (application/json):

  - `data` (array)

  - `data.created_at` (string)
    When the shipment was created

  - `data.delivered_at` (string,null)
    When the shipment was delivered

  - `data.delivery_status` (any)

  - `data.id` (integer, required)
    The shipment's unique identifier in Hive

  - `data.items` (array, required)
    Which line items this shipment includes

  - `data.items.batches` (array)
    Which batches were sent for this line item

  - `data.items.batches.expiry_date` (string, required)
    Expiration date of the batch

  - `data.items.batches.name` (string, required)
    Name of the batch

  - `data.items.batches.quantity` (integer, required)
    Number of items taken from this batch

  - `data.items.batches.tracking_code` (string, required)
    Tracking code of the batch

  - `data.items.id` (integer, required)
    The shipment item's unique identifier in Hive

  - `data.items.merchant_item_id` (string,null)
    The order line item identifier as provided by the merchant. Will be null for items added later (e.g. via add-on rules).

  - `data.items.quantity` (integer, required)
    Number of SKUs in this line item

  - `data.items.serial_numbers` (array)
    Which serial numbers were sent for this line item

  - `data.items.serial_numbers.serial_number` (string, required)
    The serial number

  - `data.items.sku` (object, required)

  - `data.items.sku.id` (integer, required)
    Hive unique identifier for the SKU

  - `data.items.sku.sku_code` (string, required)
    SKU identifier as provided by the merchant

  - `data.merchant_order_id` (string)
    Related order's unique identifier provided by merchant

  - `data.order_id` (integer, required)
    Related order's unique identifier in Hive

  - `data.sales_channel_id` (integer, required)
    The ID of the sales channel this shipment belongs to

  - `data.shipment_provider` (string,null)
    Name of the shipment provider/carrier

  - `data.shipped_at` (string,null)
    When the shipment was shipped

  - `data.shipping_method` (string,null)

  - `data.status` (string, required)
    Status of the shipment. Possible values:
- cancelled: Shipment cancelled and will not be fulfilled
- in_packing: Packing process started
- in_picking: Picking process started
- in_shipping: Shipping process started
- on_hold: On hold (e.g. future fulfillment, address issues, insufficient inventory)
- packed: Items packed and ready for shipping
- picked: Items picked and ready for packing
- picking_assigned: Employee assigned to pick items
- shipped: Shipping label created and left packing station
- waiting_for_picking: Initial status, awaiting picking
    Enum: "cancelled", "in_packing", "in_picking", "in_shipping", "on_hold", "packed", "picked", "picking_assigned", "shipped", "waiting_for_picking"

  - `data.tracking_number` (string,null)
    Tracking number assigned by the shipment provider/carrier

  - `data.tracking_url` (string,null)
    Shipment provider website showing tracking information

  - `data.updated_at` (string)
    When the shipment was updated

  - `pagination` (object)

  - `pagination.first_page_url` (string)
    URL to fetch the first page of results

  - `pagination.limit` (integer)
    Number of items returned per page

  - `pagination.next_page_url` (string,null)
    URL to fetch the next page of results. If null, there are no more results.

## Response 401 fields (application/json):

  - `errors` (any, required)
    Error information. Can be:
- Object with field names as keys and error arrays as values (for validation errors)
- Array of error objects with message, code, and optional metadata
- Array of strings (for simple error messages)

  - `success` (boolean)
    Indicates if the request was successful

  - `title` (string)
    A brief, human-readable message about the error

  - `status` (integer)
    HTTP status code

## Response 403 fields (application/json):

  - `errors` (any, required)
    Error information. Can be:
- Object with field names as keys and error arrays as values (for validation errors)
- Array of error objects with message, code, and optional metadata
- Array of strings (for simple error messages)

  - `success` (boolean)
    Indicates if the request was successful

  - `title` (string)
    A brief, human-readable message about the error

  - `status` (integer)
    HTTP status code

## Response 429 fields (application/json):

  - `errors` (any, required)
    Error information. Can be:
- Object with field names as keys and error arrays as values (for validation errors)
- Array of error objects with message, code, and optional metadata
- Array of strings (for simple error messages)

  - `success` (boolean)
    Indicates if the request was successful

  - `title` (string)
    A brief, human-readable message about the error

  - `status` (integer)
    HTTP status code