# Create Shipment

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

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

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

Creates a shipment request for one or more pieces using a rate previously retrieved with getShippingRates. The shipping address is the one the rate was requested for.

The rate must not be expired, and `items` must list the same pieces the rate was requested for. All pieces must be stored at the same facility and must not be junk mail or have another operation in progress. Declared values and customs details given here replace the ones from the rate request.

International shipments need customs information (see getShippingRates). If it is missing, the request fails with `400`.

## Authorization

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

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `inbox_id` | path | yes | string |  |

## Request body

Required.

Content type: `application/json`

Type: `CreateShipmentRequest`

Example — Create non-insured domestic shipment:

```json
{
  "rate_id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342",
  "items": [
    {
      "piece_id": 1234000
    },
    {
      "piece_id": 1234001
    }
  ]
}
```

Example — Create insured domestic shipment:

```json
{
  "rate_id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342",
  "items": [
    {
      "piece_id": 123456789
    }
  ],
  "is_insured": true,
  "declared_value_in_cents": 100000
}
```

Example — Create international shipment:

```json
{
  "rate_id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342",
  "items": [
    {
      "piece_id": 120000
    }
  ],
  "contents_type": "Merchandise",
  "custom_items": [
    {
      "description": "men's cotton trousers",
      "declared_value_in_cents": 20000,
      "hs_tariff_code": "620520"
    }
  ]
}
```

## Responses

### 200

Success

Content type: `application/json`

Type: `Shipment`

Example — Create non-insured domestic shipment:

```json
{
  "created_at": "2024-11-01T10:00:00Z",
  "id": 60001,
  "updated_at": "2024-11-01T10:00:00Z",
  "operation_action": "ship",
  "operation_status": "pending",
  "tags": [],
  "aes_itn": null,
  "contents_type": null,
  "custom_items": [],
  "customs_description": null,
  "declared_value_in_cents": null,
  "estimated_shipped_at": "2024-11-05T20:00:00Z",
  "is_insured": false,
  "is_shared": false,
  "items": [
    {
      "customs_description": null,
      "declared_value_in_cents": null,
      "has_complete_scan": false,
      "piece_id": 1234000
    },
    {
      "customs_description": null,
      "declared_value_in_cents": null,
      "has_complete_scan": false,
      "piece_id": 1234001
    }
  ],
  "owner_user_id": "12345",
  "pieces": [],
  "rate": {
    "carrier_service": "GroundAdvantage",
    "carrier_type": "USPS - Ground Advantage",
    "created_at": "2024-11-04T10:00:00Z",
    "expired_at": "2024-11-07T10:00:00Z",
    "id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342",
    "price_in_cents": 910,
    "tracking_available": true
  },
  "rate_id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342",
  "return_address": {
    "address_line_1": "",
    "address_line_2": null,
    "addressee": "",
    "country": "",
    "country_abbreviation": "",
    "locality": "",
    "postal_code": "",
    "region": "",
    "region_abbreviation": ""
  },
  "ship_after": "2024-11-05T20:00:00Z",
  "shipping_address": {
    "created_at": "2024-11-04T10:00:00Z",
    "id": 12345,
    "updated_at": "2024-11-04T10: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": 97599,
    "is_authorized": null,
    "locality": "PHOENIX",
    "phone": "",
    "postal_code": "72761",
    "region": "Arizona",
    "region_abbreviation": "AZ",
    "requires_hs_tariff_codes": false,
    "requires_itn": false,
    "tags": [
      "domestic"
    ]
  },
  "shipping_address_id": 12345,
  "shipping_comment": null,
  "signature_on_delivery": false,
  "tracking_number": null
}
```

Example — Create insured domestic shipment:

```json
{
  "created_at": "2024-11-04T10:38:05Z",
  "id": 300000,
  "updated_at": "2024-11-04T10:38:05Z",
  "operation_action": "ship",
  "operation_status": "pending",
  "tags": [],
  "aes_itn": null,
  "contents_type": null,
  "custom_items": [],
  "customs_description": null,
  "declared_value_in_cents": 100000,
  "estimated_shipped_at": "2024-11-20T20:00:00Z",
  "is_insured": true,
  "is_shared": false,
  "items": [
    {
      "customs_description": null,
      "declared_value_in_cents": null,
      "has_complete_scan": true,
      "piece_id": 123456789
    }
  ],
  "owner_user_id": "116561",
  "pieces": [],
  "rate": {
    "carrier_service": "GroundAdvantage",
    "carrier_type": "USPS - Ground Advantage",
    "created_at": "2024-11-04T10:38:00Z",
    "expired_at": "2024-11-07T10:38:00Z",
    "id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342",
    "price_in_cents": 1295,
    "tracking_available": true
  },
  "rate_id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342",
  "return_address": {
    "address_line_1": "",
    "address_line_2": null,
    "addressee": "",
    "country": "",
    "country_abbreviation": "",
    "locality": "",
    "postal_code": "",
    "region": "",
    "region_abbreviation": ""
  },
  "ship_after": "2024-11-20T20:00:00Z",
  "shipping_address_id": 123456,
  "shipping_comment": null,
  "signature_on_delivery": false,
  "tracking_number": null
}
```

Example — Create international shipment:

```json
{
  "created_at": "2024-11-04T10:55:40Z",
  "id": 234234,
  "updated_at": "2024-11-04T10:55:40Z",
  "operation_action": "ship",
  "operation_status": "pending",
  "tags": [],
  "aes_itn": null,
  "contents_type": "Merchandise",
  "custom_items": [
    {
      "declared_value_in_cents": 20000,
      "description": "men's cotton trousers",
      "hs_tariff_code": "620520"
    }
  ],
  "customs_description": null,
  "declared_value_in_cents": null,
  "estimated_shipped_at": "2024-11-20T18:00:00Z",
  "is_insured": true,
  "is_shared": false,
  "items": [
    {
      "customs_description": null,
      "declared_value_in_cents": null,
      "has_complete_scan": false,
      "piece_id": 120000
    }
  ],
  "owner_user_id": "116561",
  "pieces": [],
  "rate": {
    "carrier_service": "FirstClassPackageInternationalService",
    "carrier_type": "USPS - First Class Package International Service",
    "created_at": "2024-11-04T10:55:22Z",
    "expired_at": "2024-11-07T10:55:22Z",
    "id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342",
    "price_in_cents": 2855,
    "tracking_available": true
  },
  "rate_id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342",
  "return_address": {
    "address_line_1": "",
    "address_line_2": null,
    "addressee": "",
    "country": "",
    "country_abbreviation": "",
    "locality": "",
    "postal_code": "",
    "region": "",
    "region_abbreviation": ""
  },
  "ship_after": "2024-11-20T18:00:00Z",
  "shipping_address_id": 12345,
  "shipping_comment": null,
  "signature_on_delivery": false,
  "tracking_number": null
}
```

### 400

The request could not be processed, for example an international shipment without customs information.

Content type: `application/json`

Type: `Error`

### 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"
  }
}
```

### 403

Actions are blocked for a piece in the request. When an account's mail actions are blocked, for example because the account wasn't reverified or an identity document expired, pieces received after that can't be changed. These pieces have `actions-blocked-no-reverification` or `actions-blocked-document-expired` in their `attributes`.

Content type: `application/json`

Type: `Error`

Example — Piece actions blocked:

```json
{
  "error": {
    "code": 403,
    "message": "piece: Mail actions for piece with ID 123456 has been blocked.",
    "type": "REST"
  }
}
```

### 404

The referenced resource is accessible, but the requested item does not exist, for example a pending operation. IDs the caller can't access, or that don't exist at all, return `401` instead.

Content type: `application/json`

Type: `Error`

Example:

```json
{
  "error": {
    "code": 404,
    "message": "piece_id: Piece with ID 14460059 does not have outstanding Operation of type Recycle.",
    "type": "REST"
  }
}
```

### 422

The request body failed validation. The message names the invalid field.

Content type: `application/json`

Type: `Error`

Example:

```json
{
  "error": {
    "code": 422,
    "message": "label: must have a value",
    "type": "REST",
    "fields": {}
  }
}
```

## Schemas

### CreateShipmentRequest

- `shipping_address_id` (integer): Ignored. The shipping address is taken from the rate.
- `rate_id` (string, required): The `id` of a rate returned by getShippingRates. Required.
- `items` (array of `ShipmentItem`, required): The pieces to ship. Must match the pieces the rate was requested for.
- `custom_items` (array of `ShipmentCustomItem`): Customs line items. Replaces the ones from the rate request.
- `signature_on_delivery` (boolean): Require a signature on delivery.
- `is_insured` (boolean): Insure the shipment.
- `declared_value_in_cents` (integer or null): Total declared value of the shipment, in cents.
- `customs_description` (string or null): Description of the contents for customs.
- `aes_itn` (string or null): AES Internal Transaction Number, for destinations whose shipping address has `requires_itn`.
- `contents_type` (string or null): Kind of contents, for customs. With `Documents`, HS tariff codes are not required. One of: `Merchandise`, `Documents`, `ReturnedGoods`, `null`.
- `ship_after` (string<date-time>): Earliest date to ship. Optional. If it is missing or not a valid shipping date, the next valid shipping date is used.

### 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)