CustomsItem

A CustomsItem object describes goods for international shipment and should be created then included in a CustomInfo object. The value on each item can also supply product value for USPS Claims when a customs form is already on the shipment. New claims integrations should send line_items.

Endpoints

POST

/customs_items

GET

/customs_items/:id

CustomsItems object

string

Unique, begins with 'cstitem_'

object

string

'CustomsItem'

description

string

Description of item being shipped

quantity

float

Must be greater than zero

value

float (USD)

Total value (unit value * quantity). Must be greater than zero. EasyPost can use this amount as product value for USPS Claims when the item is on the shipment's CustomsInfo.

weight

float (oz)

Total weight (unit weight * quantity). Must be greater than zero.

hs_tariff_number

string

Harmonized Tariff Schedule code used to classify goods for customs declarations. Typically 6 or 10 digits, e.g. "6109.10.0012".

code

string

SKU, UPC or other product identifier

manufacturer

string

Manufacturer of item

eccn

string

Export Control Classification Number

printed_commodity_identifier

string

International commodity code

origin_country

string

Two-character country code

currency

string

Three-character currency code. Defaults to "USD"

created_at

datetime

When the CustomsItem was created

updated_at

datetime

When the CustomsItem was last updated

CustomsItems Object

{
  "id": "cstitem_4e7df04b42fa4ad4a2212620e0d8b78f",
  "object": "CustomsItem",
  "created_at": "2025-05-09T20:39:16Z",
  "updated_at": "2025-05-09T20:39:16Z",
  "description": "T-shirt",
  "hs_tariff_number": "123456",
  "origin_country": "US",
  "quantity": 1,
  "value": "10.0",
  "weight": 5,
  "code": "123",
  "mode": "test",
  "manufacturer": null,
  "currency": null,
  "eccn": null,
  "printed_commodity_identifier": null
}

Create a CustomsItem

A CustomsItem contains information relating to each product within the package. When creating a CustomsItem, you may store the id from the response for use later in CustomsInfo creation.

A CustomsItem object is immutable once created. All information must be provided during creation; it cannot be modified later.

Request Parameters

description

i.e. "T-Shirt"

quantity

i.e. 1

weight

i.e. 5

value

i.e. 10

hs_tariff_number

i.e. "123456"

origin_country

i.e. "US"

currency

i.e. "USD"

manufacturer

i.e. "ACME Inc."

code

i.e. "SKU123"

eccn

i.e. "EAR99"

printed_commodity_identifier

i.e. "123456"

POST /customs_items

1curl -X POST https://api.easypost.com/v2/customs_items \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "customs_item": {
6      "description": "T-shirt",
7      "quantity": "1",
8      "weight": "5",
9      "value": "10",
10      "hs_tariff_number": "123456",
11      "origin_country": "US"
12    }
13  }'

Response

1{
2  "id": "cstitem_4e7df04b42fa4ad4a2212620e0d8b78f",
3  "object": "CustomsItem",
4  "created_at": "2025-05-09T20:39:16Z",
5  "updated_at": "2025-05-09T20:39:16Z",
6  "description": "T-shirt",
7  "hs_tariff_number": "123456",
8  "origin_country": "US",
9  "quantity": 1,
10  "value": "10.0",
11  "weight": 5.0,
12  "code": "123",
13  "mode": "test",
14  "manufacturer": null,
15  "currency": null,
16  "eccn": null,
17  "printed_commodity_identifier": null
18}

Retrieve a CustomsItem

A CustomsItem can be retrieved by its id.

GET /customs_items/:id

1curl -X GET https://api.easypost.com/v2/customs_items/cstitem_... \
2  -u "EASYPOST_API_KEY":

Response

1{
2  "id": "cstitem_c1ac1f9a6c254b1cacd8a2936e624ce5",
3  "object": "CustomsItem",
4  "created_at": "2025-05-09T20:39:16Z",
5  "updated_at": "2025-05-09T20:39:16Z",
6  "description": "T-shirt",
7  "hs_tariff_number": "123456",
8  "origin_country": "US",
9  "quantity": 1,
10  "value": "10.0",
11  "weight": 5.0,
12  "code": "123",
13  "mode": "test",
14  "manufacturer": null,
15  "currency": null,
16  "eccn": null,
17  "printed_commodity_identifier": null
18}