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.

UPS item descriptions must be detailed

When shipping internationally with UPS, item descriptions provided in customsInfo.customsItems.commodityDescription must be meaningful product descriptions. UPS does not accept SKUs, part numbers, or other reference codes as valid item descriptions and may reject commercial invoices that contain them.

Use descriptive language that accurately identifies the goods, such as "cotton crew-neck t-shirt" rather than "SKU-12345".

Commercial invoice availability varies by carrier

For some carriers, the commercial invoice is managed entirely by the carrier and is not returned in the internationalDocuments field of the Shipium API response. This applies to the following supported carriers:

• Asendia
• Canada Post
• Landmark
• Passport, including Express and Expedited service methods
• Purolator E-Ship

For Global-e, behavior is conditional: if the commercial invoice is not electronically submitted, it is returned ininternationalDocuments. If electronically submitted (the default for most shipments), Global-e manages it independently and the field will be empty in the Shipium response.

To obtain a copy of the commercial invoice for shipments with these carriers, contact the carrier directly.

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@shipium.com",
              "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",
          "invoicePrePaidAmount": {
              "value": 25.50,
              "currencyCode": "USD"
          },
          "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"
                          }
                      }
                  }
              }
          ]
      }
  }
}

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.

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.

Customs info

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

Required fields

Conditional fields

Optional fields

Customs items

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

Required fields

Conditional fields

Optional fields

Resources

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

• Terms and Definitions

• Troubleshooting Guide

• Contact Shipium Support