Customs Line-Item Limits: 8 Carrier APIs Compared
Published customs line-item caps for 8 carrier and multi-carrier APIs, sourced and dated, so you know when a commodities array needs to split.
Published carrier API documentation puts the maximum number of customs line items per shipment anywhere between 5 and 999, depending on which carrier, which API, and which document type you're looking at. That's not a typo. A GlobalPost shipment can carry 255 customs items. A parcel going out on a CN22 sticker through PostNL or Royal Mail is capped at 5. If your adapter treats "customs line item limit" as one number per carrier, you've already built the wrong schema.
This matters more now than it did two years ago. Since the United States removed the $800 de minimis exemption on 29 August 2025, far more parcels carry a full commodity breakdown instead of skipping formal entry entirely. A field that used to sit empty on most low-value shipments is now mandatory on millions more of them, and the `commodities` / `customsItems` / `exportLineItems` array that carries that data has a hard ceiling nobody designs for until an 80-SKU B2B order gets bounced.
Method and scope
Every figure below is a maximum customs line item count published by the carrier or by a multi-carrier platform's own help centre or API reference. No figure here is estimated, averaged, or inferred from behaviour. Where no public number exists, the row says "Not published."
Data was checked 16 November 2026. The underlying carrier documentation pages carry their own last-updated signals from the platforms hosting them, ranging from late 2025 through to September 2026, so treat every number as a snapshot, not a contract. This comparison excludes negotiated enterprise overrides, freight and LTL customs formats, and postal forms outside the English-language carrier help centres checked for this piece.
The comparison table
The numbers split cleanly into two groups: API object limits (what your integration layer enforces before a label request leaves your system) and document limits (what the printed or electronically-filed customs form itself can hold). They are not always the same number for the same carrier.
| Carrier / API or document type | API object or document name | Max line items | Source |
|---|---|---|---|
| UPS Shipping API (REST/JSON) | Product | 50 | ShipEngine help centre |
| FedEx REST API and legacy SOAP API | Commodities | 99 | Stamps.com help centre |
| DHL eCommerce Solutions Americas API | commodities | 99 | ShipEngine help centre |
| DHL eCommerce Solutions API (Europe) | Not published | Not published | Not published |
| DHL Express / MyDHL API | exportLineItems | 999 | ShipEngine help centre |
| GlobalPost (via Auctane/ShipStation API) | customsItems | 255 | ShipStation help centre |
| USPS customs form | Not named in docs | 30 | ShipStation / ShipEngine / Stamps.com help centres |
| CN22/CN23 postal carriers (PostNL, Correos, Royal Mail, bpost, Deutsche Post) | CN22/CN23 form | 5 | Sendcloud help centre |
| bpost international shipments specifically | CN22/CN23 (bpost-specific sub-limit) | 3 | Sendcloud help centre |
| Commercial invoice via DPD, DHL, UPS | Commercial invoice | 99 | Sendcloud help centre |
| Multi-carrier platforms (ShipEngine, ShipStation, Shippo, EasyPost, AfterShip, Sendcloud, nShift, Cargoson) imposing their own ceiling below the carrier's | Not published | Not published | Not published |
A few of these rows deserve unpacking. For FedEx, the limit is consistent across both their new REST API and SOAP API, with the maximum number of customs line items allowed per shipment at 99. The DHL eCommerce Solutions Americas API allows a maximum of 99 customs line items per shipment, while DHL Express's MyDHL API carries an exportLineItems array capped at 999, a full order of magnitude higher, on the same carrier group. We could not find a published Europe-specific DHL eCommerce line-item ceiling in any of the sources checked, so that row stays marked "Not published" rather than guessed.
The postal numbers are the strictest by far. CN22 or CN23 postal carriers, such as PostNL, Correos, Royal Mail, bpost and Deutsche Post, allow a maximum of 5 item lines per customs document. Bpost's own integration notes go lower still: this carrier allows only 3 different item types per international shipment, and the edit-order view throws an error above that.
The trap: document type, not just carrier name, sets the limit
The same carrier can carry two different ceilings depending on whether you're hitting its REST API array or filling in a commercial invoice. Sendcloud's documentation states this directly: the maximum number of item lines depends on the type of customs document used by the carrier. Postal carriers using CN22/CN23 sit at 5 lines; the same shipper routing a parcel through DPD, DHL or UPS as a commercial invoice can list a maximum of 99 items per commercial invoice. UPS on its own is a good illustration of why you verify against the field name, not the carrier name. ShipStation's own troubleshooting documentation for UPS integrations states that UPS can accept up to 100 customs declarations, a figure that sits right alongside the documented 50-item ceiling on the `Product` array used in the REST API request body. One carrier, two numbers, two different places in the documentation. Add in the 35-character limit on item descriptions that UPS applies on the printed form itself, and "UPS's customs limit" stops being a single config value and starts being three.
Design implication: your schema needs a lookup keyed on (carrier, document type, API field), not a flat per-carrier constant. A single `maxCommodities: 50` field per carrier record will silently be wrong for at least one of the document types that carrier can produce.
What happens when you exceed the cap
Most carrier documentation stops short of describing client-visible behaviour beyond "validation error." We're not going to guess at reject-versus-truncate behaviour for carriers that don't document it; that row stays "Not published" everywhere we couldn't confirm it directly.
What is documented, consistently, is the workaround. Carriers such as DPD, DHL and UPS allow a maximum of 99 items per commercial invoice, and to create more than 99 items you must create a new shipment. The fix at the document layer is almost never "retry with a smaller payload." It's "split the shipment and link the two." That has a real operational cost. A 60-line B2B order clears FedEx's 99-item ceiling without issue, exceeds UPS's 50-item API array by 10 items, and is double the USPS 30-item form limit. The same order, routed to three different carriers by a rate-shopping layer that doesn't know about this, passes on one and fails on two.
Where this belongs: the routing layer, not the checkout form
Put the commodity count check before carrier selection, not after. If a shipment's distinct commodity count exceeds a carrier's documented ceiling, that carrier shouldn't be offered as a routing option in the first place, and the alternative is an adapter that auto-splits one logical order into multiple physical shipments with linked references.
That split creates a problem this blog has covered before in other contexts: one internal order ID now maps to two carrier-side shipment IDs. If your idempotency keys are built off the order ID alone, a retried split will generate duplicate shipments rather than resuming the original one. The envelope needs to carry both the original order reference and a sequence marker for the split part, and the idempotency key needs to be scoped to (order ID, split index), not just the order.
Multi-carrier platforms sit exactly at this seam. ShipEngine, ShipStation, Shippo, EasyPost, AfterShip, Sendcloud, nShift and Cargoson all abstract the raw carrier array away from the shipper to varying degrees, but only some of them publish a pass-through ceiling of their own that's lower than the underlying carrier's limit. Where we couldn't find a platform-level number distinct from the carrier's, the honest answer is "Not published," which in practice means you should assume the carrier's own limit applies until you've tested otherwise.
What to build before the next B2B order breaks it
- Keep a (carrier, document type, field name) to max-line-items lookup in configuration, not in code. These figures move between carrier API versions and the config needs to be re-checked on a schedule, not assumed stable.
- Count distinct commodities in the adapter before carrier selection runs, so a 60-line order never gets offered a 50-line carrier as a valid option.
- Build the auto-split path with the same idempotency-key discipline you'd apply to any retry-prone operation: one order ID, multiple linked shipment IDs, no ambiguity about which split a given label response belongs to.
- Treat the de minimis-driven growth in SKU-level customs data as a capacity-planning input. More parcels now need full commodity breakdowns than did in August 2025, and that shifts load onto exactly the part of your schema with the tightest documented ceilings.