Skip to main content
POST
/
customs
/
items
cURL
curl  https://api.goshippo.com/customs/items/ \
-H "Authorization: ShippoToken <API_TOKEN>" \
-d description="T-Shirt" \
-d quantity=2 \
-d net_weight="400" \
-d mass_unit="g" \
-d value_amount="20" \
-d value_currency="USD" \
-d tariff_number="" \
-d origin_country="US" \
-d metadata="Order ID '123123'"
{
  "description": "T-Shirt",
  "mass_unit": "lb",
  "net_weight": "5",
  "origin_country": "<string>",
  "quantity": 20,
  "value_amount": "200",
  "value_currency": "USD",
  "eccn_ear99": "<string>",
  "metadata": "Order ID \"123454\"",
  "sku_code": "HM-123",
  "hs_code": "0901.21",
  "tariff_number": "<string>",
  "object_created": "2014-07-17T00:49:20.631Z",
  "object_id": "d799c2679e644279b59fe661ac8fa488",
  "object_owner": "shippotle@shippo.com",
  "object_state": "VALID",
  "object_updated": "2014-07-17T00:49:20.631Z",
  "test": true
}

Authorizations

​
Authorization
string
header
default:ShippoToken shippo_test_d41a6f04796998570c521a50828eae8e3cccf0eb
required

API key authentication using the ShippoToken scheme. Format: Authorization: ShippoToken <API_TOKEN> Example: Authorization: ShippoToken shippo_live_abc123

Headers

​
SHIPPO-API-VERSION
string
default:2018-02-08

Optional string used to pick a non-default API version to use. See our API version guide.

Example:

"2018-02-08"

Body

application/json

CustomsItem details.

​
description
string
required

Text description of your item.

Example:

"T-Shirt"

​
mass_unit
enum<string>
required

The unit used for weight.

Available options:
g,
kg,
lb,
oz
Example:

"lb"

​
net_weight
string
required

Total weight of this item, i.e. quantity * weight per item.

Example:

"5"

​
origin_country
string
required

Country of origin of the item. Example: US or DE. All accepted values can be found on the Official ISO Website.

​
quantity
integer<int64>
required

Quantity of this item in the shipment you send. Must be greater than 0.

Example:

20

​
value_amount
string
required

Total value of this item, i.e. quantity * value per item.

Example:

"200"

​
value_currency
string
required

Currency used for value_amount. The official ISO 4217 currency codes are used, e.g. USD or EUR.

Example:

"USD"

​
eccn_ear99
string

Export Control Classification Number, required on some exports from the United States.

​
metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

Example:

"Order ID \"123454\""

​
sku_code
string

SKU code of the item, which is required by some carriers.

Example:

"HM-123"

​
hs_code
string

HS code of the item, which is required by some carriers. If tariff_number is not provided, hs_code will be used. If both hs_code and tariff_number are provided, tariff_number will be used. 50 character limit.

Example:

"0901.21"

​
tariff_number
string

The tariff number of the item. If tariff_number is not provided, hs_code will be used. If both hs_code and tariff_number are provided, tariff_number will be used. 12 character limit.

Response

Customs item

​
description
string
required

Text description of your item.

Example:

"T-Shirt"

​
mass_unit
enum<string>
required

The unit used for weight.

Available options:
g,
kg,
lb,
oz
Example:

"lb"

​
net_weight
string
required

Total weight of this item, i.e. quantity * weight per item.

Example:

"5"

​
origin_country
string
required

Country of origin of the item. Example: US or DE. All accepted values can be found on the Official ISO Website.

​
quantity
integer<int64>
required

Quantity of this item in the shipment you send. Must be greater than 0.

Example:

20

​
value_amount
string
required

Total value of this item, i.e. quantity * value per item.

Example:

"200"

​
value_currency
string
required

Currency used for value_amount. The official ISO 4217 currency codes are used, e.g. USD or EUR.

Example:

"USD"

​
eccn_ear99
string

Export Control Classification Number, required on some exports from the United States.

​
metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

Example:

"Order ID \"123454\""

​
sku_code
string

SKU code of the item, which is required by some carriers.

Example:

"HM-123"

​
hs_code
string

HS code of the item, which is required by some carriers. If tariff_number is not provided, hs_code will be used. If both hs_code and tariff_number are provided, tariff_number will be used. 50 character limit.

Example:

"0901.21"

​
tariff_number
string

The tariff number of the item. If tariff_number is not provided, hs_code will be used. If both hs_code and tariff_number are provided, tariff_number will be used. 12 character limit.

​
object_created
string<date-time>

Date and time of object creation.

Example:

"2014-07-17T00:49:20.631Z"

​
object_id
string

Unique identifier of the given object.

Example:

"d799c2679e644279b59fe661ac8fa488"

​
object_owner
string

Username of the user who created the object.

Example:

"shippotle@shippo.com"

​
object_state
enum<string>

Indicates the validity of the enclosing object

Available options:
VALID,
INVALID
​
object_updated
string<date-time>

Date and time of last object update.

Example:

"2014-07-17T00:49:20.631Z"

​
test
boolean

Indicates whether the object has been created in test mode.