Customs Info for Shipments

Provide customs details about your package in your API calls.

About customs and shipments

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 document includes example API calls 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]",
              "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"
          },
          "incoterm": "DDP",
          "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
      }
    ]
    ....,
    ....,
  },
  ....,
  ....
}

Minimum fields required for U.S. territory, APO, FPO, DPO

Shipium’s guidance is that as much of the following information be provided as possible for a shipment to a U.S. territory or a military region to ensure that the shipment is not returned. While some fields are marked as not required for one carrier and required for another carrier, it is not known which carrier will be chosen during carrier selection. Therefore, it is best to supply enough information for all carriers.

{
    ...
    "labelParameters": {...},
    "shipmentParameters": {
     ...,
      "customsInfo": {
          "totalCustomsValue": 54.95,
          "totalCustomsValueCurrency": "USD",
          "reasonForExport": "sale",                      // not strictly required for USPS
          "invoiceDate": "2022-06-13",                    // required for UPS
          "customsItems": [
              {
                  "customsValue": 18.31,
                  "customsValueCurrency": "USD",
                  "commodityDescription": "9 mm steel screws",
                  "countryOfManufacture": "US",          // not strictly required for USPS
                  "customsWeight": {
                      "weight": 4,
                      "weightUnit": "lb"
                  },
                  "quantity": 3,
                  "quantityUnitOfMeasurement": "box"     // required for UPS
              }
          ]
      }
  }
}

Definitions

This section includes Shipium definitions common to customs and international shipping.

Ship option

FieldTypeRequired?Description
shipOptionFor international shipments, the ship option should be one of the following values:
International24Hour
InternationalOneToThreeDayEarly
InternationalOneToThreeDay
InternationalTwoToFiveDay
InternationalTwoToTenDay
InternationalOneToTwoWeek
InternationalOneToFourWeek
YesThe kind of international shipment performance

Customs info

FieldTypeRequiredDescription
ultimateConsigneeTypeString
Values:
direct_consumer
government_entity
reseller
NoThe type of the ultimate consignee; if no value is sent, it will default to direct_consumer.
ultimateConsigneeAddressStringNoThe 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.
totalCustomsValueCurrencyString
Example: USD
YesThe currency to use for the package value in the totalCustomsValue field; must be a valid ISO 4217 currency code
totalCustomsValueFloatYesThe total customs value of the package in total customs value currency units
reasonForExportValues:
sale
gift
sample
returns
personal_effects
YesThe reason to export an international shipment
invoiceNumberStringNoThe Commercial Invoice number, if the Commercial Invoice was generated by your organization
invoiceDateLocalDateYesDate when the invoice was created; ideally, this is the same as the ship date.
electronicExportInformationElectronicExportInformation (see below)NoInformation 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)
customsItemsArray of customsItem objectsYesContains customs information for each item in the shipment
customsDescriptionString
Example: 9 mm steel screws
YesThe detailed description of the items being shipped
aesInternalTransactionNumberStringNoThe number received if the Electronic Export Information (EEI) was filed and has been accepted in the Automated Export System (AES)
incotermString enumeration
Values:

- DDP (delivery duty paid)
- DDU (delivery duty unpaid)
- DAP (delivered at place)
- DPU (delivered at place unloaded)
- FCA (free carrier)
YesDefines the delivery duty responsibility for any mode of transport; the default value is DDP.

Address

FieldTypeRequiredDescription
nameStringYesThe name associated with the address
phoneNumberStringYesPhone number of the contact
emailAddressStringNoEmail address of the contact
companyStringNoThe company name for the address
street1StringNoThe first address line
street2StringNoThe second address line
cityStringNoThe name of the city for the address
stateStringNoThe name of the state for the address
countryCodeStringYesThe ISO-3166-1 country code for the address
postalCodeStringNoA country-appropriate postal code for the address
addressTypeString
Allowable values:
commercial
residential
NoThe type of location for this address

Electronic export information

FieldTypeRequiredDescription
exportDateDate-timeYesThe date the goods will be leaving the country in ISO-8601 format
pointOfOriginStringYesThe 2-character state abbreviation from which the goods were shipped

Customs item data

FieldTypeRequiredDescription
customsValueFloatYesThe value of each individual item to report to customs in customs value currency
customsValueCurrencyStringYesThe ISO-4217 currency code representing the totalCustomsValue.
commodityDescriptionStringYesA description of this product to be provided to customs
countryOfManufactureStringYesThe ISO-3166-1 country code for the address
customsWeightWeight (see below)YesThe weight of an individual item of this product to report to customs
quantityIntegerYesThe number of units of this customs item
quantityUnitOfMeasurementString
Values:
bag
barrel
box
case_of_goods
container
crate
cylinder
envelope
pallet
piece
roll
tube
YesThe unit of measurement of the item
harmonizedTariffNumberStringYesThe 6- to 15-digit Harmonized System Tariff classification code
productIdStringNoA product ID for the customs item
commodityPartNumberStringNoThe part number or reference number for the product
marksAndNumbersStringNoAny special marks, codes, and numbers that may identify the package
electronicExportCommodity InformationElectronicExportCommodityInformation (see below)NoCustoms 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

FieldTypeRequiredDescription
weightFloatYesThe weight of the item to report to customs in units of weight unit
weightUnitString
Values:
g
kg
lb
oz
YesThe weight unit

Electronic export commodity information

FieldTypeRequiredDescription
exportTypeString
Values:
domestic
foreign
YesThe type of the export
exportInformationCodeStringYesThe 2-character export information code for the commodity
scheduleBInformationScheduleBInformation (see below)YesThe Schedule B information for the commodity
eccnNumberStringYesThe 5-digit product Export Control Classification Number (ECCN) number as issued by the Bureau of Industry and Security; the format is #A###.
exportLicenseInformationExportLicenseInformation (see below)YesThe license information for the export

Schedule B information

FieldTypeRequiredDescription
scheduleBNumberStringYesThe 10-digit Schedule B classification code for the item being exported
scheduleBQuantityIntegerYesThe count of how many Schedule B units are in the shipment
scheduleBUnitOfMeasurementString
Values:
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
YesThe unit of measure for the Schedule B quantity

Export license information

FieldTypeRequiredDescription
licenseTypeStringYesThe standard license type code as published by the U.S. 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

Export license

FieldTypeRequiredDescription
licenseNumberStringYesThe license number
licenseLineValueIntegerYesThe export monetary amount allowed per license
licenseExpirationDate-timeYesThe license expiration date in ISO-8601 format

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful: