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

Field	Type	Required?	Description
`shipOption`	For international shipments, the ship option should be one of the following values: `International24Hour` `InternationalOneToThreeDayEarly` `InternationalOneToThreeDay` `InternationalTwoToFiveDay` `InternationalTwoToTenDay` `InternationalOneToTwoWeek` `InternationalOneToFourWeek`	Yes	The kind of international shipment performance

Customs info

Field	Type	Required	Description
`ultimateConsigneeType`	String Values: `direct_consumer` `government_entity` `reseller`	No	The type of the ultimate consignee; if no value is sent, it will default to `direct_consumer`.
`ultimateConsigneeAddress`	String	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 Ex.: `usd`	Yes	The currency to use for the package value in the `totalCustomsValue` field; must be a valid ISO 4217 currency code
`totalCustomsValue`	Float	Yes	The total customs value of the package in total customs value currency units
`reasonForExport`	Values: `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`	Array of `customsItem` objects	Yes	Contains customs information for each item in the shipment
`customsDescription`	String Ex.: `9 mm steel screws`	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)
`incoterm`	String enumeration Values: - `ddp` (delivery duty paid) - `ddu` (delivery duty unpaid) - `dap` (delivered at place) - `dpu` (delivered at place unloaded) - `fca` (free carrier)	Yes	Defines the delivery duty responsibility for any mode of transport; the default value is `ddp`.

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`	String Allowable values: `commercial` `residential`	No	The type of location for this address

Electronic export information

Field	Type	Required	Description
`exportDate`	Date-time	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

Customs item data

Field	Type	Required	Description
`customsValue`	Float	Yes	The value of each individual item to report to customs in customs value currency
`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`	Integer	Yes	The number of units of this customs item
`quantityUnitOfMeasurement`	String Values: `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- to 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
`electronicExportCommodity Information`	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 weight unit
`weightUnit`	String Values: `g` `kg` `lb` `oz`	Yes	The weight unit

Electronic export commodity information

Field	Type	Required	Description
`exportType`	String Values: `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

Schedule B information

Field	Type	Required	Description
`scheduleBNumber`	String	Yes	The 10-digit Schedule B classification code for the item being exported
`scheduleBQuantity`	Integer	Yes	The count of how many Schedule B units are in the shipment
`scheduleBUnitOfMeasurement`	String 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`	Yes	The unit of measure for the Schedule B quantity

Export license information

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

Export license

Field	Type	Required	Description
`licenseNumber`	String	Yes	The license number
`licenseLineValue`	Integer	Yes	The export monetary amount allowed per license
`licenseExpiration`	Date-time	Yes	The 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: