1. ShipEngine
  2. ShipEngine Help Center
  3. International

Customs Form Item Limits

Avatar

ShipEngine Content Team

Updated

The limits on how many items you can specify in the customs form will vary by carrier. Though it does not cover every carrier, here you can find those details, plus API References and code samples for several major carriers.

Customs Line Item Limits by Carrier API and Service

This table provides a high-level comparison of the maximum number of customs line items allowed by major shipping carriers for their primary electronic shipping solutions. These limits are critical for businesses shipping internationally with detailed commercial invoices.

USPS Customs Line Item Limits

This table does not mention USPS specifics, but USPS has a limit of 30 line items in a customs form.

Carrier

API / Service

Max Line Items

API Object Name

UPS

Shipping API (REST/JSON)

50

Product

FedEx

REST API

99

commodities

FedEx

Web Services (SOAP/XML)

99

Commodity

GlobalPost

(via Auctane/ShipStation API)

255

customsItems

DHL

eCommerce Solutions API (for Europe)

99

items

DHL

eCommerce Solutions Americas API (for US)

99

commodities

DHL

Express API (MyDHL API)

999

exportLineItems

Key Takeaways:

  • DHL Express offers the highest capacity by a significant margin, supporting up to 999 line items, making it ideal for large, complex B2B shipments.

  • GlobalPost provides a generous limit of 255 items, accommodating the most diverse e-commerce inventories.

  • FedEx and both regional DHL eCommerce APIs (Americas and Europe) share a standard limit of 99 items.

  • UPS has the most restrictive limit at 50 items, which should be a key consideration for shippers with a high diversity of goods per package.

UPS

The UPS Shipping API allows a maximum of 50 customs line items per shipment.

These line items are referred to as Product objects within the InternationalForms section of a shipment request. They are used to generate the Commercial Invoice for customs clearance, often as part of UPS's Paperless Invoice service.

API Reference

The definitive source for this information is the official UPS Developer Portal for the Shipping API. The limitation is defined in the specification for the Product array within the ShipmentRequest object.

  • Primary Documentation: UPS Shipping API Reference

  • Specific Location: In the API documentation, navigate the request body structure to ShipmentRequest > Shipment > InternationalForms > Product. The documentation for the Product array will indicate its maximum occurrences ("maxItems: 50").

Sample JSON Request

Below is a sample JSON snippet demonstrating how to structure a request with multiple customs line items (Product). This is not a complete request but focuses on the relevant InternationalForms section.

JSON

{
  "ShipmentRequest": {
    "Shipment": {
      "Description": "Assorted Electronic Components",
      "Shipper": {
        /* ... Shipper Details ... */
      },
      "ShipTo": {
        /* ... ShipTo Details ... */
      },
      "PaymentDetails": {
        /* ... Payment Details ... */
      },
      "Service": {
        "Code": "08",
        "Description": "UPS Expedited"
      },
      "Package": [
        {
          "Packaging": {
            "Code": "02",
            "Description": "Customer Supplied Package"
          },
          "PackageWeight": {
            "UnitOfMeasurement": {
              "Code": "KGS"
            },
            "Weight": "2.5"
          }
        }
      ],
      "InternationalForms": {
        "FormType": "01",
        "InvoiceNumber": "INV123456789",
        "InvoiceDate": "20250915",
        "ReasonForExport": "SALE",
        "CurrencyCode": "USD",
        "InvoiceLineTotal": {
          "MonetaryValue": "350.00"
        },
        "Product": [ // This is the array for your customs line items (max 50).
          {
            "Description": "16GB DDR5 RAM Module",
            "CommodityCode": "847330",
            "OriginCountryCode": "TW",
            "Unit": {
             "Number": "10",
              "UnitOfMeasurement": {
                "Code": "PCS"
              },
              "Value": "25.00"
            },
            "ProductWeight": {
              "UnitOfMeasurement": {
                "Code": "KGS"
              },
              "Weight": "0.1"
            }
          },
          {
            "Description": "2TB NVMe SSD",
            "CommodityCode": "852351",
            "OriginCountryCode": "KR",
            "Unit": {
              "Number": "2",
              "UnitOfMeasurement": {
                "Code": "PCS"
              },
              "Value": "50.00"
            },
            "ProductWeight": {
              "UnitOfMeasurement": {
                "Code": "KGS"
              },
              "Weight": "0.2"
            }
          }
        ]
      }
    },
    "LabelSpecification": {
      /* ... Label Details ... */
    }
  }
}

Key Fields in the Product Object

  • Description: A detailed description of the item.

  • CommodityCode: The Harmonized Tariff Schedule (HTS) code for the product.

  • OriginCountryCode: The two-letter country code where the item was manufactured.

  • Unit: An object containing the quantity (Number), value per unit (Value), and unit of measurement (Code, e.g., "PCS" for pieces).

  • ProductWeight: The weight of a single unit of the product.

FedEx

For FedEx, the limit is consistent across both their new REST API and the legacy Web Services (SOAP) API.

The maximum number of customs line items (referred to as Commodities in the FedEx API) allowed per shipment is 99.

FedEx REST API (New)

The modern FedEx REST APIs are JSON-based and are the recommended integration path for new development.

  • Maximum Line Items: 99

  • API Object: The line items are provided in the commodities array, which is part of the customsClearanceDetail object

API Reference

The official documentation and API specification can be found on the FedEx Developer Portal.

  • Primary Documentation: FedEx Ship API Documentation

  • Specific Location: In the API reference for the "Create Shipment" endpoint, navigate the request body schema to: requestedShipment > customsClearanceDetail > commodities. The documentation specifies a maximum of 99 items for this array.

Sample JSON Request

This is a partial JSON payload focusing on the customsClearanceDetail section to illustrate how to structure multiple commodities.

JSON

{  
    "requestedShipment": {
        "shipper": {
      /* ... Shipper Details ... */
    },    "recipients": [
      {
        /* ... Recipient Details ... */
      }
    ],
    "shipDatestamp": "2025-09-16",
    "serviceType": "INTERNATIONAL_PRIORITY",
    "packagingType": "YOUR_PACKAGING",
    "pickupType": "USE_SCHEDULED_PICKUP",
    "blockInsightVisibility": false,
    "shippingChargesPayment": {
      "paymentType": "SENDER"
    },
    "customsClearanceDetail": {
     "dutiesPayment": {
        "paymentType": "SENDER"
      },
      "isDocumentOnly": false,
      "commodities": [ // This is the array for your customs line items (max 99).
        {
          "description": "Men's Cotton T-Shirt",
          "countryOfManufacture": "VN",
          "quantity": 50,
          "quantityUnits": "EA",
          "unitPrice": {
            "amount": 15,
            "currency": "USD"
          },
          "customsValue": {
            "amount": 750,
            "currency": "USD"
          },
          "harmonizedCode": "610910",
          "weight": {
            "units": "KG",
            "value": 10
          }
        },
        {
          "description": "Leather Belt",
          "countryOfManufacture": "IT",
          "quantity": 20,
          "quantityUnits": "EA",
          "unitPrice": {
            "amount": 40,
            "currency": "USD"
          },
          "customsValue": {
            "amount": 800,
            "currency": "USD"
          },
          "harmonizedCode": "420330",
          "weight": {
           "units": "KG",
            "value": 4
          }
        }
      ]
    },
    "requestedPackageLineItems": [
      {        "weight": {
          "units": "KG",
          "value": 14
        }
      }
    ]
  },
  "labelResponseOptions": "URL_ONLY",
  "accountNumber": {
    "value": "YourAccountNumber"
  }
}

FedEx Web Services / SOAP API (Legacy)

This is the older XML-based API. While still functional, FedEx encourages users to migrate to the REST API.

  • Maximum Line Items: 99

  • API Object: The line items are defined by repeating the Commodity element within the CustomsClearanceDetail block.

API Reference

Documentation for the legacy APIs is often found in downloadable PDF developer guides.

  • Primary Documentation: FedEx Web Services Documentation (Look for the Ship Service WSDL and its corresponding developer guide).

  • Specific Location: In the ProcessShipmentRequest WSDL, the CustomsClearanceDetail element contains a Commodities element with a maxOccurs attribute of "99".

Sample XML Request

This is a partial SOAP/XML request snippet focusing on the CustomsClearanceDetail section. Note the verbosity compared to JSON.

XML

<v18:RequestedShipment>
    <v18:CustomsClearanceDetail>
        <v18:DutiesPayment>
            <v18:PaymentType>SENDER</v18:PaymentType>
            </v18:DutiesPayment>
        <v18:DocumentContent>NON_DOCUMENTS</v18:DocumentContent>
        <v18:CustomsValue>
            <v18:Currency>USD</v18:Currency>
            <v18:Amount>1550.00</v18:Amount>
        </v18:CustomsValue>         

        <v18:Commodities>
            <v18:Name>Men's Cotton T-Shirt</v18:Name>
            <v18:NumberOfPieces>50</v18:NumberOfPieces>
            <v18:Description>Men's Cotton T-Shirt</v18:Description>
            <v18:CountryOfManufacture>VN</v18:CountryOfManufacture>
            <v18:Weight>
                <v18:Units>KG</v18:Units>
                <v18:Value>10.0</v18:Value>
            </v18:Weight>
            <v18:Quantity>50</v18:Quantity>
            <v18:QuantityUnits>EA</v18:QuantityUnits>
            <v18:UnitPrice>
                <v18:Currency>USD</v18:Currency>
                <v18:Amount>15.00</v18:Amount>
            </v18:UnitPrice>
            <v18:CustomsValue>
                <v18:Currency>USD</v18:Currency>
                <v18:Amount>750.00</v18:Amount>
            </v18:CustomsValue>
            <v18:HarmonizedCode>610910</v18:HarmonizedCode>
        </v18:Commodities>
        <v18:Commodities>
            <v18:Name>Leather Belt</v18:Name>
            <v18:NumberOfPieces>20</v18:NumberOfPieces>
            <v18:Description>Leather Belt</v18:Description>
            <v18:CountryOfManufacture>IT</v18:CountryOfManufacture>
            <v18:Weight>
                <v18:Units>KG</v18:Units>
                <v18:Value>4.0</v18:Value>
            </v18:Weight>
            <v18:Quantity>20</v18:Quantity>
            <v18:QuantityUnits>EA</v18:QuantityUnits>
            <v18:UnitPrice>
                <v18:Currency>USD</v18:Currency>
                <v18:Amount>40.00</v18:Amount>
            </v18:UnitPrice>
            <v18:CustomsValue>
                <v18:Currency>USD</v18:Currency>
                <v18:Amount>800.00</v18:Amount>
            </v18:CustomsValue>
            <v18:HarmonizedCode>420330</v18:HarmonizedCode>
        </v18:Commodities>
    </v18:CustomsClearanceDetail>
    </v18:RequestedShipment>

GlobalPost

The GlobalPost API allows a maximum of 255 customs line items per shipment.

GlobalPost API functionality is accessed through our (Auctane's) platforms. The line items are typically sent within a customs_items array in the JSON request.

API Reference

Documentation for GlobalPost is integrated into the developer portal of our ShipStation API documentation:

  • Primary Documentation: ShipStation API Documentation

  • Specific Location: In the API documentation for creating or updating an order, look for the customsItems array. The field description specifies the maximum number of items allowed.

Sample JSON Request

JSON

{
  "carrierCode": "globalpost",
  "serviceCode": "globalpost_economy_intl",
  "packageCode": "package",
  "confirmation": "delivery",
  "shipDate": "2025-09-15",
  "weight": {
    "value": 3.0,
    "units": "pounds"
  },
  "dimensions": {
    "units": "inches",
    "length": 10.0,
    "width": 8.0,
    "height": 4.0
  },
  "shipFrom": {
    /* ... Ship From Address Details ... */
  },
  "shipTo": {
    /* ... Ship To Address Details ... */
  },
  "customs": {
    "contents": "merchandise",
    "nonDelivery": "return_to_sender",
    "customsItems": [ // This is the array for your customs line items (max 255).
      {
        "description": "Men's Synthetic Fabric T-Shirt",
        "quantity": 5,
        "value": 12.00,
        "harmonizedTariffCode": "610990",
        "countryOfOrigin": "CN",
        "weight": {
          "value": 0.5,
          "units": "pounds"
        }
      },
      {
        "description": "Ceramic Coffee Mug",
        "quantity": 2,
        "value": 8.50,
        "harmonizedTariffCode": "691200",
        "countryOfOrigin": "DE",
        "weight": {
          "value": 1.1,
          "units": "pounds"
        }
      },
      {
        "description": "Hardcover Novel",
        "quantity": 1,
        "value": 15.00,
        "harmonizedTariffCode": "490199",
        "countryOfOrigin": "US",
        "weight": {
          "value": 1.4,
          "units": "pounds"
        }
      }
    ]
  }
}

DHL

Here are the customs line item limits for the specified DHL shipping APIs.

DHL Express

The DHL Express API, also known as the MyDHL API, allows for a maximum of 999 customs line items per shipment.

These items are referred to as exportLineItems within the content object of a shipment request. This high limit is designed to accommodate large, complex commercial shipments.

API Reference

The official API documentation is available on the DHL Express Developer Portal.

  • Primary Documentation: DHL Express - MyDHL API Documentation

  • Specific Location: In the "Shipments" API reference, examine the request body for the POST /shipments endpoint. The constraint is defined on the content/exportLineItems array.

Sample JSON Request

This is a partial JSON payload focusing on the content object to show how to structure multiple line items.

JSON

{
  "customerDetails": {
    /* ... Customer Details ... */
  },
  "accounts": [
    {      "typeCode": "shipper",
      "number": "YourAccountNumber"
    }
  ],
  "productCode": "P",
  "plannedShippingDateAndTime": "2025-09-16T11:00:00 GMT+01:00",
  "pickup": {
    "isRequested": false
  },
  "ship": {
    /* ... Shipper & Recipient Details ... */
  },
  "packages": [
    {
      /* ... Package Details ... */
    }
  ],
  "content": {
    "isCustomsDeclarable": true,
    "incoterm": "DAP",
    "unitOfMeasurement": "metric",
    "exportDeclaration": {
      "invoice": {
        "number": "INV-2025-12345",
        "date": "2025-09-15"
      }
    },
    "exportLineItems": [ // This is the array for your customs line items (max 999).
      {
        "number": 1,
       "quantity": {
          "value": 10,
          "unitOfMeasurement": "BOX"
        },
        "description": "Grade A Circuit Boards",
        "value": 500.00,
        "commodityCode": "8473.30.11",
        "countryOfOrigin": "KR",
        "grossWeight": {
          "value": 5.5
       },
        "netWeight": {
          "value": 5.0
        }
      },
      {
        "number": 2,
        "quantity": {
          "value": 100,
          "unitOfMeasurement": "PCS"
        },
        "description": "Power Supply Units",
        "value": 1500.00,
        "commodityCode": "8504.40.95",
        "countryOfOrigin": "CN",
        "grossWeight": {
          "value": 20.5
        },
        "netWeight": {
          "value": 18.0
        }
      }
    ]
  }
}

DHL eCommerce Solutions (EU)

The DHL eCommerce Solutions API (also known as the Business Customer Shipping API in Europe) allows for a maximum of 99 customs line items per shipment.

These items are referred to as items or positions within the customsDetails object of the shipment request.

API Reference

Documentation is on the DHL Developer Portal, but under the Post & Parcel Germany or eCommerce Solutions sections, which use a different API from DHL Express.

  • Primary Documentation: DHL Business Customer Shipping API v3

  • Specific Location: In the POST /shipments operation, navigate the request body schema to shipments/details/customsDetails. The limit is specified for the items array within that object.

Sample JSON Request

This example shows the structure for a shipment with customs details for DHL eCommerce.

JSON

{
  "profile": "STANDARD_GRUPPENPROFIL",
  "shipments": [
    {
      "product": "V55WPAK",
      "billingNumber": "YourBillingNumber",
      "refNo": "Customer-Ref-123",
      "shipper": {
        /* ... Shipper Address ... */
      },
      "receiver": {
        /* ... Receiver Address ... */
      },
      "details": {
        "dim": {
          "uom": "cm",
          "length": 20,
          "width": 15,
          "height": 10
        },
        "weight": {
          "uom": "kg",
          "value": 2.5
        },
        "customsDetails": {
          "exportType": "OTHER",
          "placeOfCommital": "Hamburg",
          "additionalInfo": "Gift items",
          "exportTypeDescription": "SALE_OF_GOODS",
          "invoiceNo": "INV-2025-12345",
          "items": [ // This is the array for your customs line items (max 99).
            {
              "itemDescription": "Wool Scarf",
              "packagedQuantity": 2,
              "countryOfOrigin": "GB",
              "hsCode": "611710",
              "itemValue": 25.00,
              "itemWeight": 0.4
            },
            {
              "itemDescription": "Leather Gloves",
              "packagedQuantity": 1,
              "countryOfOrigin": "IT",
              "hsCode": "420321",
              "itemValue": 60.00,
              "itemWeight": 0.3
            }
          ]
        }
      }
   }
  ]
}

DHL eCommerce Solutions Americas API (US)

The DHL eCommerce Solutions Americas API allows a maximum of 99 customs line items per shipment.

These line items are referred to as commodities and are placed within the commodities array inside the customs object of a shipment request.

API Reference

The official documentation for this specific API is found on the DHL eCommerce Solutions Americas Developer Portal. It is crucial to use this portal and not the European one for US-based shipping.

Sample JSON Request

Below is a sample JSON payload for creating a shipment. It highlights the customs object and the structure of the commodities array where you would list your items.

JSON

{
  "shipper": {
    /* ... Shipper Details ... */
  },
  "consignee": {
    /* ... Consignee (Receiver) Details ... */
  },
  "packages": [
    {
      "packageId": "YourPackageID123",
      "weight": 2.5,
      "weightUom": "lb",
      "dimensions": {
        "length": 10,
        "width": 8,
        "height": 4,
        "dimUom": "in"
      },
      "customs": {
        "currency": "USD",
        "customsValue": 125.00,
        "customsContentType": "MERCHANDISE",
        "commodities": [ // This is the array for your customs line items (max 99).
          {
            "description": "Men's Cotton Polo Shirt",
            "quantity": 3,
            "value": 25.00,
            "hsCode": "610510",
            "countryOfOrigin": "VN"
          },
          { 
           "description": "Women's Leather Handbag",
            "quantity": 1,
            "value": 50.00,
            "hsCode": "420221",
            "countryOfOrigin": "MX"
          }
        ] 
     }
    }
  ],
  "labelOptions": {
    "format": "PDF",
    "resolution": 300
  },
  "billing": {
    "shipperAccountNumber": "YourAccountNumber",
    "billingAccountNumber": "YourAccountNumber"
  },
  "serviceType": "plg"
}

Articles in this section

Didn't Find What You Were Looking For? Contact Support