# Get Shipments

> `GET /inboxes/{inbox_id}/shipments`

Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/listshipments/

URL: `GET https://api.earthclassmail.com/v1/inboxes/{inbox_id}/shipments`

Returns shipments for the given inbox. Supports filtering by status and other criteria.

## Authorization

Send your API key in the `x-api-key` header.

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `inbox_id` | path | yes | string |  |
| `page` | query | no | integer | The desired page from the result set. Defaults to 1. |
| `per_page` | query | no | integer | The number of items per page. Defaults to 100. |
| `operation_status` | query | no | string | Filter by shipment status. Comma-separated list. Allowed values: pending, in_progress, complete, problem. |
| `piece_id` | query | no | string | Filter by piece IDs. Comma-separated list of integers. |
| `shipping_address_id` | query | no | string | Filter by shipping address IDs. Comma-separated list of integers. |
| `carrier` | query | no | string | Filter by carrier. Comma-separated list of strings. |
| `class` | query | no | string | Filter by carrier service class. Comma-separated list of strings. |
| `is_insured` | query | no | boolean | Filter by insurance status. |
| `signature_on_delivery` | query | no | boolean | Filter by signature requirement. |
| `country_abbreviations` | query | no | string | Filter by destination country. Comma-separated list of ISO 3166-1 alpha-2 country codes. |
| `postal_codes` | query | no | string | Filter by destination postal code. Comma-separated list of strings. |
| `tracking_number` | query | no | string | Filter by tracking number. Comma-separated list of strings. |
| `sort_by` | query | no | string | The field to sort results by. Allowed values: id, requested_at, shipped_at, ship_after, item_count. |
| `sort_direction` | query | no | string | The direction to sort results. Allowed values: asc, desc. |

## Responses

### 200

Success

Content type: `application/json`

- `total` (integer): Total number of items across all pages.
- `per_page` (integer): Number of items per page.
- `current_page` (integer): The current page number (1-based).
- `last_page` (integer): The last available page number.
- `from` (integer): The index of the first item on this page (1-based).
- `to` (integer): The index of the last item on this page (1-based).
- `data` (array of `Shipment`)

Example:

```json
{
  "current_page": 1,
  "data": [
    {
      "id": 123456,
      "created_at": "2024-02-01T10:00:00Z",
      "updated_at": "2024-02-02T10:00:20Z",
      "operation_action": "ship",
      "operation_status": "complete",
      "tags": [],
      "aes_itn": null,
      "completed_at": "2024-07-03T00:00:00Z",
      "contents_type": null,
      "custom_items": [],
      "customs_description": null,
      "declared_value_in_cents": null,
      "estimated_shipped_at": "2024-07-02T10:00:00Z",
      "is_insured": false,
      "is_shared": false,
      "items": [
        {
          "customs_description": null,
          "declared_value_in_cents": null,
          "has_complete_scan": true,
          "piece_id": 123456
        }
      ],
      "owner_user_id": "123456",
      "rate": {
        "carrier_service": "Express",
        "carrier_type": "USPS - Express",
        "created_at": "2024-04-01T12:00:00Z",
        "expired_at": "2024-04-04T12:00:00Z",
        "id": null,
        "price_in_cents": 3000,
        "tracking_available": false
      },
      "rate_id": null,
      "return_address": {
        "address_line_1": "9450 SW Gemini Dr",
        "address_line_2": null,
        "addressee": "John Smith PMB #123456",
        "country": "United States",
        "country_abbreviation": "US",
        "locality": "Beaverton",
        "postal_code": "97008-7105",
        "region": "Oregon",
        "region_abbreviation": "OR"
      },
      "ship_after": "2024-07-02T10:00:00Z",
      "shipped_at": "2024-07-02T00:00:00Z",
      "shipping_address": {
        "id": 123456,
        "created_at": "2022-10-10T10:00:00Z",
        "updated_at": "2022-10-10T10:00:00Z",
        "address_line_1": "1004 S Mt Olive St",
        "address_line_2": "",
        "addressee": "Molly Smith",
        "company": null,
        "country": "United States",
        "country_abbreviation": "US",
        "delivery_confidence_percent": null,
        "inbox_id": 123456,
        "is_authorized": null,
        "locality": "Siloam Springs",
        "phone": "(111) 111-1111",
        "postal_code": "11111",
        "region": "Arizona",
        "region_abbreviation": "AZ",
        "requires_hs_tariff_codes": false,
        "requires_itn": false,
        "tags": [
          "domestic"
        ]
      },
      "shipping_address_id": 123456,
      "shipping_comment": null,
      "signature_on_delivery": false,
      "tracking_number": "00000000000000000000"
    }
  ],
  "from": 1,
  "to": 1,
  "last_page": 1,
  "per_page": 100,
  "total": 1
}
```

### 401

The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access.

Content type: `application/json`

Type: `Error`

Example — Missing API key:

```json
{
  "error": {
    "code": 401,
    "message": "The request does not include a valid access token. Please provide a valid access token.",
    "type": "Authorization"
  }
}
```

Example — Invalid API key:

```json
{
  "error": {
    "code": 401,
    "message": "x-api-key: x-api-key is invalid",
    "type": "REST"
  }
}
```

Example — No access to resource:

```json
{
  "error": {
    "code": 401,
    "message": "User does not have access to requested resource.",
    "type": "Authorization"
  }
}
```

## Schemas

### Error

Error envelope returned with 4xx and 5xx responses.

- `error` (object)
  - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500.
  - `message` (string): Human-readable description of the error.
  - `type` (string): The kind of error, for example `Authorization` or `REST`.
  - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input.

### Shipment

- `id` (integer)
- `created_at` (string<date-time>)
- `updated_at` (string<date-time>)
- `operation_action` (string)
- `operation_status` (string)
- `tags` (array of string)
- `shipping_address_id` (integer)
- `shipping_address` (`ShippingAddress`)
- `rate_id` (string or null)
- `shipping_comment` (string or null)
- `rate` (`ShippingRate`)
- `aes_itn` (string or null)
- `ship_after` (string<date-time> or null)
- `signature_on_delivery` (boolean)
- `items` (array of `ShipmentItem`)
- `custom_items` (array of `ShipmentCustomItem`)
- `is_insured` (boolean)
- `is_shared` (boolean)
- `tracking_number` (string or null)
- `declared_value_in_cents` (integer or null)
- `customs_description` (string or null)
- `delivered_at` (string<date-time> or null)
- `shipped_at` (string<date-time> or null)
- `estimated_shipped_at` (string<date-time> or null)
- `completed_at` (string<date-time> or null)
- `return_address` (`ShipmentReturnAddress`)
- `delete_scans` (boolean)
- `pieces` (array of `Piece`)
- `contents_type` (string or null)
- `owner_user_id` (string)

### Piece

- `id` (integer)
- `created_at` (string<date-time>)
- `updated_at` (string<date-time>)
- `inbox_id` (integer)
- `barcode` (string)
- `license_plate` (integer)
- `recipient` (`PieceRecipient`)
- `mailbox_folder_id` (integer)
- `tags` (array of string)
- `attributes` (array of string)
- `sender` (`PieceSender` or null)
- `received_at` (string<date-time>)
- `date_arrived_in_mailbox` (string<date-time>)
- `weight_in_ounces` (number)
- `facility_name` (string)
- `page_count_estimate` (integer)
- `page_count_actual` (integer or null)
- `height_in_inches` (number)
- `depth_in_inches` (number)
- `length_in_inches` (number)
- `carrier` (`PieceCarrier`)
- `media` (array of `PieceMedia`)
- `ocr_data` (string)
- `envelope_ocr_data` (string)
- `piece_type` (string)
- `piece_sub_type` (string)
- `insights` (array of `PieceInsight`)
- `user_defined_tags` (array of `Tag`)
- `matched_by` (array of string)
- `operation_action` (string or null)
- `end_user_operation_status` (string or null)
- `storage_fee_amount_in_cents` (integer)
- `can_delete_scan_only` (boolean)
- `available_actions` (array of string)
- `name` (string)
- `detected_checks_count` (integer or null)
- `recipient_type` (string)

### ShipmentCustomItem

- `declared_value_in_cents` (integer)
- `description` (string)
- `hs_tariff_code` (string)

### ShipmentItem

- `piece_id` (integer)
- `declared_value_in_cents` (integer or null)
- `customs_description` (string or null)
- `has_complete_scan` (boolean)

### ShipmentReturnAddress

- `addressee` (string)
- `address_line_1` (string)
- `address_line_2` (string or null)
- `locality` (string)
- `region_abbreviation` (string)
- `region` (string)
- `country_abbreviation` (string)
- `country` (string)
- `postal_code` (string)

### ShippingAddress

- `id` (integer)
- `created_at` (string<date-time>)
- `updated_at` (string<date-time>)
- `addressee` (string)
- `address_line_1` (string)
- `address_line_2` (string)
- `locality` (string)
- `region_abbreviation` (string)
- `region` (string)
- `country_abbreviation` (string)
- `country` (string)
- `postal_code` (string)
- `phone` (string)
- `tags` (array of string)
- `delivery_confidence_percent` (number or null)
- `inbox_id` (integer or null)
- `company` (string or null)
- `is_authorized` (boolean or null)
- `requires_hs_tariff_codes` (boolean or null)
- `requires_itn` (boolean or null)

### ShippingRate

- `id` (string or null)
- `carrier_type` (string)
- `carrier_service` (string)
- `price_in_cents` (integer)
- `created_at` (string<date-time>)
- `expired_at` (string<date-time>)
- `tracking_available` (boolean)

### PieceCarrier

- `name` (string)
- `class` (string)

### PieceInsight

- `type` (string)
- `confidence` (number)

### PieceMedia

- `id` (string)
- `url` (string)
- `content_type` (string)
- `tags` (array of string)
- `url_valid_until` (string<date-time>)
- `file_size_in_bytes` (integer)
- `piece_id` (integer or null)
- `scan_id` (integer or null)
- `page_count` (integer or null)
- `sequence_number` (integer or null)

### PieceRecipient

- `id` (integer)
- `name` (string)
- `inbox_id` (integer or null)
- `type` (string)

### PieceSender

- `name` (string)
- `address` (string)

### Tag

- `id` (integer)
- `created_at` (string<date-time>)
- `updated_at` (string<date-time>)
- `label` (string)
- `parent_tag_id` (integer or null)
- `piece_counts` (integer or null)