Tell Zonos about your postal shipments

There are two calls, and they are the same for every destination.

1. brokerageManifestLinesCreate tells us about the parcels: the goods, the parties, and your own references. Send it as soon as you accept a parcel, with no transport context and nothing to create first. Up to 100 parcels per request.
2. brokerageManifestCreate tells us how they travel: the flight, voyage, or truck. Send it when the mail is tendered, naming the parcel ids from the first call.

Neither waits on the other. A parcel accepted after the conveyance already exists attaches later with manifestLinesLink.

Keep the id returned by the first call. It is what you name on the second.

Zonos calculates the landed cost for each parcel asynchronously. A successful response means the parcel was accepted, not that it has been quoted. Item and party data is checked during that calculation, so follow the field guidance below even where the API itself does not reject a missing value.

Certain destinations add a PDDP surcharge to each shipment. For the rates by destination, see PDDP surcharges by destination.

Shipping only within Europe? There is a one-call version. See a shorter path for Europe.

Field legend 

Step 1: Tell us about the parcels 

Parcel fields

Item fields

One entry per line of goods. A parcel holding three classifications is one parcel with three entries.

HS code and country of origin are per line of goods. A parcel holding goods of different classifications needs a code and an origin for each. One code for a mixed parcel cannot be filed into the United States.

Measurements. Each entry needs a type, unitOfMeasure, and value. Weight is net and covers all units on that line, so do not multiply by quantity. This is the weight duty is assessed on.

• type: WEIGHT, TOTAL_WEIGHT, VOLUME, LENGTH, WIDTH, HEIGHT, or ALCOHOL_BY_VOLUME
• unitOfMeasure: GRAM, KILOGRAM, OUNCE, POUND, LITER, MILLILITER, CENTIMETER, METER, MILLIMETER, INCH, FOOT, YARD, or PERCENTAGE

Product composition. Each entry takes material and percentage, plus optional countryOfMeltAndPour, countryOfCast, primaryCountryOfSmelt, and secondaryCountryOfSmelt.

Party fields

Each party has a type (ORIGIN for the sender, DESTINATION for the consignee), a person, and a location.

Customs authorities in both markets name the sender and the addressee, and a thin party is the most common reason a parcel cannot be cleared.

Origin addresses can be in any country, so postal code is recommended rather than required there. Many origins, such as Hong Kong, the UAE, and Qatar, have no postal codes. EU consignee addresses reliably have one, except in Ireland, where Eircode use is still incomplete.

Send administrativeAreaCode as the two-letter code, for example TX, not TEXAS.

Example

{
  "data": {
    "brokerageManifestLinesCreate": [
      {
        "id": "line_abc123def456",
        "trackingNumber": "RB123456799GB",
        "referenceNumber": "ITM-00184413",
        "taxIdNumber": "IM5281234567"
      }
    ]
  }
}

Product identifiers 

Four fields on each line of goods. Which you send matters more for Europe than anywhere else.

What Europe does with them

EU PDDP carries seven product identifier fields. Three are fed directly from what you send on the item, so sending more here fills more of the declaration.

The other PDDP identifier fields are not sourced from what you send. lccProviderProductIdentifier is set from our own item id, and manufacturerIdentifier is deliberately not sent: merchants rarely know their manufacturer's GLN, and the regimes that care about manufacturer identity want a name and address rather than a code.

Three things follow, and each causes a rejection if missed.

gtin must be digits only. The S PID field is pattern-matched to digits, so a dashed or spaced barcode fails. Send 05012345678900, not 0-50123-45678-9.

One canonical GTIN, never separate values. A UPC is a GTIN-12, an EAN-13 is a GTIN-13, and an ISBN-13 is a GTIN-13 with a 978 or 979 prefix. They are the same number space. Send gtin alone, or send upc and we normalize it into gtin. Sending both stores one identity twice.

manufacturerProductId allows 70 characters. Every other identifier field truncates at 50.

A field you do not hold is omitted rather than sent as an empty string. All seven have a minimum length of one.

Step 2: Tell us about the conveyance 

Send this when the mail is tendered to the carrier, naming the parcel ids from step 1.

No air waybill needed. We build the conveyance key ourselves from your carrier code, service number, and the date. Send one if you have it.

Ports. Keep sending destinationCode and originCode in the format you already use. We hold the mapping to the customs port lists and maintain it. If you route through a port we have not seen, tell us and we will add it.

A sea despatch is the same call with transportationMode: SEA, a SCAC in carrierCode, the voyage number in serviceNumber, a vesselName, and an arrival date weeks rather than hours out.

Parcels accepted later

Parcels accepted after the conveyance exists attach to it with manifestLinesLink.

mutation ManifestLinesLink($manifestId: ID!, $lineIds: [ID!]!) {
  manifestLinesLink(manifestId: $manifestId, lineIds: $lineIds) {
    id
  }
}

A shorter path for Europe 

Non-US parcels can skip the conveyance entirely. Pass your operator code alongside the array and send one call.

postalOperatorCode is what the conveyance would otherwise have carried. Supplying it here means we do not need one. A parcel can override the request-level default with its own postalOperatorCode.

Non-US destinations only. A US parcel always needs a conveyance, because the customs entry names the carrier, the service, and the arrival port.

Both paths work. The two-call flow is identical in every market and is the simpler integration if you ship to both; the short path saves a call if you ship only within Europe.

EU data notes 

IOSS

Send the IOSS number in taxIdNumber when the sale was made under IOSS. A valid IOSS number is IM, a 3-digit EU member state code, and 7 digits, for example IM5281234567. When it is valid, the parcel is quoted without import VAT, because the IOSS holder has already collected it. A number that is not in the IOSS format is ignored and the parcel is quoted with import VAT, so send the registration or send nothing rather than a sequence number or a line count.

CIF values

EU duty and VAT are assessed on the CIF value: goods plus shipping. Send shippingCost and shippingCostCurrency on every EU parcel. Without them, shipping is treated as zero and the quote understates the value.

Destination party

Always send a DESTINATION party with the consignee's EU country code. The destination country decides which rules apply, so a parcel without it cannot be quoted as an EU shipment.

US data notes 

Complete parties

A US customs entry names the sender and the addressee. Both need a full address: name, street, locality, postal code, state, and country. Send administrativeAreaCode as the two-letter state code.

Classification

A US entry needs a tariff code per line of goods, 10 digits preferred and 6 minimum. Where you send 6 digits we extend and validate. A line with no code cannot be filed, and a description alone is not enough to classify.

What we handle

You do not send, calculate, or maintain any of this: the importer of record, the customs bond and surety, the entry type and filer code, the duty, tax, and fees, or the transmission to customs. We resolve them from your account configuration and from the goods on the parcel.

General notes 

Duplicate parcels

referenceNumber must be unique across all of your parcels. If you send a parcel with a referenceNumber Zonos already has, the existing record is returned and moved to the new conveyance. Its items and parties are not updated. To correct a parcel, contact Zonos rather than resending it under the same reference.

Values

• Send exactly one of amount or totalAmount per item. Sending both, or neither, fails the quote.
• currencyCode is set once per parcel. Every item value on the parcel uses it.
• If you send upc without gtin, the UPC is used as the GTIN.
• Enum values are plain strings, for example "KILOGRAM".

Nothing waits on anything

Tell us about parcels the day you accept them. Tell us about the conveyance when you have it. Neither blocks the other.