HomePostal outbound solutions To the European Union Manifest API

Send manifest data for EU shipments

Provide Zonos with the conveyance and shipment data needed to quote and declare postal shipments into the European Union.

Sending data takes two calls:

manifestCreate creates the manifest for a conveyance (a flight, truck, or vessel) and returns an id.
manifestLineCreate adds one shipment (its items and parties) to that manifest, using the id from step 1. Use manifestLinesCreate to add many lines in one request.

Zonos calculates the landed cost for each line asynchronously after it is created. A successful manifestLineCreate response means the line 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.

Field legend

Label↕	Meaning↕
Required	The API rejects the request without it.
Required for EU	Must be sent for every EU-bound shipment. The API may accept a line without it, but the quote can be wrong or fail and the shipment is not compliant.
Recommended	Not needed to quote, but used by destination posts and customs. Send it whenever you have it.
Optional	Send it when it applies.

Step 1: Create the manifest

Field↕	Requirement↕	Notes↕
`carrierCode`	Required	IATA 2-letter code (air) or SCAC (truck, ocean).
`serviceNumber`	Required	Flight or trip number.
`arrivalDate`	Required	ISO 8601 date and time of arrival.
`destinationCode`	Required	Arrival airport or port code, for example `FRA` or `CDG`.
`postalOperatorCode`	Required	Your posting operator code, for example `J1CGBA`.
`originCode`	Recommended	Departure airport or port code.
`transportationMode`	Optional	`AIR`, `SEA`, `ROAD`, `RAIL`, `INLAND_WATERWAY`, or `OTHER`. Defaults to `AIR`.
`weight`	Optional	Total manifest weight.
`weightUnit`	Optional	`GRAM`, `KILOGRAM`, `OUNCE`, or `POUND`. Required when `weight` is greater than zero.
`awbPrefix`	Optional	Air waybill prefix.
`awbNumber`	Optional	Air waybill number.
`amount`	Optional	Total manifest value.

1mutation ManifestCreate($input: ManifestInput!) {

2 manifestCreate(input: $input) {

3 id

4 arrivalDate

5 carrierCode

6 destinationCode

7 postalOperatorCode

8 serviceNumber

9 }

10}

RESPONSE

json

{
  "data": {
    "manifestCreate": {
      "id": "manifest_abc123def456",
      "arrivalDate": "2026-10-15T09:00:00Z",
      "carrierCode": "LH",
      "destinationCode": "FRA",
      "postalOperatorCode": "J1CGBA",
      "serviceNumber": "LH901"
    }
  }
}

Step 2: Add manifest lines

manifestLineCreate takes the manifestId returned in step 1 and one ManifestLineInput.

Line fields

Field↕	Requirement↕	Notes↕
`trackingNumber`	Required	Item tracking number.
`currencyCode`	Required	Currency of every item value on the line.
`endUse`	Required	`DOCUMENTS`, `GIFT`, `FOR_RESALE`, `NOT_FOR_RESALE`, or `RETURN`.
`items`	Required	At least one item. See item fields.
`parties`	Required	One `ORIGIN` and one `DESTINATION` party. See party fields.
`shippingCost`	Required for EU	Shipping charge for the parcel. EU duty and VAT are assessed on the CIF value, so a missing shipping cost is treated as zero.
`shippingCostCurrency`	Required for EU	Currency of `shippingCost`. Defaults to `USD` when omitted.
`taxIdNumber`	Optional	The IOSS number, when the sale was made under IOSS. See IOSS.
`consignmentWeight`	Recommended	Parcel weight in kilograms. Send the same value on every line that shares a tracking number.
`referenceNumber`	Recommended	Your unique reference for the line, used to prevent duplicates. See duplicate lines.
`shipperAccountId`	Optional	The Zonos organization ID or your external ID for the shipper's verified account. Links the line to that account for billing.

Item fields

Field↕	Requirement↕	Notes↕
`quantity`	Required	Number of units.
`countryOfOrigin`	Required	2-letter ISO country code.
`amount`	Required for EU	Unit value. Send exactly one of `amount` or `totalAmount`.
`totalAmount`	Required for EU	Extended value for all units. When sent instead of `amount`, the unit value is `totalAmount / quantity`.
`description`	Required for EU	Plain description of the goods.
`measurements`	Required for EU	Include a weight entry (`WEIGHT` per unit, or `TOTAL_WEIGHT` for all units, not both). See below.
`hsCode`	Recommended	HS or tariff code.
`customsDescription`	Optional	Customs-specific description, when it differs from `description`.
`provinceOfOrigin`	Optional	Province or state of origin, where a country requires it.
`gtin`	Recommended	Global Trade Item Number (covers UPC, EAN, and ISBN).
`upc`	Optional	Used as the `gtin` when no `gtin` is sent.
`sku`	Optional	Your SKU.
`productId`	Optional	Your product identifier.
`name`	Optional	Short product name.
`productComposition`	Optional	Materials that make up the product. Each entry needs `material` and `percentage`.
`marketplace`	Optional	Marketplace the item was sold on, as `name` and `url`.

Measurements. Each entry needs a type, unitOfMeasure, and value.

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.

Field↕	Origin (sender)↕	Destination (consignee)↕
`location.countryCode`	Required	Required
`location.line1`	Required for EU	Required for EU
`location.locality` (city)	Required for EU	Required for EU
`location.postalCode`	Optional	Required for EU (except Ireland)
`location.administrativeArea`	Optional	Optional
`person.firstName`	Required for EU	Required for EU
`person.lastName`	Required for EU	Required for EU
`person.email`	Required for EU	Required for EU
`person.companyName`	Optional	Optional
`person.phone`	Optional	Optional

Origin addresses can be in any country, so postal code and state are optional 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.

Example

1mutation ManifestLineCreate($manifestId: ID!, $input: ManifestLineInput!) {

2 manifestLineCreate(manifestId: $manifestId, input: $input) {

3 id

4 trackingNumber

5 referenceNumber

6 taxIdNumber

7 landedCost {

8 id

9 }

10 }

11}

RESPONSE

json

{
  "data": {
    "manifestLineCreate": {
      "id": "manifest_line_def456ghi789",
      "trackingNumber": "LX123456789GB",
      "referenceNumber": "RMG-1001",
      "taxIdNumber": "IM3720000123",
      "landedCost": null
    }
  }
}

landedCost is null until the asynchronous calculation finishes. Query the line again with manifestLines to read the quote.

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 IM3720000123. When it is valid, the line 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 line is quoted with import VAT.

CIF values

EU duty and VAT are assessed on the CIF value: goods plus shipping. Send shippingCost and shippingCostCurrency on every EU line. 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 to the line, so a line without it cannot be quoted as an EU shipment.

Duplicate lines

referenceNumber must be unique across all of your lines. If you send a line with a referenceNumber Zonos already has, the existing line is returned and moved to the new manifest. Its items and parties are not updated. To correct a line, 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 line. Every item value on the line uses it.
If you send upc without gtin, the UPC is used as the GTIN.
Enum values are plain strings, for example "KILOGRAM".

Book a demo