{"componentChunkName":"component---src-templates-simple-markdown-js","path":"/guides/integrate-cross-border-shipments/","matchPath":"","result":{"data":{"markdownRemark":{"html":"

Integrate Cross-Border Shipments

\n

Cross-border shipments require significantly richer data than domestic shipments. While a domestic shipment can often be booked with just a pickup, dropoff, and basic parcel information, international shipments must include detailed item-level customs data, accurate parcel weights and dimensions, trade terms, and information about the commercial parties involved in the transaction.

\n

This guide walks through everything you need to know to create cross-border shipments through the Carriyo API, and explains how Carriyo's configuration hierarchy lets you choose what to pass per shipment versus what to default at the carrier account level.

\n

When to use this guide

\n

Use this guide when you are:

\n\n

If your shipments are purely domestic and don't cross customs boundaries, the standard Create Shipment documentation is sufficient.

\n
\n

How Carriyo resolves cross-border data

\n

Before diving into the individual fields, it's important to understand how Carriyo resolves customs-related data at booking time. Carriyo uses a configuration hierarchy — you don't necessarily need to pass every cross-border field on every shipment. Instead, you can configure defaults at the carrier account level, and only pass shipment-level data when it differs.

\n

The resolution order is:

\n
    \n
  1. \nShipment-level data (highest priority)\n — If you pass a value in the shipment's \ncustoms\n object, it is always used.\n
    2. \n
  2. \nCarrier account properties (fallback)\n — If the shipment doesn't include the field, Carriyo checks the carrier account's configured properties for a default value.\n
    3. \n
  3. \nSmart defaults (lowest priority)\n — For certain parties, additional fallback logic applies. For example, if \nSeller defaults to pickup\n is enabled on the carrier account, the seller details will be derived from the shipment's \npickup\n address when no explicit seller is configured. Similarly, \nBuyer defaults to dropoff\n derives the buyer from the \ndropoff\n address.\n
    4. \n
\n

This means that for merchants who always ship from the same entity with the same tax registrations, the seller, exporter, and incoterms can be configured once on the carrier account — and individual shipments only need to carry the data that varies per order (items, parcels, buyer/dropoff).

\n
\n

Example: DHL Express — A DHL carrier account can be configured via the Carriyo dashboard with default values for the incoterm, seller, buyer, exporter, and importer — including full addresses and registration numbers. See Carrier Account configuration below for details.

\n
\n
\n

Cross-border data checklist

\n

1. Item-level customs data

\n

Each item in the items[] array must carry enough detail for customs declaration and commercial invoice generation.

\n

Required item fields

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldShipment pathNotes
Descriptionitems[].descriptionHuman-readable description for customs forms (e.g. \"Cotton T-shirt, size M, blue\"). Required at confirm.
SKUitems[].skuUnique item/SKU identifier from your catalog. Required at confirm.
Quantityitems[].quantityInteger, must be >= 1. Required at confirm.
Unit priceitems[].price.amount, items[].price.currencyPrice per unit. Currency as ISO 4217 code (e.g. USD, AED, EUR). Required at confirm.
HS codeitems[].hs_codeThe Harmonized System commodity code. Required by most carriers and customs authorities for classification and duty calculation. Typically 6-10 digits.
Country of originitems[].origin_countryTwo-letter ISO 3166-1 alpha-2 code for the country where the item was manufactured (e.g. CN, IN, US).
Item weightitems[].weight.value, items[].weight.unitNet weight of a single unit. Unit is typically kg. Used for customs value calculations and documentation.
\n
\n

Tip: The description field appears directly on customs forms and commercial invoices. Vague descriptions like \"Clothing\" or \"Goods\" can cause customs delays. Be specific: \"Men's cotton polo shirt\" is better than \"Shirt\".

\n
\n

Additional item fields for compliance

\n

Depending on the carrier, destination country, or the nature of the goods, you may also need:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldShipment pathWhen needed
Cost priceitems[].cost.amount, items[].cost.currencyThe unit cost of the item. Useful when the selling price (price) is zero — for example, samples or promotional items. Customs authorities require a monetary value for declaration even when the item is not being sold. In such cases, set price to 0 and provide the actual cost here so it can be used on the commercial invoice and customs declaration.
Dangerous goodsitems[].dangerous_goodsSet to true if the item is classified as hazardous goods (e.g. perfumes, aerosols, certain chemicals). Triggers carrier-specific DG handling.
Battery detailsitems[].battery.material_type, items[].battery.packing_typeRequired when shipping items containing lithium batteries. material_type values: lithium_ion, lithium_metal. packing_type values: contained_in_equipment, packed_with_equipment, stand_alone.
Taxesitems[].taxes[]Pre-calculated tax amounts for the item, if available from your tax engine.
Dutiesitems[].duties[]Pre-calculated duty amounts for the item.
Manufacturer IDitems[].manufacturer_idManufacturer reference. Required by some carriers for specific destination countries.
Material compositionitems[].material_compositionMaterial details (e.g. \"100% cotton\", \"polyester blend\"). Relevant for textile and apparel shipments where customs classification depends on material.
\n

2. Parcel-level details

\n

Parcels define the physical packages being shipped. Even when item data is complete, carrier booking may fail if parcel weight and dimensions are missing or inaccurate.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldShipment pathNotes
Parcel weightparcels[].weight.value, parcels[].weight.unitThe actual packed weight of the parcel including packaging material. Required for rating, booking, and label generation.
Parcel dimensionsparcels[].dimension.width, parcels[].dimension.height, parcels[].dimension.depth, parcels[].dimension.unitPhysical dimensions of the package. Used to calculate volumetric (dimensional) weight. Carriers charge based on whichever is greater: actual weight or volumetric weight.
Item-to-parcel mappingparcels[].parcel_items[].sku, parcels[].parcel_items[].quantitySpecifies which items (and how many of each) are in each parcel. Critical for multi-parcel shipments where customs documentation must accurately reflect the contents of each package.
\n
\n

Why parcel weight matters separately from item weight: The parcel weight should reflect the total packed weight — including packaging materials, filler, and the box itself. The sum of individual item weights will typically be less than the parcel weight. Carriers use the parcel weight for rating; customs authorities use item weights for duty calculation.

\n
\n
\n

Volumetric weight: Most international carriers calculate chargeable weight as the greater of actual weight or volumetric weight. Volumetric weight = (Width x Height x Depth) / volumetric divisor (typically 5000 for cm/kg). If you don't provide dimensions, some carriers will reject the booking; others may apply default dimensions that result in higher charges.

\n
\n

3. Shipment-level customs context

\n

The customs object on the shipment carries trade terms, value declarations, and customs-specific instructions.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldShipment pathNotes
Incotermscustoms.incotermsInternational Commercial Terms defining the responsibilities of buyer and seller. See Incoterms reference below.
Declared valuecustoms.declared_value.amount, customs.declared_value.currencyOptional override of the total customs value. If omitted, Carriyo or the carrier typically derives this from the sum of items[].price.amount * items[].quantity. Use this when you need to declare a different value than the item total.
Customs instructionscustoms.instructionsFree-text handling notes for customs processing (e.g. \"Fragile — handle with care\", \"Temperature sensitive\").
Declaration statementcustoms.declaration_statementFormal legal text for the customs declaration (e.g. \"I hereby certify that the information on this invoice is true and correct and that the contents of this shipment are as stated above.\").
\n

4. Customs parties

\n

For domestic shipments, the pickup and dropoff addresses are sufficient. For international shipments, customs authorities and carriers may require additional parties to be identified. These parties appear on the commercial invoice and customs declaration documents.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PartyShipment pathRole
Sellercustoms.sellerThe entity selling the goods. Often the merchant or warehouse operator. Appears on the commercial invoice as the invoicing party.
Buyercustoms.buyerThe entity purchasing the goods. Typically the end customer. The \"sold to\" party on the commercial invoice.
Importercustoms.importerThe Importer of Record (IOR) — the entity responsible for clearing goods through customs at the destination country. May carry specific tax registration numbers (VAT, IOSS, EOR).
Exportercustoms.exporterThe Exporter of Record (EOR) — the entity responsible for export compliance and documentation in the origin country.
Brokercustoms.brokerThe customs broker handling clearance formalities on behalf of the importer or exporter. Used by carriers like FedEx for broker-assisted clearance.
\n

When are these parties needed?

\n

Not every shipment requires all five parties. Here's a practical guide:

\n\n
\n

Don't have all the party details? Carriyo supports smart defaults. For example, if the carrier account has Seller defaults to pickup enabled, the seller will be automatically derived from the pickup address. Similarly, Buyer defaults to dropoff derives the buyer from the dropoff address. This is useful when the seller is always the warehouse (pickup) and the buyer is always the consignee (dropoff).

\n
\n

Party field structure

\n

Each customs party uses the same address structure:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldJSON path (relative to party)Notes
Contact namecontact_nameFull name of the contact person. Required at confirm.
Company namecompany_nameLegal entity or business name. Only needed when it differs from contact_name — for domestic shipments, the company name is often passed in contact_name directly. More relevant for cross-border where customs forms distinguish the two.
Phonecontact_phoneContact phone number with country code.
Emailcontact_emailContact email address.
Address line 1address1Primary street address.
Address line 2address2Additional address details (suite, floor, etc.).
CitycityCity name.
State / ProvincestateState, province, or region.
Postal codepostcodePostal or ZIP code.
CountrycountryTwo-letter ISO 3166-1 alpha-2 country code. Required at confirm.
Personal IDpersonal_id.id, personal_id.typeGovernment-issued identification (passport number, national ID). Required for customs clearance in some countries (e.g. Brazil CPF, South Korea PCC).
Registration numbersregistration_numbers[]Tax and regulatory identifiers. See Registration numbers below.
\n

Registration numbers

\n

Registration numbers are tax and regulatory identifiers critical for customs clearance. Each customs party can carry multiple registration numbers — for example, a seller might have both a VAT number and an IOSS number.

\n
\n
\n
Copy
\n
Copied
\n
\n 
\"registration_numbers\": [\n  {\n    \"type_code\": \"VAT\",\n    \"value\": \"GB123456789\",\n    \"issuer_country_code\": \"GB\"\n  },\n  {\n    \"type_code\": \"IOSS\",\n    \"value\": \"IM1234567890\",\n    \"issuer_country_code\": \"IE\"\n  }\n]
\n
\n

Each registration number has three fields:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldDescription
type_codeThe type of registration. See supported types below.
valueThe actual registration number value.
issuer_country_codeThe two-letter ISO country code of the issuing authority.
\n

Supported registration number types:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Type codeFull nameCommon use
VATValue Added TaxMost international shipments. Required in EU, GCC, UK.
IOSSImport One-Stop ShopEU imports under EUR 150. Placed on the seller or importer.
EOREconomic Operator Registration (EORI)EU/UK customs clearance. Required for commercial importers.
EINEmployer Identification NumberUS-based entities.
GSTGoods and Services TaxIndia, Australia, Singapore, and other GST jurisdictions.
PANPermanent Account NumberIndia — required for customs clearance.
SSNSocial Security NumberIndividual identification in some jurisdictions.
DUNDun & Bradstreet NumberBusiness identification.
FEDFederal Tax IDFederal-level tax identification.
STAState Tax IDState-level tax identification.
SDTState Department of TaxationState tax authority registration.
INNTaxpayer Identification NumberRussia.
KPPTax Registration Reason CodeRussia.
OGRPrimary State Registration NumberRussia.
OKPRussian Classification of ProductsRussia.
CNPCod Numeric PersonalRomania — personal identification code.
IEInscrição EstadualBrazil — state-level tax registration.
\n

Common scenarios:

\n\n
\n

Incoterms reference

\n

Incoterms (International Commercial Terms) define who is responsible for shipping costs, insurance, duties, and risk at each stage of the shipment. The customs.incoterms field tells the carrier which trade terms apply to the shipment.

\n

Supported values

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CodeFull nameWho pays duties & taxes?Who bears shipping risk?
EXWEx WorksBuyerBuyer from seller's premises
FCAFree CarrierBuyerBuyer after handover to carrier
FASFree Alongside ShipBuyerBuyer after goods placed alongside vessel
FOBFree on BoardBuyerBuyer after goods loaded on vessel
CFRCost and FreightBuyerBuyer after goods loaded on vessel
CIFCost, Insurance, and FreightBuyerBuyer after goods loaded on vessel
CPTCarriage Paid ToBuyerBuyer after handover to carrier
CIPCarriage and Insurance Paid ToBuyerBuyer after handover to carrier
DAPDelivered at PlaceBuyerSeller until arrival at destination
DPUDelivered at Place UnloadedBuyerSeller until unloaded at destination
DDPDelivered Duty PaidSellerSeller until delivery
DDUDelivered Duty UnpaidBuyerSeller until arrival at destination
DATDelivered at TerminalBuyerSeller until unloaded at terminal (replaced by DPU in Incoterms 2020)
DAFDelivered at FrontierBuyerSeller until frontier (legacy)
DEQDelivered Ex QuayBuyerSeller until unloaded at quay (legacy)
DESDelivered Ex ShipBuyerSeller until arrival at port (legacy)
\n

Choosing the right incoterm for e-commerce

\n

For most e-commerce cross-border shipments, the practical choice comes down to two options:

\n\n
\n

Tip: If you are seeing high rates of refused deliveries on international shipments, consider switching from DAP to DDP and factoring duties into your product pricing or checkout flow.

\n
\n

Carrier-specific incoterm support

\n

Not all carriers support all incoterms. Carriyo validates the incoterm against the carrier's supported values at booking time. Here are some examples:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CarrierSupported incoterms
DHL ExpressCFR, CIF, CIP, CPT, DAF, DAP, DAT, DDP, DDU, DPU, DEQ, DES, EXW, FAS, FCA, FOB
FedExDAP, DAT, DDP, DDU, EXW
UPSCFR, CIF, CIP, CPT, DAF, DDP, DDU, DEQ, DES, EXW, FAS, FCA, FOB
DHL eCommerceDDP, DDU
AJEXDDP, DDU
GLSDDP, DDU
DB SchenkerCFR, CIF, CIP, CPT, DAF, DAP, DAT, DDP, DDU, DEQ, DES, DPU, EXW, FAS, FCA, FOB
\n

If you pass an unsupported incoterm for a given carrier, the booking will fail with an error indicating which values are accepted.

\n

Incoterm resolution: shipment vs. carrier account

\n

Incoterms follow Carriyo's standard configuration hierarchy:

\n
    \n
  1. \nIf \ncustoms.incoterms\n is set on the shipment, that value is used.\n
    2. \n
  2. \nIf not set on the shipment, the carrier account's configured incoterm default is used (e.g. \nINCOTERM: \"DDP\"\n in the DHL carrier account properties).\n
    3. \n
  3. \nIf neither is configured, the carrier booking proceeds without an incoterm (which may cause a booking failure if the carrier requires one).\n
    4. \n
\n

When to pass it on the shipment: When you have mixed incoterm requirements — for example, DDP for some destinations and DAP for others — pass the incoterm per shipment.

\n

When to configure it on the carrier account: When all shipments through a given carrier account use the same trade terms. This is common when a carrier account is dedicated to a specific trade lane (e.g. a DHL account used exclusively for DDP shipments from UAE to EU).

\n
\n

Configuring defaults on the carrier account

\n

Many cross-border fields that remain the same across all shipments for a given carrier account can be configured as defaults rather than passed on every shipment. This reduces the payload size and ensures consistency.

\n

Carrier account configuration is managed through the Carriyo dashboard. Each carrier has its own set of supported configuration fields — the available settings depend on the carrier's specification and what Carriyo supports for that integration. These settings are not self-service via the API.

\n

The following are examples of what can typically be configured at the carrier account level for cross-border flows:

\n

Incoterm default

\n

A default incoterm (e.g. DDP, DAP) can be set on the carrier account. When configured, it applies automatically to all shipments booked through that account unless the shipment explicitly passes customs.incoterms.

\n

Customs party defaults (seller, buyer, exporter, importer)

\n

For carriers that require customs parties (such as DHL Express), the full details of each party — including name, company, address, and registration numbers — can be pre-configured on the carrier account. This is common when:

\n\n

When these defaults are configured, you don't need to pass the corresponding customs.seller, customs.exporter, or customs.importer objects on each shipment — Carriyo fills them in from the carrier account at booking time.

\n

Smart party defaults

\n

Some carriers (such as DHL Express) support smart fallback behavior that can be enabled on the carrier account via the Carriyo dashboard:

\n\n

This is particularly useful for standard e-commerce flows where the seller is always the warehouse (pickup) and the buyer is always the end customer (dropoff). With these defaults enabled on the carrier account, you may not need to pass seller or buyer details at all — Carriyo derives them from the shipment's pickup and dropoff addresses.

\n

Other carrier-specific settings

\n

Depending on the carrier, additional cross-border settings may be available at the carrier account level. Examples include:

\n\n
\n

Note: The available configuration fields vary by carrier. Work with your Carriyo support team to set up the carrier account for your cross-border requirements. They will help you configure the appropriate settings based on the carrier's specification and your specific trade lanes.

\n
\n
\n

Recommended integration flow

\n

Step 1: Configure carrier account defaults

\n

Before you start sending cross-border shipments, configure your carrier account with the static cross-border data:

\n\n

Step 2: Create shipments with per-order data

\n

When creating a shipment, include the data that varies per order:

\n\n

Step 3: Confirm and monitor

\n
    \n
  1. \nConfirm the shipment\n once fulfillment and parcelization are final using \nConfirm Shipment\n. Carriyo validates all required fields at confirmation time.\n
    2. \n
  2. \nMonitor for errors.\n Common cross-border booking failures include:\n\n
    3. \n
  3. \nCorrect and retry.\n Use \nPatch Shipment\n to fix individual fields without replacing the entire shipment payload, then retry the booking using \nReprocess Shipment\n.\n
    4. \n
\n

See Shipment Validation Errors and Shipment Error Codes for error reference.

\n
\n

Example: Cross-border shipment with full customs data

\n

The example below shows a complete cross-border shipment from UAE to UK, with two items, one parcel, and full customs data including parties and registration numbers.

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"merchant\": \"YOUR-MERCHANT-ID\",\n  \"entity_type\": \"FORWARD\",\n  \"pickup\": {\n    \"contact_name\": \"Acme Fashion Warehouse\",\n    \"company_name\": \"Acme Fashion Ltd\",\n    \"contact_phone\": \"+971501234567\",\n    \"address1\": \"Dubai Internet City, Building 12\",\n    \"city\": \"Dubai\",\n    \"country\": \"AE\",\n    \"postcode\": \"00000\"\n  },\n  \"dropoff\": {\n    \"contact_name\": \"Jane Smith\",\n    \"contact_phone\": \"+447700900123\",\n    \"contact_email\": \"jane.smith@example.com\",\n    \"address1\": \"42 King's Road\",\n    \"city\": \"London\",\n    \"state\": \"England\",\n    \"country\": \"GB\",\n    \"postcode\": \"SW3 4ND\"\n  },\n  \"items\": [\n    {\n      \"description\": \"Women's cotton T-shirt, size M, navy blue\",\n      \"sku\": \"TSHIRT-W-M-NAVY\",\n      \"quantity\": 2,\n      \"price\": { \"amount\": 25.00, \"currency\": \"USD\" },\n      \"weight\": { \"value\": 0.2, \"unit\": \"kg\" },\n      \"hs_code\": \"610910\",\n      \"origin_country\": \"IN\"\n    },\n    {\n      \"description\": \"Wireless Bluetooth earbuds with charging case\",\n      \"sku\": \"EARBUDS-BT-001\",\n      \"quantity\": 1,\n      \"price\": { \"amount\": 89.99, \"currency\": \"USD\" },\n      \"weight\": { \"value\": 0.15, \"unit\": \"kg\" },\n      \"hs_code\": \"851830\",\n      \"origin_country\": \"CN\",\n      \"dangerous_goods\": false,\n      \"battery\": {\n        \"material_type\": \"lithium_ion\",\n        \"packing_type\": \"contained_in_equipment\"\n      }\n    }\n  ],\n  \"parcels\": [\n    {\n      \"weight\": { \"value\": 0.9, \"unit\": \"kg\" },\n      \"dimension\": {\n        \"width\": 30,\n        \"height\": 20,\n        \"depth\": 15,\n        \"unit\": \"cm\"\n      },\n      \"parcel_items\": [\n        { \"sku\": \"TSHIRT-W-M-NAVY\", \"quantity\": 2 },\n        { \"sku\": \"EARBUDS-BT-001\", \"quantity\": 1 }\n      ]\n    }\n  ],\n  \"customs\": {\n    \"incoterms\": \"DAP\",\n    \"declaration_statement\": \"I hereby certify that the information on this invoice is true and correct and that the contents of this shipment are as stated above.\",\n    \"seller\": {\n      \"contact_name\": \"Ahmed Al Rashid\",\n      \"company_name\": \"Acme Fashion Ltd\",\n      \"contact_phone\": \"+971501234567\",\n      \"contact_email\": \"exports@acmefashion.com\",\n      \"address1\": \"Dubai Internet City, Building 12\",\n      \"city\": \"Dubai\",\n      \"country\": \"AE\",\n      \"postcode\": \"00000\",\n      \"registration_numbers\": [\n        {\n          \"type_code\": \"VAT\",\n          \"value\": \"100234567890003\",\n          \"issuer_country_code\": \"AE\"\n        }\n      ]\n    },\n    \"buyer\": {\n      \"contact_name\": \"Jane Smith\",\n      \"contact_phone\": \"+447700900123\",\n      \"contact_email\": \"jane.smith@example.com\",\n      \"address1\": \"42 King's Road\",\n      \"city\": \"London\",\n      \"state\": \"England\",\n      \"country\": \"GB\",\n      \"postcode\": \"SW3 4ND\"\n    },\n    \"exporter\": {\n      \"contact_name\": \"Ahmed Al Rashid\",\n      \"company_name\": \"Acme Fashion Ltd\",\n      \"contact_phone\": \"+971501234567\",\n      \"contact_email\": \"exports@acmefashion.com\",\n      \"address1\": \"Dubai Internet City, Building 12\",\n      \"city\": \"Dubai\",\n      \"country\": \"AE\",\n      \"postcode\": \"00000\",\n      \"registration_numbers\": [\n        {\n          \"type_code\": \"EOR\",\n          \"value\": \"AEXXXXXXXXX\",\n          \"issuer_country_code\": \"AE\"\n        }\n      ]\n    },\n    \"importer\": {\n      \"contact_name\": \"Jane Smith\",\n      \"company_name\": \"Jane Smith\",\n      \"contact_phone\": \"+447700900123\",\n      \"address1\": \"42 King's Road\",\n      \"city\": \"London\",\n      \"state\": \"England\",\n      \"country\": \"GB\",\n      \"postcode\": \"SW3 4ND\",\n      \"registration_numbers\": [\n        {\n          \"type_code\": \"EOR\",\n          \"value\": \"GB205672212000\",\n          \"issuer_country_code\": \"GB\"\n        }\n      ]\n    }\n  }\n}
\n
\n

Simplified version using carrier account defaults

\n

If the carrier account is configured with seller, exporter, incoterm, and smart defaults (Seller defaults to pickup enabled, Buyer defaults to dropoff enabled), the same shipment can be created with a much leaner payload — only the per-order data:

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"merchant\": \"YOUR-MERCHANT-ID\",\n  \"entity_type\": \"FORWARD\",\n  \"pickup\": {\n    \"contact_name\": \"Acme Fashion Warehouse\",\n    \"company_name\": \"Acme Fashion Ltd\",\n    \"contact_phone\": \"+971501234567\",\n    \"address1\": \"Dubai Internet City, Building 12\",\n    \"city\": \"Dubai\",\n    \"country\": \"AE\",\n    \"postcode\": \"00000\"\n  },\n  \"dropoff\": {\n    \"contact_name\": \"Jane Smith\",\n    \"contact_phone\": \"+447700900123\",\n    \"contact_email\": \"jane.smith@example.com\",\n    \"address1\": \"42 King's Road\",\n    \"city\": \"London\",\n    \"state\": \"England\",\n    \"country\": \"GB\",\n    \"postcode\": \"SW3 4ND\"\n  },\n  \"items\": [\n    {\n      \"description\": \"Women's cotton T-shirt, size M, navy blue\",\n      \"sku\": \"TSHIRT-W-M-NAVY\",\n      \"quantity\": 2,\n      \"price\": { \"amount\": 25.00, \"currency\": \"USD\" },\n      \"weight\": { \"value\": 0.2, \"unit\": \"kg\" },\n      \"hs_code\": \"610910\",\n      \"origin_country\": \"IN\"\n    },\n    {\n      \"description\": \"Wireless Bluetooth earbuds with charging case\",\n      \"sku\": \"EARBUDS-BT-001\",\n      \"quantity\": 1,\n      \"price\": { \"amount\": 89.99, \"currency\": \"USD\" },\n      \"weight\": { \"value\": 0.15, \"unit\": \"kg\" },\n      \"hs_code\": \"851830\",\n      \"origin_country\": \"CN\",\n      \"battery\": {\n        \"material_type\": \"lithium_ion\",\n        \"packing_type\": \"contained_in_equipment\"\n      }\n    }\n  ],\n  \"parcels\": [\n    {\n      \"weight\": { \"value\": 0.9, \"unit\": \"kg\" },\n      \"dimension\": {\n        \"width\": 30,\n        \"height\": 20,\n        \"depth\": 15,\n        \"unit\": \"cm\"\n      },\n      \"parcel_items\": [\n        { \"sku\": \"TSHIRT-W-M-NAVY\", \"quantity\": 2 },\n        { \"sku\": \"EARBUDS-BT-001\", \"quantity\": 1 }\n      ]\n    }\n  ]\n}
\n
\n

In this version, the seller and exporter are derived from carrier account defaults, the buyer is derived from the dropoff address, and the incoterm comes from the carrier account's configured default. The customs object is omitted entirely.

\n
\n

Troubleshooting

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SymptomLikely causeFix
Booking fails with \"incoterm not supported\"Incoterm value not accepted by this carrierCheck the carrier-specific incoterm table and use a supported value.
Customs hold or clearance delayMissing or vague item description, missing hs_code, or incorrect origin_countryEnsure all items have specific descriptions, accurate HS codes, and correct origin country.
\"Missing registration number\" errorCarrier requires a tax ID on one of the customs partiesAdd the appropriate registration_numbers to the seller, buyer, importer, or exporter.
Carrier charges higher than expectedMissing parcel dimension causing estimated volumetric weightAlways provide accurate parcel dimensions.
\"Missing customs data\" errorCarrier requires customs declaration but no customs data was providedEnsure the carrier account is configured for customs declarations , and that items have hs_code and origin_country.
Duties charged to wrong partyIncorrect incoterm (e.g. DDP when it should be DAP, or vice versa)Verify the incoterm matches your commercial agreement with the buyer.
Shipment rejected at originMissing exporter registration numbers or export licenseAdd EOR or other required registration numbers to customs.exporter.
Refused delivery / customer complaints about duty chargesCustomer unaware of import duty liability under DAP/DDUConsider switching to DDP or adding duty estimates to your checkout flow.
","headings":[{"value":"Integrate Cross-Border Shipments","depth":1},{"value":"When to use this guide","depth":2},{"value":"How Carriyo resolves cross-border data","depth":2},{"value":"Cross-border data checklist","depth":2},{"value":"1. Item-level customs data","depth":3},{"value":"Required item fields","depth":4},{"value":"Additional item fields for compliance","depth":4},{"value":"2. Parcel-level details","depth":3},{"value":"3. Shipment-level customs context","depth":3},{"value":"4. Customs parties","depth":3},{"value":"When are these parties needed?","depth":4},{"value":"Party field structure","depth":4},{"value":"Registration numbers","depth":4},{"value":"Incoterms reference","depth":2},{"value":"Supported values","depth":3},{"value":"Choosing the right incoterm for e-commerce","depth":3},{"value":"Carrier-specific incoterm support","depth":3},{"value":"Incoterm resolution: shipment vs. carrier account","depth":3},{"value":"Configuring defaults on the carrier account","depth":2},{"value":"Incoterm default","depth":3},{"value":"Customs party defaults (seller, buyer, exporter, importer)","depth":3},{"value":"Smart party defaults","depth":3},{"value":"Other carrier-specific settings","depth":3},{"value":"Recommended integration flow","depth":2},{"value":"Step 1: Configure carrier account defaults","depth":3},{"value":"Step 2: Create shipments with per-order data","depth":3},{"value":"Step 3: Confirm and monitor","depth":3},{"value":"Example: Cross-border shipment with full customs data","depth":2},{"value":"Simplified version using carrier account defaults","depth":3},{"value":"Troubleshooting","depth":2}]},"contentItem":{"data":{"lastModified":"2026-04-17T13:42:00.000Z","enableToc":null,"disableLastModified":null,"tocMaxDepth":null,"requestLogin":false}},"siteConfig":{"enableToc":false,"disableLastModified":false,"tocMaxDepth":4}},"pageContext":{"matchPath":"","id":"5a36d03a-a7e1-50ef-ba4e-5a8f28424755__redocly content/guides/integrate-cross-border-shipments/","seo":{"title":"Integrate Cross-Border Shipments","description":null,"image":"","keywords":null,"jsonLd":null,"lang":null,"siteUrl":null},"pageId":"guides/integrate-cross-border-shipments.md","pageBaseUrl":"/guides/integrate-cross-border-shipments","type":"markdown","toc":{"enable":true,"maxDepth":4,"headings":[{"depth":1,"value":"Integrate Cross-Border Shipments","id":"integrate-cross-border-shipments"},{"depth":2,"value":"When to use this guide","id":"when-to-use-this-guide"},{"depth":2,"value":"How Carriyo resolves cross-border data","id":"how-carriyo-resolves-cross-border-data"},{"depth":2,"value":"Cross-border data checklist","id":"cross-border-data-checklist"},{"depth":3,"value":"1. Item-level customs data","id":"1-item-level-customs-data"},{"depth":4,"value":"Required item fields","id":"required-item-fields"},{"depth":4,"value":"Additional item fields for compliance","id":"additional-item-fields-for-compliance"},{"depth":3,"value":"2. Parcel-level details","id":"2-parcel-level-details"},{"depth":3,"value":"3. Shipment-level customs context","id":"3-shipment-level-customs-context"},{"depth":3,"value":"4. Customs parties","id":"4-customs-parties"},{"depth":4,"value":"When are these parties needed?","id":"when-are-these-parties-needed"},{"depth":4,"value":"Party field structure","id":"party-field-structure"},{"depth":4,"value":"Registration numbers","id":"registration-numbers"},{"depth":2,"value":"Incoterms reference","id":"incoterms-reference"},{"depth":3,"value":"Supported values","id":"supported-values"},{"depth":3,"value":"Choosing the right incoterm for e-commerce","id":"choosing-the-right-incoterm-for-e-commerce"},{"depth":3,"value":"Carrier-specific incoterm support","id":"carrier-specific-incoterm-support"},{"depth":3,"value":"Incoterm resolution: shipment vs. carrier account","id":"incoterm-resolution-shipment-vs-carrier-account"},{"depth":2,"value":"Configuring defaults on the carrier account","id":"configuring-defaults-on-the-carrier-account"},{"depth":3,"value":"Incoterm default","id":"incoterm-default"},{"depth":3,"value":"Customs party defaults (seller, buyer, exporter, importer)","id":"customs-party-defaults-seller-buyer-exporter-importer"},{"depth":3,"value":"Smart party defaults","id":"smart-party-defaults"},{"depth":3,"value":"Other carrier-specific settings","id":"other-carrier-specific-settings"},{"depth":2,"value":"Recommended integration flow","id":"recommended-integration-flow"},{"depth":3,"value":"Step 1: Configure carrier account defaults","id":"step-1-configure-carrier-account-defaults"},{"depth":3,"value":"Step 2: Create shipments with per-order data","id":"step-2-create-shipments-with-per-order-data"},{"depth":3,"value":"Step 3: Confirm and monitor","id":"step-3-confirm-and-monitor"},{"depth":2,"value":"Example: Cross-border shipment with full customs data","id":"example-cross-border-shipment-with-full-customs-data"},{"depth":3,"value":"Simplified version using carrier account defaults","id":"simplified-version-using-carrier-account-defaults"},{"depth":2,"value":"Troubleshooting","id":"troubleshooting"}]},"data":{"title":""},"catalogInfo":null,"link":"/guides/integrate-cross-border-shipments/","sidebarName":"guides","isLanding":false,"showPrevButton":null,"showNextButton":null,"apiVersions":null,"apiVersionId":null,"isDefaultApiVersion":null}},"staticQueryHashes":["1123603147","1302185487","1344209882","1398840060","1520077861","1975142765","2667623876","2950305614","3240152602","3743992808","561138138"]}