Integrate Cross-Border Shipments

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.

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.

When to use this guide

Use this guide when you are:

• Shipping goods across international borders that require customs clearance.
• Integrating with carriers that require commercial invoice data (DHL Express, FedEx, UPS, DB Schenker, etc.).
• Shipping to or from regions with specific regulatory requirements (e.g. EU IOSS, GCC VAT, India GST).
• Handling DDP (Delivered Duty Paid) or DDU (Delivered Duty Unpaid) flows where duty responsibility must be declared.

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

How Carriyo resolves cross-border data

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.

The resolution order is:

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

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).

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.

Cross-border data checklist

1. Item-level customs data

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

Required item fields

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".

Additional item fields for compliance

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

2. Parcel-level details

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.

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.

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.

3. Shipment-level customs context

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

4. Customs parties

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.

When are these parties needed?

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

• Seller + Buyer : Required by most carriers for any cross-border shipment. These are the core commercial invoice parties.
• Exporter : Often the same as the seller, but may differ if a third-party logistics provider handles export. Required by carriers like DHL Express for the customs declaration.
• Importer : Often the same as the buyer, but critical when a dedicated importer of record handles customs clearance at the destination. The importer typically carries the tax/duty registration numbers for the destination country.
• Broker : Used when a customs broker is involved in clearance. Common with FedEx shipments that use broker-assisted import.

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).

Party field structure

Each customs party uses the same address structure:

Registration numbers

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.

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

Each registration number has three fields:

Supported registration number types:

Common scenarios:

• Shipping to the EU (under EUR 150): The seller's or importer's IOSS number should be provided. This enables simplified customs clearance and ensures VAT is collected at the point of sale rather than at import.
• Shipping to the UK: The importer should have an EOR (EORI) number. The seller may need a UK VAT number if registered.
• Shipping to/from India: PAN and GST numbers are commonly required on the exporter and importer.
• Shipping to/from GCC countries: VAT registration numbers are required for commercial shipments.

Incoterms reference

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.

Supported values

Choosing the right incoterm for e-commerce

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

• DAP (Delivered at Place) — The seller ships to the destination and the buyer pays any import duties and taxes upon delivery. This is the most common incoterm for international e-commerce. The buyer may be asked to pay duties at the door, which can lead to refused deliveries if unexpected.
• DDP (Delivered Duty Paid) — The seller covers all costs including import duties, taxes, and customs clearance fees. This provides a better customer experience (no surprise charges at delivery) but the seller assumes full duty and tax liability. Requires the seller or their agent to have the ability to pay duties in the destination country.

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.

Carrier-specific incoterm support

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

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

Incoterm resolution: shipment vs. carrier account

Incoterms follow Carriyo's standard configuration hierarchy:

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

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.

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).

Configuring defaults on the carrier account

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.

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.

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

Incoterm default

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.

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

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:

• The seller/exporter is always the same entity (your company) across all shipments.
• The importer is a fixed third-party agent handling customs clearance at the destination.

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.

Smart party defaults

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

• Seller defaults to pickup — If no seller is configured on the shipment or the carrier account, the pickup address is used as the seller.
• Buyer defaults to dropoff — If no buyer is configured on the shipment or the carrier account, the dropoff address is used as the buyer.

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.

Other carrier-specific settings

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

• DHL Express : customs declarable flag, invoice type and template, invoice signatory details, shipper and receiver registration numbers.
• FedEx : customs broker details (name, address, account number), terms of sale.

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.

Recommended integration flow

Step 1: Configure carrier account defaults

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

• Default incoterm, if all shipments through this account use the same trade terms.
• Seller and exporter details, including addresses and tax registration numbers.
• Smart defaults (seller-to-pickup, buyer-to-dropoff) if appropriate for your flow.
• Any carrier-specific customs settings (e.g. customs declarable flag for DHL).

Step 2: Create shipments with per-order data

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

• items[] : Complete item details including description , sku , quantity , price , hs_code , origin_country , and weight .
• parcels[] : Accurate packed weight, dimensions, and item-to-parcel mapping.
• customs.buyer or customs.importer : If the buyer or importer differs from the dropoff address (or if smart defaults are not enabled).
• customs.incoterms : Only if it differs from the carrier account default.
• customs.declaration_statement : If required by your carrier or lane.

Step 3: Confirm and monitor

1. Confirm the shipment once fulfillment and parcelization are final using Confirm Shipment . Carriyo validates all required fields at confirmation time.
2. Monitor for errors. Common cross-border booking failures include:
   • Missing or invalid hs_code
   • Missing origin_country on items
   • Missing description on items
   • Missing or inaccurate parcel weight or dimension
   • Missing registration numbers on customs parties
   • Unsupported incoterm for the carrier
3. Correct and retry. Use Patch Shipment to fix individual fields without replacing the entire shipment payload, then retry the booking using Reprocess Shipment .

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

Example: Cross-border shipment with full customs data

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.

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

Simplified version using carrier account defaults

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:

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

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.

Troubleshooting