Looking for the old docs? View our old docs site.
API Docs

CustomsInfo

CustomsInfo objects contain CustomsItem objects and all necessary information for the generation of customs forms required for international shipping.

Please see the Shipments documentation for examples of including a CustomsInfo object in a Shipment. Note: the maximum number of items that can be included in customs info with UPS is 100.

Endpoints
POST
/customs_infos
GET
/customs_infos/:id

CustomsInfo object

id
string
Unique, begins with 'cstinfo_'
object
string
'CustomsInfo'
eel_pfc
string
"EEL" or "PFC"
  • If value is less than $2500: "NOEEI 30.37(a)"
  • If value is greater than $2500: see Customs Guide
contents_type
string

Possible values:

  • "documents"
  • "gift"
  • "merchandise"
  • "returned_goods"
  • "sample"
  • "dangerous_goods"
  • "humanitarian_donation"
  • "other"
contents_explanation
string
Human readable description of content, max 255 characters. Required for certain carriers and always required if contents_type is "other"
customs_certify
boolean
Electronically certify the information provided
customs_signer
string
Required if customs_certify is true
non_delivery_option
string

Possible values:

  • "return" (default)
  • "abandon"
restriction_type
string

Possible values:

  • "none"
  • "other"
  • "quarantine"
  • "sanitary_phytosanitary_inspection"
restriction_comments
string
Required if restriction_type is not "none"
customs_items
Describes products being shipped
declaration
string
A customs declaration message, available for eligible carriers
created_at
datetime
When the CustomsInfo was created
updated_at
datetime
When the CustomsInfo was last updated
CustomsInfo Object
{
  "id": "cstinfo_55c25c9757b6456c9f222b1e7d8dfe94",
  "object": "CustomsInfo",
  "created_at": "2024-01-24T00:05:42Z",
  "updated_at": "2024-01-24T00:05:42Z",
  "contents_explanation": "",
  "contents_type": "merchandise",
  "customs_certify": true,
  "customs_signer": "Steve Brule",
  "eel_pfc": "NOEEI 30.37(a)",
  "non_delivery_option": "return",
  "restriction_comments": null,
  "restriction_type": "none",
  "mode": "test",
  "declaration": null,
  "customs_items": [
    {
      "id": "cstitem_ef7c227016ec4967833e8049cdc6d684",
      "object": "CustomsItem",
      "created_at": "2024-01-24T00:05:42Z",
      "updated_at": "2024-01-24T00:05:42Z",
      "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 CustomsInfo

A CustomsInfo object contains all administrative information for processing customs, as well as a list of CustomsItems. When creating a CustomsInfo, you may store the id from the response for use later in Shipment creation.

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

Request Parameters

customs_certify
i.e. true
customs_signer
i.e. "Steve Brule"
contents_type
i.e. "merchandise"
restriction_type
i.e. "none"
eel_pfc
i.e. "NOEEI 30.37(a)"
customs_items
POST /customs_infos
1curl -X POST https://api.easypost.com/v2/customs_infos \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "customs_info": {
6      "customs_certify": "true",
7      "customs_signer": "Steve Brule",
8      "contents_type": "merchandise",
9      "contents_explanation": "",
10      "restriction_type": "none",
11      "eel_pfc": "NOEEI 30.37(a)",
12      "customs_items": [
13        {
14          "description": "T-shirt",
15          "quantity": "1",
16          "weight": "5",
17          "value": "10",
18          "hs_tariff_number": "123456",
19          "origin_country": "US"
20        }
21      ]
22    }
23  }'
Response
1{
2  "id": "cstinfo_55c25c9757b6456c9f222b1e7d8dfe94",
3  "object": "CustomsInfo",
4  "created_at": "2024-01-24T00:05:42Z",
5  "updated_at": "2024-01-24T00:05:42Z",
6  "contents_explanation": "",
7  "contents_type": "merchandise",
8  "customs_certify": true,
9  "customs_signer": "Steve Brule",
10  "eel_pfc": "NOEEI 30.37(a)",
11  "non_delivery_option": "return",
12  "restriction_comments": null,
13  "restriction_type": "none",
14  "mode": "test",
15  "declaration": null,
16  "customs_items": [
17    {
18      "id": "cstitem_ef7c227016ec4967833e8049cdc6d684",
19      "object": "CustomsItem",
20      "created_at": "2024-01-24T00:05:42Z",
21      "updated_at": "2024-01-24T00:05:42Z",
22      "description": "T-shirt",
23      "hs_tariff_number": "123456",
24      "origin_country": "US",
25      "quantity": 1,
26      "value": "10.0",
27      "weight": 5.0,
28      "code": "123",
29      "mode": "test",
30      "manufacturer": null,
31      "currency": null,
32      "eccn": null,
33      "printed_commodity_identifier": null
34    }
35  ]
36}

Retrieve a CustomsInfo

A CustomsInfo can be retrieved by its id.

GET /customs_infos/:id
1curl -X GET https://api.easypost.com/v2/customs_infos/cstinfo_... \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "id": "cstinfo_8ebad928c87d40aea1d0695d835d93de",
3  "object": "CustomsInfo",
4  "created_at": "2024-01-24T00:05:43Z",
5  "updated_at": "2024-01-24T00:05:43Z",
6  "contents_explanation": "",
7  "contents_type": "merchandise",
8  "customs_certify": true,
9  "customs_signer": "Steve Brule",
10  "eel_pfc": "NOEEI 30.37(a)",
11  "non_delivery_option": "return",
12  "restriction_comments": null,
13  "restriction_type": "none",
14  "mode": "test",
15  "declaration": null,
16  "customs_items": [
17    {
18      "id": "cstitem_ffde56d2590d498198fba5f223cd3ba5",
19      "object": "CustomsItem",
20      "created_at": "2024-01-24T00:05:43Z",
21      "updated_at": "2024-01-24T00:05:43Z",
22      "description": "T-shirt",
23      "hs_tariff_number": "123456",
24      "origin_country": "US",
25      "quantity": 1,
26      "value": "10.0",
27      "weight": 5.0,
28      "code": "123",
29      "mode": "test",
30      "manufacturer": null,
31      "currency": null,
32      "eccn": null,
33      "printed_commodity_identifier": null
34    }
35  ]
36}