Customs Info API Example & Definitions

API Overviews

Example: minimum fields required for international, no EEI required for shipment

{
    ...
    "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"
              }
          ]
      }
  }
}

Example - minimum fields for a shipment that requires an EEI, and EEI is filed through AES Direct by the partner

{
    ...
    "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"
              }
          ]
      }
  }
}

Example - Sample with all fields

{
    ...
    "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"
                          }
                      }
                  }
              }
          ]
      }
  }
}

Definitions

Ship Option

Field

Type

Required?

Description

shipOption

For international shipments, the shipOption should be one of the following:

Enum:
International24Hour
InternationalOneToThreeDayEarly
InternationalOneToThreeDay
InternationalTwoToFiveDay
InternationalTwoToTenDay[
](http://google.com)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 the partner

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 the partner using AES Direct 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

FieldTypeRequiredDescription
exportDateDateTimeYesThe date the goods will be leaving the country in ISO-8601 format.
pointOfOriginStringYesThe 2-characted 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 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

FieldTypeRequiredDescription
licenseTypeStringYesThe standard license type code as published by the US government
licenseExemptionCodeStringNoThe license exemption code, if the license type does not require a license number
exportLicenseExportLicense (see below)NoThe export license, if the license type requires a valid license

ExportLicense

FieldTypeRequiredDescription
licenseNumberStringYesThe license number
licenseLineValueintYesThe export monetary amount allowed per license
licenseExpirationDateTimeYesThe license expiration date in ISO-8601 format.

Did this page help you?