Customs API overview

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 documentation includes example client uniform resource locator (cURL) application programming interface (API) calls as well as a sample JavaScript Object Notation (JSON) response 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]",
              "company": null,
              "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"
          },
          "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
      }
    ]
    ....,
    ....,
  },
  ....,
  ....
}

Specify incoterms

When shipping internationally, there are a variety of different pre-defined commercial terms that can be associated with a shipment, defining exporter and importer responsibilities with regard to costs and risks associated with a given shipment. These are known as incoterms and are represented by 3-letter codes associated with each defined set of terms. For more information about incoterms, the Wikipedia incoterms covers this topic in detail.

When producing a shipment using the Shipium carrier selection and label system, you can specify an "incoterms" element as a child of the "customsInfo" element to specify a supported set of incoterms for that shipment to be communicated to the eventual carrier. This may also impact which set of carriers is eligible for the shipment since not all of your carriers may support all incoterms.

Default behavior

By default, the Shipium API assumes that international shipments are being shipped Delivery Duty Paid, or DDP, and if no incoterms element is provided, that is what will be assumed. Passing no "incoterms" element is the equivalent of passing "incoterms": "DDP".

Supported incoterms

Shipium supports the following set of incoterms for shipments. The table below shows the incoterms name, the 3-letter code, and a very brief description of the commercial terms specified by that incoterms value.

Incoterms name	Incoterms 3-letter code	Incoterms overview
Delivery Duty Paid	DDP	Duties are calculated and paid upfront by the shipper via the carrier. This is the Shipium default behavior.
Delivered at Place Delivery Duty Unpaid	DAP or DDU	Duties are not covered by the shipper, but instead are the responsibility of the receiving party. Note that DDU is the older term specified in Incoterms 2000 and DAP is the newer term from Incoterms 2010. Specifying DAP or DDU will have the same behavior.
Delivery at Place Unloaded	DPU	The seller delivers the goods at the disposal of the buyer after they have been unloaded from the arriving means of transport. (If you don't know what this means, you probably should not be using it.)
Free Carrier	FCA	The seller makes the goods available to a carrier that has been stipulated by the buyer, who is also responsible for coordinating the export clearance. (If you don't know what this means, you probably should not be using it.)

Incoterms API call sample

Using a subset of the example above, you can see an example of DAP being specified in the incoterms field in the example below.

{
    ...
    "labelParameters": {...},
    "shipmentParameters": {
     ...,
     "shipOption": "InternationalTwoToFiveDay",
      "customsInfo": {
          "incoterms": "DAP",
          "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]",
              "company": null,
              "street1": "123 Test",
              "city": "St. John's",
              "state": "NL",
              "countryCode": "CA",
              "postalCode": "A1A 2H4",
              "addressType": "residential"
          },
          ...
      }
      ...
}

Definitions

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

ShipOption

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

CustomsInfo

Field	Type	Required	Description
`ultimateConsigneeType`	Enum: `direct_consumer` `government_entity` - `reseller`	No	The type of the ultimate consignee. If no value is sent, it will default to `direct_consumer`
ultimateConsigneeAddress	Address (see below)	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	Yes	The ISO-4217 currency code representing the `totalCustomsValue`
totalCustomsValue	Float	Yes	The customs value of the shipment in `totalCustomsValueCurrency`
reasonForExport	Enum: `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	List of CustomsItemData (see below)	Yes	Contains customs information for each item in the shipment
customsDescription	String	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)

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

ElectronicExportInformation

Field	Type	Required	Description
exportDate	DateTime	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

CustomsItemData

Field	Type	Required	Description
customsValue	Float	Yes	The value of each individual item to report to customs in customsValueCurrency
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	int	Yes	The number of units of this customs item
quantityUnitOfMeasurement	Enum: `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-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
electronicExportCommodityInformation	`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 weightUnit
weightUnit	Enum: `g` `kg` `lb` `oz`	Yes	The weight unit

ElectronicExportCommodityInformation

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

ScheduleBInformation

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

ExportLicenseInformation

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

ExportLicense

Field	Type	Required	Description
licenseNumber	String	Yes	The license number
licenseLineValue	int	Yes	The export monetary amount allowed per license
licenseExpiration	DateTime	Yes	The license expiration date in ISO-8601 format

FAQ

Q: Can I include a desired delivery date (DDD) in addition to passing a ship option when using the all-in-one shipment and label method?

A: Yes. For example, shipOption: standard, desiredDeliveryDate: 2023-11-15 limits the carrier selection search to only those methods that are marked as standard and for which the DDD of 2023-11-15 can be met. If the DDD of 2023-11-15 cannot be met, Shipium will return the cheapest service method on 2023-11-16, and so on.