🎉ShipEngine is becoming ShipStation API🎉

Over the next few months you'll notice the ShipEngine website, documentation portal, and dashboard being rebranded as ShipStation API. For our ShipEngine customers, you don't need to take any action or change any of your integrations in any way. All endpoints will remain the same and continue to function as they always have.

To learn more about what's coming, review our [New ShipStation API page](/content/docs/new-shipstation-api/index.html).

# Using Custom Packages

Once you have [defined your custom packages](/content/docs/shipping/custom-package-types/index.html), you can then use either the `package_id` or the `package_code` in the `shipments` object when creating your shipment or purchasing a label.

> **NOTE:**
>
> ### `package_id` vs `package_code`
>
> When creating or updating shipments, you can provide either `package_code` or `package_id`. If both are included, `package_code` will take precedence. When getting rates or labels, only `package_code` is supported.

## Example Request & Response

In this example, we replace the `dimensions` object with the `package_code` property in the `packages` object.

**POST /v1/shipments**

```http
POST /v1/shipments HTTP/1.1

{
  "shipments": [\
    {\
      "service_code": "usps_priority_mail",\
      "shipment_status": "pending",\
      "ship_to": {\
        "name": "Amanda Miller",\
        "phone": "555-555-5555",\
        "address_line1": "525 S Winchester Blvd",\
        "city_locality": "San Jose",\
        "state_province": "CA",\
        "postal_code": "95128",\
        "country_code": "US",\
        "address_residential_indicator": "yes"\
      },\
      "ship_from": {\
        "company_name": "Example Corp.",\
        "name": "John Doe",\
        "phone": "111-111-1111",\
        "address_line1": "4009 Marathon Blvd",\
        "address_line2": "Suite 300",\
        "city_locality": "Austin",\
        "state_province": "TX",\
        "postal_code": "78756",\
        "country_code": "US",\
        "address_residential_indicator": "no"\
      },\
      "confirmation": "none",\
      "advanced_options": {},\
      "insurance_provider": "none",\
      "tags": [],\
      "total_weight": {\
        "value": 10.0,\
        "unit": "ounce"\
      },\
      "packages": [\
        {\
          "package_code": "custom_laptop_box",\
          "weight": {\
            "value": 10.0,\
            "unit": "ounce"\
          }\
        }\
      ]\
    }\
  ]
}
```

**Response**

In the response, you'll see the `package_code` property in the `packages` object (in addition to all its included properties), which indicates that it worked!

```json
{
  "has_errors": false,
  "shipments": [\
    {\
      "errors": null,
      "address_validation": {\
        "status": "verified",\
        "original_address": {\
          "name": "Amanda Miller",\
          "phone": "555-555-5555",\
          "address_line1": "525 S Winchester Blvd",\
          "city_locality": "San Jose",\
          "state_province": "CA",\
          "postal_code": "95128",\
          "country_code": "US",\
          "address_residential_indicator": "yes"\
        },\
        "matched_address": {\
          "name": "AMANDA MILLER",\
          "phone": "555-555-5555",\
          "address_line1": "525 S WINCHESTER BLVD",\
          "city_locality": "SAN JOSE",\
          "state_province": "CA",\
          "postal_code": "95128",\
          "country_code": "US",\
          "address_residential_indicator": "yes"\
        },\
        "messages": []\
      },\
      "shipment_id": "se-41838065",\
      "carrier_id": "se-123890",\
      "service_code": "usps_priority_mail",\
      "external_shipment_id": null,\
      "ship_date": "2019-07-25T05:00:00.000Z",\
      "created_at": "2019-07-25T15:24:46.657Z",\
      "modified_at": "2019-07-25T15:24:46.657Z",\
      "shipment_status": "pending",\
      "ship_to": {\
        "name": "Amanda Miller",\
        "phone": "555-555-5555",\
        "address_line1": "525 S Winchester Blvd",\
        "city_locality": "San Jose",\
        "state_province": "CA",\
        "postal_code": "95128",\
        "country_code": "US",\
        "address_residential_indicator": "yes"\
      },\
      "ship_from": {\
        "company_name": "Example Corp.",\
        "name": "John Doe",\
        "phone": "111-111-1111",\
        "address_line1": "4009 Marathon Blvd",\
        "address_line2": "Suite 300",\
        "city_locality": "Austin",\
        "state_province": "TX",\
        "postal_code": "78756",\
        "country_code": "US",\
        "address_residential_indicator": "no"\
      },\
      "warehouse_id": null,\
      "return_to": {\
        "company_name": "Example Corp.",\
        "name": "John Doe",\
        "phone": "111-111-1111",\
        "address_line1": "4009 Marathon Blvd",\
        "address_line2": "Suite 300",\
        "city_locality": "Austin",\
        "state_province": "TX",\
        "postal_code": "78756",\
        "country_code": "US",\
        "address_residential_indicator": "no"\
      },\
      "confirmation": "none",\
      "advanced_options": {\
        "bill_to_account": null,\
        "bill_to_country_code": null,\
        "bill_to_party": null,\
        "bill_to_postal_code": null,\
        "contains_alcohol": false,\
        "custom_field1": null,\
        "custom_field2": null,\
        "custom_field3": null,\
        "non_machinable": false,\
        "saturday_delivery": false\
      },\
      "insurance_provider": "none",\
      "tags": [],\
      "total_weight": {\
        "value": 10.0,\
        "unit": "ounce"\
      },\
      "packages": [\
        {\
          "package_code": "custom_laptop_box",\
          "weight": {\
            "value": 10.0,\
            "unit": "ounce"\
          },\
          "dimensions": {\
            "unit": "inch",\
            "length": 15.00,\
            "width": 20.00,\
            "height": 5.00\
          },\
          "insured_value": {\
            "currency": "usd",\
            "amount": 0.0\
          }\
        }\
      ]\
    }\
  ]
}
```