Customs Info API Example & Definitions
Customs application programming interface (API) overviews
In international shipping, customs commonly refers to any applicable duties, fees, or taxes charged on items being shipped from one country to another. When shipping internationally, your organization may be required to provide additional customs details about your package.
This documentation includes example client uniform resource locator (cURL) application programming interface (API) calls as well as a sample JavaScript Object Notation (JSON) response for customs-specific shipping scenarios, including when international document printing is required, when electronic export information (EEI) is not required, when EEI is required, and when you want to pass all customs details for a shipment.
Finally, common definitions associated with customs and international shipping are included.
Example API calls and responses for international shipping customs
Minimum fields required for international, no EEI required for shipment
This is a sample cURL call to the API including the minimum required information for international shipping when an EEI is not required.
{
...
"labelParameters": {...},
"shipmentParameters": {
...,
"shipOption": "InternationalTwoToFiveDay",
"customsInfo": {
"totalCustomsValue": 54.95,
"totalCustomsValueCurrency": "USD",
"customsDescription": "9 mm steel screws",
"reasonForExport": "sale",
"invoiceDate": "2022-06-13",
"customsItems": [
{
"customsValue": 18.31,
"customsValueCurrency": "USD",
"commodityDescription": "9 mm steel screws",
"countryOfManufacture": "US",
"customsWeight": {
"weight": 4,
"weightUnit": "lb"
},
"quantity": 3,
"quantityUnitOfMeasurement": "box",
"harmonizedTariffNumber": "9876543210"
}
]
}
}
}
Minimum fields for a shipment that requires an EEI, and EEI is filed through AES Direct
This is a sample cURL call to the API including the minimum required information for international shipping when an EEI is required and it is filed through the Automated Commercial Environment (ACE) AESDirect.
{
...
"labelParameters": {...},
"shipmentParameters": {
...,
"shipOption": "InternationalTwoToFiveDay",
"customsInfo": {
"totalCustomsValue": 54.95,
"totalCustomsValueCurrency": "USD",
"customsDescription": "9 mm steel screws",
"reasonForExport": "sale",
"invoiceDate": "2022-06-13",
"aesInternalTransactionNumber": "X20220613366903",
"customsItems": [
{
"customsValue": 18.31,
"customsValueCurrency": "USD",
"commodityDescription": "9 mm steel screws",
"countryOfManufacture": "US",
"customsWeight": {
"weight": 4,
"weightUnit": "lb"
},
"quantity": 3,
"quantityUnitOfMeasurement": "box",
"harmonizedTariffNumber": "9876543210"
}
]
}
}
}
Sample API call with customs information included
This is a sample cURL call to the API including customs information.
{
...
"labelParameters": {...},
"shipmentParameters": {
...,
"shipOption": "InternationalTwoToFiveDay",
"customsInfo": {
"totalCustomsValue": 54.95,
"totalCustomsValueCurrency": "USD",
"customsDescription": "9 mm steel screws",
"reasonForExport": "sale",
"invoiceDate": "2022-06-13",
"invoiceNumber": "123-abc-456",
"ultimateConsigneeAddress": {
"name": "Wile E. Coyote",
"phoneNumber": "1112223333",
"emailAddress": "[email protected]",
"company": null,
"street1": "123 Test",
"city": "St. John's",
"state": "NL",
"countryCode": "CA",
"postalCode": "A1A 2H4",
"addressType": "residential"
},
"ultimateConsigneeType": "direct_consumer",
"aesInternalTransactionNumber": "X20220613366903",
"electronicExportInformation": { // Note: not needed if an aesInternalTransactionNumber is provided
"exportDate": "2022-06-15",
"pointOfOrigin": "CO"
},
"customsItems": [
{
"customsValue": 18.31,
"customsValueCurrency": "USD",
"commodityDescription": "9 mm steel screws",
"countryOfManufacture": "US",
"customsWeight": {
"weight": 4,
"weightUnit": "lb"
},
"quantity": 3,
"quantityUnitOfMeasurement": "box",
"harmonizedTariffNumber": "9876543210",
"productId": "ABC123",
"commodityPartNumber": "12345",
"marksAndNumbers": "1 of 1",
"electronicExportCommodityInformation": { // Note: not needed if the carrier is not filing an EEI
"exportType": "domestic",
"exportInformationCode": "LC",
"scheduleBInformation": {
"scheduleBNumber": "6404195500",
"scheduleBQuantity": 3,
"scheduleBUnitOfMeasurement": "pack"
},
"eccnNumber": "EAR99",
"exportLicenseInformation": {
"licenseType": "C33",
"licenseExemptionCode": "NLR",
"exportLicense": { // Note: not needed if you have provided a licenseExemptionCode
"licenseNumber": "123ABC",
"licenseLineValue": 1000,
"licenseExpiration": "2025-06-13"
}
}
}
}
]
}
}
}
Sample response with customs information included in the API call
This is a sample JSON response from the API when customs information was included in the API call.
{
"carrierSelection": {
....
},
....,
....,
"carrierLabel": {
....,
....,
"documents": [
{
"labelExpiration": "2023-11-19T21:08:54.305Z",
"labelFormat": "ZPL",
"labelImage": {
"imageContents": "BASE64LOOKINGSTUFFANDWHATHAVEYOUETCETCETC",
"imageEncoding": "base64"
},
"labelUrl": "string"
}
],
"internationalDocuments": [
{
"documentType": "commericial_invoice", // "commercial_invoice", "electronic_export_information", "ps_2976", "air_waybill" or "multiple"
"documentExpiration": "2023-11-19T21:08:54.305Z",
"documentFormat": "PDF",
"documentImage": {
"documentEncoding": "base64",
"documentContents": "BASE64LOOKINGSTUFFANDWHATHAVEYOUETCETCETC"
},
"electronicallySubmitted": false
}
]
....,
....,
},
....,
....
}
Definitions
This section includes Shipium definitions common to customs and international shipping.
ShipOption
Field | Type | Required? | Description |
---|---|---|---|
shipOption | For international shipments, the shipOption should be one of the following: Enum: - International24Hour - InternationalOneToThreeDayEarly - InternationalOneToThreeDay - InternationalTwoToFiveDay - InternationalTwoToTenDay - InternationalOneToTwoWeek - InternationalOneToFourWeek | Yes | The kind of international shipment performance |
CustomsInfo
Field | Type | Required | Description |
---|---|---|---|
ultimateConsigneeType | Enum:direct_consumer government_entity - reseller | No | The type of the ultimate consignee. If no value is sent, it will default to direct_consumer |
ultimateConsigneeAddress | Address (see below) | No | The person or company who receives the goods for end-use. If no value is sent, we will use the destinationAddress Note: a phone number is required. |
totalCustomsValueCurrency | String | Yes | The ISO-4217 currency code representing the totalCustomsValue |
totalCustomsValue | Float | Yes | The customs value of the shipment in totalCustomsValueCurrency |
reasonForExport | Enum:sale gift sample returns - personal_effects | Yes | The reason to export an international shipment |
invoiceNumber | String | No | The Commercial Invoice number, if the Commercial Invoice was generated by your organization |
invoiceDate | LocalDate | Yes | Date when the invoice was created. Ideally this is the same as the ship date |
electronicExportInformation | ElectronicExportInformation (see below) | No | Information for the Electronic Export Information (EEI) customs form, only used when the EEI will be filed directly by the carrier (i.e., not filed by your organization using AESDirect or otherwise) |
customsItems | List of CustomsItemData (see below) | Yes | Contains customs information for each item in the shipment |
customsDescription | String | Yes | The detailed description of the items being shipped |
aesInternalTransactionNumber | String | No | The number received if the Electronic Export Information (EEI) was filed and has been accepted in the Automated Export System (AES) |
Address
Field | Type | Required | Description |
---|---|---|---|
name | String | Yes | The name associated with the address |
phoneNumber | String | Yes | Phone number of the contact |
emailAddress | String | No | Email address of the contact |
company | String | No | The company name for the address |
street1 | String | No | The first address line |
street2 | String | No | The second address line |
city | String | No | The name of the city for the address |
state | String | No | The name of the state for the address |
countryCode | String | Yes | The ISO-3166-1 country code for the address |
postalCode | String | No | A country-appropriate postal code for the address |
addressType | Enum. Allowable values:commercial residential | No | The type of location for this address |
ElectronicExportInformation
Field | Type | Required | Description |
---|---|---|---|
exportDate | DateTime | Yes | The date the goods will be leaving the country in ISO-8601 format |
pointOfOrigin | String | Yes | The 2-character state abbreviation from which the goods were shipped |
CustomsItemData
Field | Type | Required | Description |
---|---|---|---|
customsValue | Float | Yes | The value of each individual item to report to customs in customsValueCurrency |
customsValueCurrency | String | Yes | The ISO-4217 currency code representing the totalCustomsValue . |
commodityDescription | String | Yes | A description of this product to be provided to customs |
countryOfManufacture | String | Yes | The ISO-3166-1 country code for the address. |
customsWeight | Weight (see below) | Yes | The weight of an individual item of this product to report to customs |
quantity | int | Yes | The number of units of this customs item |
quantityUnitOfMeasurement | Enum:bag barrel box case_of_goods container crate cylinder envelope pallet piece roll tube | Yes | The unit of measurement of the item. |
harmonizedTariffNumber | String | Yes | The 6-15 digit Harmonized System Tariff classification code |
productId | String | No | A product ID for the customs item |
commodityPartNumber | String | No | The part number or reference number for the product |
marksAndNumbers | String | No | Any special marks, codes, and numbers that may identify the package |
electronicExportCommodityInformation | ElectronicExportCommodityInformation (see below) | No | Customs item information that is particular to the Electronic Export Information (EEI), only used when the EEI will be filed directly by the carrier (i.e. not filed by the partner using AES Direct or otherwise) |
Weight
Field | Type | Required | Description |
---|---|---|---|
weight | Float | Yes | The weight of the item to report to customs in units of weightUnit |
weightUnit | Enum:g kg lb oz | Yes | The weight unit |
ElectronicExportCommodityInformation
Field | Type | Required | Description |
---|---|---|---|
exportType | Enum:domestic foreign | Yes | The type of the export |
exportInformationCode | String | Yes | The 2-character export information code for the commodity |
scheduleBInformation | ScheduleBInformation (see below) | Yes | The Schedule B information for the commodity |
eccnNumber | String | Yes | The 5-digit product Export Control Classification Number (ECCN) number as issued by the Bureau of Industry and Security. The format is #A### |
exportLicenseInformation | ExportLicenseInformation (see below) | Yes | The license information for the export |
ScheduleBInformation
Field | Type | Required | Description |
---|---|---|---|
scheduleBNumber | String | Yes | The 10-digit Schedule B classification code for the item being exported |
scheduleBQuantity | int | Yes | The count of how many Schedule B units are in the shipment |
scheduleBUnitOfMeasurement | Enum:barrels carat content_kilogram square_centimeter content_ton curie clean_yield_kilogram dozen dozen_pieces dozen_pairs fiber_meter gross_container gram gross hundred kilogram cubic_kilometer kilogram_total_sugars liter meter square_meter cubic_meter millicurie number pieces proof_liter pack pairs running_bales square ton thousand - no_quantity_required | Yes | The unit of measure for the Schedule B quantity |
ExportLicenseInformation
Field | Type | Required | Description |
---|---|---|---|
licenseType | String | Yes | The standard license type code as published by the U.S. government |
licenseExemptionCode | String | No | The license exemption code, if the license type does not require a license number |
exportLicense | ExportLicense (see below) | No | The export license, if the license type requires a valid license |
ExportLicense
Field | Type | Required | Description |
---|---|---|---|
licenseNumber | String | Yes | The license number |
licenseLineValue | int | Yes | The export monetary amount allowed per license |
licenseExpiration | DateTime | Yes | The license expiration date in ISO-8601 format |
Updated 2 months ago