FedEx ETD: Sending the Commercial Invoice with the Shipment, Not in a Pouch

On a traditional international shipment, the commercial invoice is a piece of paper. You print several copies, put them in a document pouch on the box, and customs reads them at the border. If the pouch is lost or a copy is missing, the shipment stops.

Electronic Trade Documents send those documents to FedEx digitally as part of the shipment request, so customs receives them before the box arrives.

An honest note on this one: unlike most posts here, this is a docs-and-integration guide rather than a war story. The customs-data specifics below are the parts that caused real problems; the ETD mechanics themselves come from FedEx's published API.

Everything customs-related hangs off one branch of the shipment request:

requestedShipment:
  customsClearanceDetail:
    commodities: [ ... ]          # what is in the box
    dutiesPayment:                # who pays duty — see incoterms below
      paymentType: SENDER | RECIPIENT
    commercialInvoice: { ... }    # invoice-level fields
  shippingDocumentSpecification:  # what FedEx should produce / you supply
    shippingDocumentTypes: [ COMMERCIAL_INVOICE ]
  etdDetail:
    requestedDocumentTypes: [ COMMERCIAL_INVOICE ]

Two routes, and picking the right one early saves rework:

If your invoice has to carry country-specific tax registration numbers, a declaration line, or an authorised signature block, you will usually end up generating it yourself.

ETD does not make customs data more forgiving — it makes bad data arrive faster. These are the fields worth being pedantic about.

1. HS code, at the right number of digits

   Harmonised codes are internationally six digits, extended nationally to eight or ten. Different carriers and lanes expect different lengths, and sending the wrong number of digits gets rejected at booking or queried at the border. Store the full code and trim per lane rather than storing one truncated value.

2. Country of manufacture, per commodity

   Not the ship-from country. If you sell goods made in several places, this is per line, and getting it wrong is a misdeclaration rather than a typo.

3. Declared value that matches what the buyer paid

   Under-declaring to reduce duty is a customs offence, not a tactic. The value on the invoice should reconcile with the marketplace order.

4. Incoterm, chosen deliberately

   Who pays the duty — you or the buyer. Leave it defaulted and you will discover the answer when a buyer is asked for money at the door, which becomes a support ticket and often a refund.

Not strictly ETD, but it belongs in the same conversation because it becomes a problem the moment you automate document generation.

Every label you create is a shipment as far as the carrier is concerned — including the ones created by a bug, a duplicate click, or a test run. Cancel the ones you do not ship:

PUT /ship/v1/shipments/cancel

Cancellation is valid only before the package is tendered. Build the cancel path at the same time as the create path, not after your first billing surprise, and make it easy for an operator to reach — because they will need it on their first day.

FedEx gives you a sandbox, which puts it well ahead of some carriers. Two things to know before you rely on it:

• The Ship API is enabled separately from tracking. A project with tracking working is not a project that can create labels. If label calls fail with an authorisation error while tracking works fine, check which APIs are actually enabled on the project rather than debugging your credentials.
• Sandbox labels are not shippable, which is the point. Do your envelope and document work there, and treat moving to production as a separate, deliberate step with its own checks.

Most defects in this area are in document construction rather than the round trip, so assert on the request you build — the commodity lines, the code lengths, the value totals — rather than only on the response. That is testable offline and it is where the bugs live.

What is FedEx ETD?

Electronic Trade Documents — a way to submit customs paperwork such as the commercial invoice digitally with the shipment request, so customs receives it electronically instead of reading printed copies from a pouch on the box.

Where does ETD go in the FedEx Ship API request?

Customs data sits in requestedShipment.customsClearanceDetail, with the document behaviour controlled by shippingDocumentSpecification and etdDetail. You can have FedEx generate the commercial invoice from your customs data, or upload your own document.

Should I let FedEx generate the commercial invoice or upload my own?

Let FedEx generate it unless your invoice must carry specific local content — tax registration numbers, declaration wording, a signature block or branding. Those requirements usually push you to generating the PDF yourself.

How many digits should an HS code have?

Six internationally, extended to eight or ten nationally. Requirements vary by carrier and lane, so store the full code and trim per lane rather than storing a pre-truncated value.

How do I cancel a FedEx label I created by mistake?

PUT /ship/v1/shipments/cancel with the account and tracking number, valid only before the package is tendered. Build the cancel path alongside label creation rather than after the first billing surprise.

Why do my FedEx label calls fail when tracking works?

The Ship API is enabled separately from tracking on a FedEx developer project. Tracking working does not mean labels are enabled — check which APIs are on the project before suspecting your credentials.