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.

Carrier-specific requirements

Customs information needed may differ by carrier. Shipium recommends checking specific carrier requirements when shipping internationally. You can find guidance for Shipium-supported carriers with additional customs requirements in the following carrier-specific documentation: Amazon - Ship With Amazon, AMPM, Estafeta, LaserShip, and Paquetexpress.

In addition, UPS recommends including an email address for both the shipper and recipient for international shipments. You can include this information in the shipmentParameters or multiParcelShipmentParameters of your API call as the shipFromAddress.emailAddress and destinationAddress.emailAddress.

Customs items to order item quantity mapping

For certain carriers, accurate customs declaration requires a precise mapping between the individual items declared in your customs information and the corresponding items within each parcel. Shipium facilitates this by connecting the productId values provided in your customsInfo.customsItems with the productId values in your package's orderItemQuantities.

How it works. When you provide customs information for a shipment with the following carriers, Shipium expects that each customsItem will have a productId that matches a productId in one of the orderItemQuantities. This connects each item declared for customs with its corresponding item in your parcel.

Important. If the productId values do not match between your customsInfo.customsItems and your orderItemQuantities, the system will be unable to send complete and accurate customs and item information to the carrier. This may result in:

Shipment delays
Customs clearance issues
Incorrect duties and taxes calculations
Shipment rejection by the carrier

Carriers requiring this mapping. The following carriers require this explicit productId mapping for customs declarations:

Amazon - Ship With Amazon
Cirro
ECMS
FlavorCloud
Reliable Logistics

Action required. When preparing shipments for these carriers, you'll want to ensure that:

Every item you declare in customsInfo.customsItems has a unique and accurate productId.
Every item listed in your package's orderItemQuantities also has a productId.
The productId for each item in customsInfo.customsItems precisely matches the productId of its corresponding item in orderItemQuantities.

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. Importer of record and broker are not included in this sample call; the Broker & Importer of Record document provides details about these optional fields that can be included in your API call. The Tax Identification Number document includes information about the optional tax ID field in the sample call.

{
    ...
    "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",
          "europeanUnionInfo": {
              "vendorIossNumber": "123456789012"
          },
          "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"
          },
         "b13AFilingOption": "NOT_REQUIRED",
          "exportComplianceStatement": "AESX20220714987654",
          "permitNumber": "12345",
          "incoterm": "ddp",
          "declarationStatement": "I declare that the information provided is true and accurate. These commodities are licensed by the United States for export to the destination country",            
          "taxIdentificationNumber": "12345",
          "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": "https://api.shipium.com/labels/1a486afc-2ffc-4c37-928f-8d6aa014b35b.zpl"
      }
    ],
    "internationalDocuments": [
      {
        "documentType": "commercial_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 of API request fields for customs and international shipping

This section includes Shipium descriptions of API request fields common to customs and international shipping. All fields are included within customsInfo in the shipmentParameters (or multiParcelShipmentParameters for multi-parcel shipments) of your call, with the exception of shipOption, which is included at the shipmentParameters (or multiParcelShipmentParameters) level.

Importer of record and broker are not included here; the Broker & Importer of Record document provides details about these optional fields that can be included in your API call. Likewise, the Tax Identification Number document includes information about tax IDs that is not included here.

Ship option

The shipOption field is included in the shipmentParameters of the API call (or in multiParcelShipmentParameters for a multi-parcel shipment). You can find more information about ship options in our Ship Options documentation.

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

The customsInfo fields are included in the shipmentParameters (or in multiParcelShipmentParameters for a multi-parcel shipment) of the API call.

Field	Type	Required	Description
`totalCustomsValue`	Float	Yes	The total customs value of the package in total customs value currency units
`totalCustomsValueCurrency`	String Ex.: `usd`	Yes	The currency to use for the package value in the `totalCustomsValue` field; this must be a valid ISO 4217 currency code.
`customsDescription`	String Ex.: `9 mm steel screws`	Yes	The detailed description of the items being shipped
`reasonForExport`	Values: `sale` `gift` `sample` `returns` `personal_effects`	Yes	The reason to export an international shipment
`invoiceDate`	LocalDate	Yes	Date when the invoice was created; ideally, this is the same as the ship date.
`invoiceNumber`	String	No	The Commercial Invoice number, if the Commercial Invoice was generated by your organization
`europeanUnionInfo .vendorIossNumber`	String	No	An Import One-Stop-Shop (IOSS) number is a 12-digit identification number that is used to pay value added tax (VAT) and declare imports to the European Union (EU). The IOSS number is a type of VAT identification, but it is not the same as a resident VAT registration.
`ultimateConsigneeAddress`	String	Conditional (see the address fields that follow)	The address of the person or company who receives the goods for end use; if no value is sent, we will use the destinationAddress
`ultimateConsigneeAddress .name`	String	No	The name associated with the address
`ultimateConsigneeAddress .phoneNumber`	String	Conditional (some carriers require a phone number)	The phone number of the contact
`ultimateConsigneeAddress .phoneNumberCountryCode`	String	No	The country code of the phone number of the contact
`ultimateConsigneeAddress .emailAddress`	String	No	The email address of the contact
`ultimateConsigneeAddress .company`	String	No	The company name for the address
`ultimateConsigneeAddress .street1`	String	No	The first address line
`ultimateConsigneeAddress .street2`	String	No	The second address line
`ultimateConsigneeAddress .city`	String	No	The name of the city for the address
`ultimateConsigneeAddress .state`	String	No	The name of the state for the address
`ultimateConsigneeAddress .countryCode`	String	Yes	The ISO-3166-1 country code for the address
`ultimateConsigneeAddress .postalCode`	String	Yes	A country-appropriate postal code for the address
`ultimateConsigneeAddress .addressType`	String Allowable values: `commercial` `residential`	No	The type of location for this address
`ultimateConsigneeAddress .addressLineComponents`	String Ex.: `streetName`: "Fovisste Fuentes Brotantes" `primaryAddressNumber`: "12" `secondaryAddressNumber`: "302" `district`: "Iztacalco" `neighborhood`: "Agrícola Pantitlán"	Optional, but preferred for Mexican addresses	The address line components for the address, used for some international shipments. This is an optional object that can be included in `shipmentParameters`. The `street1` and `street2` fields should not be included if using `addressLineComponents`, or an error will be returned. This optional address object is not included in the example JSON requests for this API call. You can find out more about Mexican addresses in Non-U.S. Address Formats.
`ultimateConsigneeType`	String Values: `direct_consumer` `government_entity` `reseller`	No	The type of the ultimate consignee, the person or company receiving the shipment; if no value is sent, it will default to `direct_consumer`.
`aesInternalTransactionNumber`	String	No	The number received if the Electronic Export Information (EEI) was filed and has been accepted in the Automated Export System (AES)
`electronicExportInformation`	Array of `electronicExportInformation`objects (defined in the following table rows)	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)
`electronicExportInformation .exportDate`	Date-time	No, but required if including EEI	The date the goods will be leaving the country in ISO-8601 format
`electronicExportInformation .pointOfOrigin`	String	No, but required if including EEI	The 2-character state abbreviation from which the goods were shipped
`b13AFilingOption`	String enumeration Values: `NOT_REQUIRED` `MANUALLY_ATTACHED` `FILED_ELECTRONICALLY` `SUMMARY_REPORTING` `CARRIER_TO_STAMP` `UNKNOWN`	Conditional	Specify the filing option being exercised; this is required for non-document shipments originating in Canada destined for any country other than Canada, the United States, Puerto Rico, or the U.S. Virgin Islands.
`exportComplianceStatement`	String Ex.: `AESX20220714987654`	No	For U.S. export shipments requiring an EEI, enter the ITN number received from AES when you filed your shipment or the FTR (Foreign Trade Regulations) exemption number. The proper format for an ITN number is AES XYYYYMMDDNNNNNN where YYYYMMDD is date and NNNNNN are numbers generated by the AES. Note: The ITN or FTR exemption number you submit in the ship request prints on the international shipping label. For Canada export shipments, it can be proof of report number (15-32 alphanumeric), summary proof of report number (7-32 alphanumeric) or exemption number (2 digit) based on the selected b13AFilingOption. Example:`98765432107654321` (POR number), `7654321` (summary POR number), and `02` (exemption number). For FTR exemption number you need provide a predefined value as NO_EEI_30_37_A.
`permitNumber`	String	No	This is a permit number. This field is applicable only to Canada export non-document shipments of any value to any destination. No special characters are allowed.
`incoterm`	String enumeration Values: `cpt` (carriage paid to; the seller is responsible for delivering the goods to the carrier, and the seller covers all costs until the goods are delivered to that carrier) `ddp` (delivery duty paid; the seller delivers the shipment in the foreign country to the named place and assumes all costs, risk, and responsibilities of the shipping process) `ddu` (delivery duty unpaid; the seller delivers the shipment in the foreign country to the named place, and the buyer is responsible for import duties, taxes, and customs clearance) `dap` (delivered at place; the seller arranges and pays for delivery of goods, and the buyer handles import clearance and unloading and in-country transport) `dpu` (delivered at place unloaded; the seller arranges and pays for delivery of goods and is responsible for unloading goods at the destination point) `exw` (ex works; the seller makes the product available at a specific location, and the buyer is responsible for all costs and risks associated with picking up the goods from the seller's location and transporting them to their final destination) `fca` (free carrier; the seller delivers the goods to a named place and is responsible for export clearance, and the buyer is then responsible for the shipment) `fob` (free on board; the seller is responsible for delivering goods to the port of shipment, loading them onto the designated vessel, and covering all associated costs until that point. Once the goods are on board, the responsibility for the rest of the journey, including shipping, customs clearance, and import duties, transfer to the buyer.)	Yes	The incoterm, or international commerce term, defines the delivery duty responsibility for buyers and sellers for any mode of transport; the default value is `ddp`.
`declarationStatement`	String Ex.: `I declare that the information provided is true and accurate. These commodities are licensed by the United States for export to the destination country.`	No	A customs declaration statement for the shipment that, if provided, will appear on generated commercial invoices
`taxIdentificationNumber`	String	No	The employer identification number (EIN) tax identification number of the shipper; you can find more details about this field in Tax Identification Number.
`customsItems`	Array of `customsItem` objects (see the table that follows)	Yes	Contains customs information for each item in the shipment

Customs items

The customsItems fields are included within customsInfo in the API call.

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`	Float	Yes	The weight of the item to report to customs in units of weight unit
`customsWeight.weightUnit`	String enumeration Values: `g` `kg` `lb` `oz`	Yes	The weight unit
`quantity`	Integer	Yes	The number of units of this customs item
`quantityUnitOfMeasurement`	String enumeration 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	The unique identifier for the product being shipped. This value must match the `productId` in `orderItemQuantities` for certain international carriers. See Carrier-Specific Requirements for details.
`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`	Array of `electronicExportInformation`objects (defined in the following table rows)	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)
`electronicExportCommodity Information.exportType`	String Values: `domestic` `foreign`	No, but required if including `electronicExportInformation`	The type of the export
`electronicExportCommodity Information .exportInformationCode`	String	No, but required if including `electronicExportInformation`	The 2-character export information code for the commodity
`electronicExportCommodity Information .scheduleBInformation`	Array of `scheduleBInformation` objects (defined in the following table rows)	No, but required if including `electronicExportInformation`	The Schedule B information for the commodity
`electronicExportCommodity Information.scheduleB Information .scheduleBNumber`	String	No, but required if including `electronicExportInformation`	The 10-digit Schedule B classification code for the item being exported
`electronicExportCommodity Information.scheduleB Information .scheduleBQuantity`	Integer	No, but required if including `electronicExportInformation`	The count of how many Schedule B units are in the shipment
`electronicExportCommodity Information.scheduleB Information .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`	No, but required if including `electronicExportInformation`	The unit of measure for the Schedule B quantity
`electronicExportCommodity Information.eccnNumber`	String	No, but required if including `electronicExportInformation`	The 5-digit product Export Control Classification Number (ECCN) number as issued by the Bureau of Industry and Security; the format is `#A###`.
`electronicExportCommodity Information .exportLicenseInformation`	Array of `exportLicenseInformation` objects (defined in the following table rows)	No, but required if including `electronicExportInformation`	The license information for the export
`electronicExportCommodity Information .exportLicenseInformation .licenseType`	String	No, but required if including `exportLicenseInformation`	The standard license type code as published by the U.S. government
`electronicExportCommodity Information .exportLicenseInformation .licenseExemptionCode`	String	No	The license exemption code, if the license type does not require a license number
`electronicExportCommodity Information .exportLicenseInformation .exportLicense`	Array of exportLicense objects (defined in the following table rows)	No	The export license, if the license type requires a valid license
`electronicExportCommodity Information .exportLicenseInformation .exportLicense .licenseNumber`	String	No, but required if including `exportLicense`	The license number
`electronicExportCommodity Information .exportLicenseInformation .exportLicense .licenseLineValue`	Integer	No, but required if including `exportLicense`	The export monetary amount allowed per license
`electronicExportCommodity Information .exportLicenseInformation .exportLicense .licenseExpiration`	Date-time	No, but required if including `exportLicense`	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: