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 electronic export information (EEI) is not required, when EEI is required, when an item needs separate export and import classification codes, when an item needs a CPSC certificate of compliance for import into the United States, and when you want to pass all customs details for a shipment.

Finally, common definitions associated with customs and international shipping are included.

Product identifiers for shipments to the European Union

For shipments to a European Union (EU) member state, send product identifiers on each item in customsInfo.customsItems. Carriers pass these identifiers to EU customs. A shipment without them can be held at customs, and some carriers reject the label request.

Field	What to send
`productId`	Your SKU for the item
`manufacturerProductId`	The manufacturer's own code for the product
`standardizedProductIds`	The item's barcode and its type (`GTIN`, `EAN`, `UPC`, or `ISBN`), when the item has a barcode
`businessIndicator`	`B2B` for a sale to a business, `B2C` for a sale to a consumer; this field is in `customsInfo`, not in each customs item

When you send these fields:

Send productId, manufacturerProductId, and standardizedProductIds on every customs item of every shipment to the European Union.
Include a type with every standardizedProductIds entry. An entry without a type may not reach the carrier.
If an item has no barcode, leave out standardizedProductIds. Don't send a placeholder value such as Y081, N/A, or NONE in its place.
Keep each productId to 20 characters or fewer and each manufacturerProductId to 32 or fewer, using letters and digits only. Some carriers accept shorter identifiers than others. Shipium doesn't shorten an identifier that's too long, so the label request can fail instead. If you shorten or reformat a SKU to fit, use the same value for productId in orderItemQuantities; see Customs Items to Order Item Quantity Mapping.
Send the manufacturer's code in manufacturerProductId, not your SKU, unless your company is the brand owner. If the product has no manufacturer code, send its barcode in manufacturerProductId as well as in standardizedProductIds. If the product has neither, leave out manufacturerProductId.
Set businessIndicator to B2B on every shipment sold to a business.

CPSC certificate of compliance for imports to the United States

The U.S. Consumer Product Safety Commission (CPSC) requires certificate of compliance data for many consumer products imported into the United States, such as children's products, toys, and sleepwear. To send certificate data for an item, add cpscCertificateOfCompliance to that item in customsInfo.customsItems. Shipium doesn’t require the certificate on a label request; whether CPSC requires certificate data for your product is set by CPSC regulations, not by Shipium.

Choose a filing mode in filingMode and send the fields for that mode:

Filing mode	When to use	Fields for this mode
`FULL`	You provide all certificate data in the request	`cpscProductId`, `applicableCpscRules`, `dateOfManufacture`, `manufacturerName`, `manufacturerAddress`, `lastComplianceTestingDate`, `testingLabName`, `testingLabAddress`, `testingLabContactInfo`, `importerRecordKeeperContact`
`REFERENCE`	The product's certificate is registered in the CPSC Product Registry	`registryProductId`, `registryVersionId`, `registryCertifierId`

When you send a certificate:

Send it on each customs item it applies to. Multi-parcel shipments use the same field.
Send only the fields for the filing mode you choose.
Use YYYY-MM-DD for dateOfManufacture and lastComplianceTestingDate.
Carriers receive only part of the certificate, and some carriers don’t receive it.
With some carriers, Shipium adds the applicable CPSC rules to the item’s description on customs paperwork, ahead of the item’s commodityDescription. Carriers limit how long that description can be, so a long list of rules can be cut off, and the rules can shorten or replace part of the commodityDescription.
The certificate is returned as sent in customsInfo in the API response, including its contact details.

You can also enter certificate data for an item in the Print Labels tool in the Shipium Console. See Print Labels.

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, and LaserShip Routed Delivery.

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
FlavorCloud

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 for a cross-border shipment with separate export and import codes

This is a sample cURL call for a shipment from the EU to the United States, where the origin and destination classify the item differently. The EU export declaration uses an 8-digit Combined Nomenclature code and the U.S. import entry uses a 10-digit Harmonized Tariff Schedule of the United States (HTSUS) code, so both are supplied.

{
    ...
    "labelParameters": {...},
    "shipmentParameters": {
     ...,
     "shipOption": "InternationalTwoToFiveDay",
      "customsInfo": {
          "totalCustomsValue": 89.00,
          "totalCustomsValueCurrency": "eur",
          "customsDescription": "Men's cotton t-shirts",
          "reasonForExport": "sale",
          "invoiceDate": "2026-09-23",
          "customsItems": [
              {
                  "customsValue": 44.50,
                  "customsValueCurrency": "eur",
                  "commodityDescription": "Men's t-shirt, 100% cotton",
                  "countryOfManufacture": "PT",
                  "customsWeight": {
                      "weight": 0.2,
                      "weightUnit": "kg"
                  },
                  "quantity": 2,
                  "quantityUnitOfMeasurement": "piece",
                  "harmonizedTariffNumber": "61091000",
                  "importHarmonizedTariffNumber": "6109100012"
              }
          ]
      }
  }
}

Sample API call for a shipment to the European Union

This is a sample cURL call for a consumer shipment from the United States to Germany. Each customs item carries product identifiers. The first item has a barcode; the second doesn't, so standardizedProductIds is left out.

{
    ...
    "labelParameters": {...},
    "shipmentParameters": {
     ...,
     "shipOption": "InternationalTwoToFiveDay",
      "customsInfo": {
          "totalCustomsValue": 62.00,
          "totalCustomsValueCurrency": "usd",
          "customsDescription": "Cotton t-shirt and ceramic mug",
          "reasonForExport": "sale",
          "invoiceDate": "2026-10-23",
          "businessIndicator": "B2C",
          "customsItems": [
              {
                  "customsValue": 28.00,
                  "customsValueCurrency": "usd",
                  "commodityDescription": "Women's t-shirt, 100% cotton",
                  "countryOfManufacture": "US",
                  "customsWeight": {
                      "weight": 0.4,
                      "weightUnit": "lb"
                  },
                  "quantity": 1,
                  "quantityUnitOfMeasurement": "piece",
                  "harmonizedTariffNumber": "610910",
                  "productId": "TSHIRTWMNBLUM",
                  "manufacturerProductId": "CT4471BLUM",
                  "standardizedProductIds": [
                      { "type": "GTIN", "value": "00012345678905" }
                  ]
              },
              {
                  "customsValue": 34.00,
                  "customsValueCurrency": "usd",
                  "commodityDescription": "Handmade stoneware coffee mug",
                  "countryOfManufacture": "US",
                  "customsWeight": {
                      "weight": 1.1,
                      "weightUnit": "lb"
                  },
                  "quantity": 1,
                  "quantityUnitOfMeasurement": "piece",
                  "harmonizedTariffNumber": "691200",
                  "productId": "MUGSTN12OZ",
                  "manufacturerProductId": "HSM12OZGRY"
              }
          ]
      }
  }
}

Sample API call for a CPSC-regulated import to the United States

This is a sample cURL call for a shipment from Canada to the United States of an item that needs a CPSC certificate of compliance. The certificate uses the FULL filing mode.

{
    ...
    "labelParameters": {...},
    "shipmentParameters": {
     ...,
     "shipOption": "InternationalTwoToFiveDay",
      "customsInfo": {
          "totalCustomsValue": 249.00,
          "totalCustomsValueCurrency": "usd",
          "customsDescription": "Child bicycle trailer",
          "reasonForExport": "sale",
          "invoiceDate": "2026-10-28",
          "customsItems": [
              {
                  "customsValue": 249.00,
                  "customsValueCurrency": "usd",
                  "commodityDescription": "Two-seat child bicycle trailer",
                  "countryOfManufacture": "CN",
                  "customsWeight": {
                      "weight": 28,
                      "weightUnit": "lb"
                  },
                  "quantity": 1,
                  "quantityUnitOfMeasurement": "piece",
                  "harmonizedTariffNumber": "8716400000",
                  "cpscCertificateOfCompliance": {
                      "filingMode": "FULL",
                      "cpscProductId": "EXK-TRL-2026",
                      "applicableCpscRules": ["16 CFR 1512"],
                      "dateOfManufacture": "2026-08-14",
                      "manufacturerName": "Example Kids Gear Co.",
                      "manufacturerAddress": {
                          "name": "Example Kids Gear Co.",
                          "street1": "100 Sample Road",
                          "city": "Ningbo",
                          "countryCode": "CN"
                      },
                      "lastComplianceTestingDate": "2026-07-30",
                      "testingLabName": "Sample Testing Lab",
                      "testingLabAddress": {
                          "name": "Sample Testing Lab",
                          "street1": "200 Test Avenue",
                          "city": "Shenzhen",
                          "countryCode": "CN"
                      },
                      "testingLabContactInfo": "[email protected]",
                      "importerRecordKeeperContact": "[email protected]"
                  }
              }
          ]
      }
  }
}

For the REFERENCE filing mode, the certificate carries only the CPSC Product Registry identifiers:

"cpscCertificateOfCompliance": {
    "filingMode": "REFERENCE",
    "registryProductId": "EXAMPLE-PRODUCT-001",
    "registryVersionId": "3",
    "registryCertifierId": "EXAMPLE-CERTIFIER-01"
}

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",
          "businessIndicator": "B2C",
          "europeanUnionInfo": {
              "vendorIossNumber": "123456789012",
              "vendorIossAddress": {
                  "name": "Acme Fiscal Rep BV",
                  "street1": "Keizersgracht 123",
                  "city": "Amsterdam",
                  "postalCode": "1015 CJ",
                  "countryCode": "NL"
              }
          },
          "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",
          "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",
                  "importHarmonizedTariffNumber": "9876549900",
                  "productId": "ABC123",
                  "commodityPartNumber": "12345",
                  "manufacturerProductId": "MPN77BXL",
                  "standardizedProductIds": [
                      { "type": "GTIN", "value": "0123456789012" }
                  ],
                  "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",                   // required for UPS and FedEx; not strictly required for USPS
          "invoiceDate": "2022-06-13",                 // required for UPS; not required for FedEx
          "customsItems": [
              {
                  "customsValue": 18.31,
                  "customsValueCurrency": "usd",
                  "commodityDescription": "9 mm steel screws",
                  "countryOfManufacture": "US",        // required for UPS and FedEx; not strictly required for USPS
                  "customsWeight": {
                      "weight": 4,
                      "weightUnit": "lb"
                  },
                  "quantity": 3,
                  "quantityUnitOfMeasurement": "box"   // required for UPS; not required for FedEx
              }
          ]
      }
  }
}

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.

Request field	Details
`shipOption`	Type: String (enumeration) Values: `International24Hour`, `InternationalOneToThreeDayEarly`, `InternationalOneToThreeDay`, `InternationalTwoToFiveDay`, `InternationalTwoToTenDay`, `InternationalOneToTwoWeek`, `InternationalOneToFourWeek` Description: 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.

Required fields

Request field	Details
`totalCustomsValue`	Type: Float Description: The total customs value of the package in total customs value currency units
`totalCustomsValueCurrency`	Type: String Example: `usd` Description: The currency to use for the package value in the `totalCustomsValue` field; this must be a valid ISO 4217 currency code.
`customsDescription`	Type: String Example: `9 mm steel screws` Description: A shipment-level summary of the goods being shipped; this is a general description of the overall shipment, not the per-item description that prints on the commercial invoice and customs forms. Those per-item descriptions come from `commodityDescription` in `customsItems`.
`reasonForExport`	Type: String (enumeration) Values: `sale`, `gift`, `sample`, `returns`, `personal_effects` Description: The reason to export an international shipment
`invoiceDate`	Type: LocalDate Description: Date when the invoice was created; ideally, this is the same as the ship date.
`incoterm`	Type: String (enumeration) Values: `cpt` (carriage paid to), `ddp` (delivery duty paid), `ddu` (delivery duty unpaid), `dap` (delivered at place), `dpu` (delivered at place unloaded), `exw` (ex works), `fca` (free carrier), `fob` (free on board) Description: 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`.
`customsItems`	Type: Array Description: Contains customs information for each item in the shipment. See the Customs Items tables for details.

Conditional fields

Request field	Details
`ultimateConsigneeAddress`	Type: Object Condition: Required fields within this object vary by carrier. Description: 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.countryCode`	Type: String Condition: Required if `ultimateConsigneeAddress` is provided; required fields within this object vary by carrier. Description: The ISO 3166-1 country code for the address
`ultimateConsigneeAddress.postalCode`	Type: String Condition: Required if `ultimateConsigneeAddress` is provided; required fields within this object vary by carrier. Description: A country-appropriate postal code for the address
`ultimateConsigneeAddress.phoneNumber`	Type: String Condition: Some carriers require a phone number. Description: The phone number of the contact
`europeanUnionInfo.vendorIossAddress.postalCode`	Type: String Condition: Required if `vendorIossAddress` is provided Description: A country-appropriate postal code for the address
`europeanUnionInfo.vendorIossAddress.countryCode`	Type: String Condition: Required if `vendorIossAddress` is provided Description: The ISO 3166-1 country code for the address
`b13AFilingOption`	Type: String (enumeration) Values: `NOT_REQUIRED`, `MANUALLY_ATTACHED`, `FILED_ELECTRONICALLY`, `SUMMARY_REPORTING`, `CARRIER_TO_STAMP`, `UNKNOWN` Condition: 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 Description: Specify the filing option being exercised.
`electronicExportInformation.exportDate`	Type: String (date-time) Condition: Required if including EEI Description: The date the goods will be leaving the country in ISO 8601 format
`electronicExportInformation.pointOfOrigin`	Type: String Condition: Required if including EEI Description: The 2-character state abbreviation from which the goods were shipped

Optional fields

Field	Details
`invoiceNumber`	Type: String Description: The Commercial Invoice number, if the Commercial Invoice was generated by your organization
`europeanUnionInfo.vendorIossNumber`	Type: String Description: 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.name`	Type: String Description: The name associated with the address
`ultimateConsigneeAddress .phoneNumberCountryCode`	Type: String Description: The country code of the phone number of the contact
`ultimateConsigneeAddress.emailAddress`	Type: String Description: The email address of the contact
`ultimateConsigneeAddress.company`	Type: String Description: The company name for the address
`ultimateConsigneeAddress.street1`	Type: String Description: The first address line
`ultimateConsigneeAddress.street2`	Type: String Description: The second address line
`ultimateConsigneeAddress.city`	Type: String Description: The name of the city for the address
`ultimateConsigneeAddress.state`	Type: String Description: The name of the state for the address
`ultimateConsigneeAddress.addressType`	Type: String (enumeration) Values: `commercial` or `residential` Description: The type of location for this address
`ultimateConsigneeAddress .addressLineComponents`	Type: Object Description: The address line components for the address, used for some international shipments. The `street1` and `street2` fields should not be included if using `addressLineComponents`, or an error will be returned. Preferred for Mexican addresses. You can find out more about Mexican addresses in Non-U.S. Address Formats.
`ultimateConsigneeType`	Type: String (enumeration) Values: `direct_consumer`, `government_entity`, `reseller` Description: The type of the ultimate consignee, the person or company receiving the shipment; if no value is sent, it will default to `direct_consumer`.
`soldTo`	Type: Object Description: The party who purchased the goods; this may differ from both the recipient and the importer of record. Some carriers, such as FedEx, require this information for certain customs filings. See Broker & Importer of Record for more details on customs parties.
`soldTo.address`	Type: Object Description: The address of the sold-to party
`soldTo.address.name`	Type: String Description: The name associated with the address
`soldTo.address.company`	Type: String Description: The company name for the address
`soldTo.address.street1`	Type: String Description: The first address line
`soldTo.address.street2`	Type: String Description: The second address line
`soldTo.address.city`	Type: String Description: The name of the city for the address
`soldTo.address.state`	Type: String Description: The 2-letter abbreviation of the state for the address
`soldTo.address.postalCode`	Type: String Description: A country-appropriate postal code for the address
`soldTo.address.countryCode`	Type: String Description: The ISO 3166-1 country code for the address
`soldTo.address.phoneNumber`	Type: String Description: The phone number of the contact
`soldTo.address.phoneNumberCountryCode`	Type: String Description: The country code of the phone number of the contact
`soldTo.address.emailAddress`	Type: String Description: The email address of the contact
`soldTo.address.addressType`	Type: String (enumeration) Values: `commercial` or `residential` Description: The type of location for this address
`soldTo.taxIdentificationNumbers`	Type: Array Description: Array of tax identification number objects for the sold-to party
`soldTo.taxIdentificationNumbers.tinType`	Type: String (enumeration) Values: `business_national`, `business_state`, `business_union`, `federal`, `personal_national`, `personal_state` Description: The type of tax identification number
`soldTo.taxIdentificationNumbers.tinNumber`	Type: String Description: The tax identification number value
`soldTo.taxIdentificationNumbers .tinIssuingCountry`	Type: String Description: The ISO 3166-1 country code of the country that issued the tax identification number
`soldTo.accountNumber`	Type: String Description: The carrier account number information for the sold-to party
`aesInternalTransactionNumber`	Type: String Description: The number received if the Electronic Export Information (EEI) was filed and has been accepted in the Automated Export System (AES)
`electronicExportInformation`	Type: Array Description: 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)
`exportComplianceStatement`	Type: String Example: `AESX20220714987654` Description: 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. 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`.
`permitNumber`	Type: String Description: 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.
`invoicePrePaidAmount`	Type: Object Description: The prepaid shipping or handling charges for the shipment, used to include freight costs on the commercial invoice. Currently supported for DHL Express DDP shipments. See DHL for carrier-specific configuration and requirements.
`invoicePrePaidAmount.value`	Type: Number (float) Description: The monetary amount of the prepaid shipping or handling charges
`invoicePrePaidAmount.currencyCode`	Type: String Description: The ISO 4217 currency code for the prepaid amount
`declarationStatement`	Type: String Example: `I declare that the information provided is true and accurate. These commodities are licensed by the United States for export to the destination country.` Description: A customs declaration statement for the shipment that, if provided, will appear on generated commercial invoices
`taxIdentificationNumber`	Type: String Description: The employer identification number (EIN) tax identification number of the shipper; you can find more details about this field in Tax Identification Number.
`businessIndicator`	Type: String (enumeration) Values: `B2C`, `B2B` Description: Whether the sale is to a consumer (B2C) or to a business (B2B). For shipments to the European Union, set `B2B` on every shipment sold to a business; if you leave it out, the shipment is treated as a consumer (B2C) sale. See Product Identifiers for Shipments to the European Union.
`europeanUnionInfo.vendorIossAddress`	Type: Object Description: The name and address of the IOSS VAT registrant, provided alongside `vendorIossNumber`. It accepts the same sub-fields as other Shipium customs addresses, listed below. `countryCode` and `postalCode` are required when `vendorIossAddress` is provided.
`europeanUnionInfo.vendorIossAddress.name`	Type: String Description: The name of the IOSS registrant
`europeanUnionInfo.vendorIossAddress.street1`	Type: String Description: The first address line
`europeanUnionInfo.vendorIossAddress.street2`	Type: String Description: The second address line
`europeanUnionInfo.vendorIossAddress.city`	Type: String Description: The name of the city for the address
`europeanUnionInfo.vendorIossAddress.state`	Type: String Description: The name of the state or region for the address
`europeanUnionInfo.vendorIossAddress.company`	Type: String Description: The company name for the address
`europeanUnionInfo.vendorIossAddress.phoneNumber`	Type: String Description: The phone number of the contact
`europeanUnionInfo.vendorIossAddress .phoneNumberCountryCode`	Type: String Description: The country code of the phone number of the contact
`europeanUnionInfo.vendorIossAddress.emailAddress`	Type: String Description: The email address of the contact
`europeanUnionInfo.vendorIossAddress.addressType`	Type: String (enumeration) Values: `commercial`, `residential` Description: The type of location for this address
`europeanUnionInfo.vendorIossAddress .addressLineComponents`	Type: Object Description: The address line components for the address, used for some international shipments. Do not include `street1` or `street2` if using `addressLineComponents`, or an error will be returned. See Non-U.S. Address Formats for details.

📘
Understanding soldTo vs. importerOfRecord
The soldTo field represents the party who purchased the goods, while importerOfRecord represents the party legally responsible for customs compliance. These may be the same entity or different parties depending on your shipping scenario. For detailed guidance on when to use each field, see Broker & Importer of Record.

Customs items

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

📋
customsDescription and commodityDescription serve different roles
customsDescription is a shipment-level summary of the goods. The detailed, per-item descriptions that print on the commercial invoice and customs forms come from commodityDescription in each customsItems entry. To control how an item reads on customs paperwork, you'll set that item's commodityDescription. Carriers enforce their own character limits on this per-item description. Keeping each commodityDescription meaningful and within the smallest limit among the carriers you route to, with the most important detail first, is best practice. With some carriers, an item’s CPSC rules print ahead of its commodityDescription; see CPSC Certificate of Compliance for Imports to the United States.

📋
harmonizedTariffNumber and importHarmonizedTariffNumber classify the same item for different countries
harmonizedTariffNumber is the code the origin country's export declaration requires, such as a U.S. Schedule B code, and it is required for each customs item. importHarmonizedTariffNumber is the code the destination country's import entry requires, such as a Harmonized Tariff Schedule of the United States (HTSUS) code into the United States or an Integrated Tariff of the European Union (TARIC) code into the EU, and it is optional.
The first six digits of a Harmonized System code are consistent across countries; digits beyond that are country-specific. When the origin and destination classify an item differently past those first six digits, supply both fields.
Neither field depends on the other, and you can supply either one with any carrier. Where a carrier accepts only one commodity code, harmonizedTariffNumber is the code sent.

Required fields

Request field	Details
`customsValue`	Type: Float Description: The value of each individual item to report to customs in customs value currency
`customsValueCurrency`	Type: String Description: The ISO 4217 currency code representing the `customsValue`
`commodityDescription`	Type: String Description: A per-item description of the product provided to customs; this is the description that appears on the commercial invoice and customs forms. Carriers enforce their own character limits on this field. Keeping each description meaningful and within the smallest limit among the carriers you route to is best practice. With some carriers, an item’s CPSC rules print ahead of this description; see CPSC Certificate of Compliance for Imports to the United States.
`countryOfManufacture`	Type: String Description: The ISO 3166-1 country code
`customsWeight.weight`	Type: Float Description: The weight of the item to report to customs in units of weight unit
`customsWeight.weightUnit`	Type: String (enumeration) Values: `g`, `kg`, `lb`, `oz` Description: The weight unit
`quantity`	Type: Integer (int32) Description: The number of units of this customs item
`quantityUnitOfMeasurement`	Type: String (enumeration) Values: `bag`, `barrel`, `box`, `case_of_goods`, `container`, `crate`, `cylinder`, `envelope`, `pallet`, `piece`, `roll`, `tube` Description: The unit of measurement of the item
`harmonizedTariffNumber`	Type: String Example: `9876543210` Description: The 6- to 15-digit Harmonized System Tariff classification code for the origin country's export declaration, such as an 8-digit EU code or a U.S. Schedule B code. Where the destination country requires a different code, supply `importHarmonizedTariffNumber` as well. If you file electronic export information, supply your Schedule B code here as well as in `scheduleBInformation.scheduleBNumber`.

Conditional fields

Request field	Details
`electronicExportCommodityInformation .exportType`	Type: String (enumeration) Values: `domestic` or `foreign` Condition: Required if including `electronicExportInformation` Description: The type of the export
`electronicExportCommodityInformation .exportInformationCode`	Type: String Condition: Required if including `electronicExportInformation` Description: The 2-character export information code for the commodity
`electronicExportCommodityInformation .scheduleBInformation`	Type: Array Condition: Required if including `electronicExportInformation` Description: The Schedule B information for the commodity
`electronicExportCommodityInformation .scheduleBInformation.scheduleBNumber`	Type: String Condition: Required if including `electronicExportInformation` Description: The 10-digit Schedule B classification code for the item being exported; this code feeds the electronic export information filing. Supply the same code in `harmonizedTariffNumber` for the customs declaration.
`electronicExportCommodityInformation .scheduleBInformation.scheduleBQuantity`	Type: Integer (int32) Condition: Required if including `electronicExportInformation` Description: The count of how many Schedule B units are in the shipment
`electronicExportCommodityInformation .scheduleBInformation .scheduleBUnitOfMeasurement`	Type: String (enumeration) 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` Condition: Required if including `electronicExportInformation` Description: The unit of measure for the Schedule B quantity
`electronicExportCommodityInformation .eccnNumber`	Type: String Condition: Required if including `electronicExportInformation` Description: The 5-digit product Export Control Classification Number (ECCN) number as issued by the Bureau of Industry and Security; the format is `#A###`.
`electronicExportCommodityInformation .exportLicenseInformation`	Type: Array Condition: Required if including `electronicExportInformation` Description: The license information for the export
`electronicExportCommodityInformation .exportLicenseInformation.licenseType`	Type: String Condition: Required if including `exportLicenseInformation` Description: The standard license type code as published by the U.S. government
`electronicExportCommodityInformation .exportLicenseInformation.exportLicense .licenseNumber`	Type: String Condition: Required if including `exportLicense` Description: The license number
`electronicExportCommodityInformation .exportLicenseInformation.exportLicense .licenseLineValue`	Type: Integer (int32) Condition: Required if including `exportLicense` Description: The export monetary amount allowed per license
`electronicExportCommodityInformation .exportLicenseInformation.exportLicense .licenseExpiration`	Type: String (date-time) Condition: Required if including `exportLicense` Description: The license expiration date in ISO 8601 format

Optional fields

Request field	Details
`productId`	Type: String Description: The merchant SKU for the product, declared to customs. This value must match the `productId` in `orderItemQuantities` for certain international carriers; see Carrier-Specific Requirements. For shipments to the European Union, send this on every customs item, 20 characters or fewer; see Product Identifiers for Shipments to the European Union.
`commodityPartNumber`	Type: String Description: The part number or reference number for the product
`marksAndNumbers`	Type: String Description: Any special marks, codes, and numbers that may identify the package
`manufacturerProductId`	Type: String Description: The manufacturer's product identifier for the item, a maker-assigned code; use `standardizedProductIds` for standardized barcodes such as GTIN or UPC. For shipments to the European Union, send this on every customs item, 32 characters or fewer; see Product Identifiers for Shipments to the European Union.
`standardizedProductIds`	Type: Array Description: A list of standardized product identifiers (barcodes) for the item; if the item has no barcode, leave this out rather than sending a placeholder value.
`standardizedProductIds.type`	Type: String (enumeration) Values: `GTIN`, `EAN`, `UPC`, `ISBN` Description: The type of standardized product identifier; include a type with every entry.
`standardizedProductIds.value`	Type: String Description: The standardized product identifier value
`importHarmonizedTariffNumber`	Type: String Example: `9876549900` Description: The classification code for the destination country's import entry, such as a 10-digit HTSUS code into the United States or a 10-digit TARIC code into the EU; independent of `harmonizedTariffNumber`
`cpscCertificateOfCompliance`	Type: Object Description: U.S. Consumer Product Safety Commission (CPSC) certificate of compliance data for the item, for import into the United States. See CPSC Certificate of Compliance for Imports to the United States.
`cpscCertificateOfCompliance.filingMode`	Type: String (enumeration) Values: `FULL`, `REFERENCE` Description: How the certificate is provided: `FULL` for all certificate data in the request, `REFERENCE` for a certificate registered in the CPSC Product Registry. Include it with every certificate.
`cpscCertificateOfCompliance.cpscProductId`	Type: String Description: The product identifier on the certificate; separate from the item's `productId`. Used with `FULL`.
`cpscCertificateOfCompliance.applicableCpscRules`	Type: Array of strings Example: `["16 CFR 1512"]` Description: The CPSC rules the product is certified to. Used with `FULL`. With some carriers, these rules are added ahead of the item’s description on customs paperwork. A long list can be cut off, and the rules can shorten the item’s `commodityDescription`.
`cpscCertificateOfCompliance.dateOfManufacture`	Type: String (date) Example: `2026-08-14` Description: The date the product was manufactured, in `YYYY-MM-DD` format. Used with `FULL`.
`cpscCertificateOfCompliance.manufacturerName`	Type: String Description: The name of the manufacturer. Used with `FULL`.
`cpscCertificateOfCompliance.manufacturerAddress`	Type: Object Description: The manufacturer's address. Accepts `name`, `company`, `street1`, `street2`, `city`, `state`, `postalCode`, `countryCode`, `phoneNumber`, `phoneNumberCountryCode`, and `emailAddress`. Used with `FULL`.
`cpscCertificateOfCompliance.lastComplianceTestingDate`	Type: String (date) Example: `2026-07-30` Description: The date of the product's most recent compliance testing, in `YYYY-MM-DD` format. Used with `FULL`.
`cpscCertificateOfCompliance.testingLabName`	Type: String Description: The name of the testing lab. Used with `FULL`.
`cpscCertificateOfCompliance.testingLabAddress`	Type: Object Description: The testing lab's address. Accepts the same sub-fields as `manufacturerAddress`. Used with `FULL`.
`cpscCertificateOfCompliance.testingLabContactInfo`	Type: String Description: Contact information for the testing lab, such as a phone number or email address. Used with `FULL`.
`cpscCertificateOfCompliance.importerRecordKeeperContact`	Type: String Description: Contact information for the importer or the party keeping the certificate records. Used with `FULL`.
`cpscCertificateOfCompliance.registryProductId`	Type: String Description: The product identifier in the CPSC Product Registry. Used with `REFERENCE`.
`cpscCertificateOfCompliance.registryVersionId`	Type: String Description: The certificate version identifier in the CPSC Product Registry. Used with `REFERENCE`.
`cpscCertificateOfCompliance.registryCertifierId`	Type: String Description: The certifier identifier in the CPSC Product Registry. Used with `REFERENCE`.
`electronicExportCommodityInformation`	Type: Array Description: 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)
`electronicExportCommodityInformation .exportLicenseInformation.licenseExemptionCode`	Type: String Description: The license exemption code, if the license type does not require a license number
`electronicExportCommodityInformation .exportLicenseInformation.exportLicense`	Type: Array Description: The export license, if the license type requires a valid license

Resources

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