International Shipments

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

To ship internationally, your package will be required to go through customs in the destination country. For your shipment to effectively pass through customs, include all the required data for customs declarations in your create shipment request and create label request.

Requirements

International shipments must include the required properties for the customs, products, and tax_identifiers objects. You may also need to add specific details like harmonized_tarrif_code and vat_rate to each of the products in your shipment.

Specific properties may be required depending on which countries you are shipping to and which carriers you are using. Be sure to check with your carrier and customs authority if you are uncertain what details you need to include with your shipments.

Customs Object Properties

NOTE:

Deprecated: The customs_items Object

As of July 31, 2023, the customs_items object has been deprecated. All properties for customs items should now be added to the products object, which also includes 3 additional fields not previously available for customs_items.

While we will continue to support customs_items temporarily, you cannot use both customs_items and products in your create shipment request. Your request can only contain one of them.

Products Object

When you request an international shipping label, you are required to send ShipStation API a list of that shipment's contents, along with their declared values. The following table describes the properties available.

Tax Identifiers Object

ShipStation API supports adding tax IDs to your shipment to comply with current international shipping requirements. Note that the tax_identifiers object exists inside the shipments object, so you will need to take this into account when creating both shipments and labels.

Downloading Forms

Any forms you will need to include with your shipment will be in the form_download object. In some cases, the form_download object will be empty, as is the case with electronic submissions or carriers that print customs details directly on the label (like USPS).

• When shipping with UPS, FedEx, or DHL Express, ShipStation API can electronically submit your forms to the carrier.
• When using USPS, your customs forms print with your label rather than as separate documents.
• For other carriers, you will need to download and print any generated files and include them in your shipment.

Example Request & Response

Now that you understand the objects required for international shipping, we can drop those into a basic label request by adding a products object, customs object, and tax_identifiers object.

POST /v1/labels

POST /v1/labels HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
  "shipment": {
    "service_code": "usps_priority_mail_international",
    "ship_from": {
        "company_name": "Example Corp.",
        "name": "John Doe",
        "phone": "111-111-1111",
        "email": "sender@example.com",
        "address_line1": "4301 Bull Creek Rd Ste. 300",
        "city_locality": "Austin",
        "state_province": "TX",
        "postal_code": "78731",
        "country_code": "US",
        "address_residential_indicator": "no"
    },
    "ship_to": {
      "name": "John Doe",
      "company_name": "Example Corp",
      "address_line1": "Röntgenstr. 3",
      "city_locality": "Esslingen am Neckar",
      "state_province": "Stuttgart",
      "postal_code": "73730",
      "country_code": "DE",
      "phone": "5555555555",
      "email": "recipient@example.com"
    },
    "packages": [
      {
        "content_description": "Dog Toys",
        "products": [
          {
            "quantity": 4,
            "value": {
              "currency": "usd",
              "amount": 75
            },
            "sku": "4225-776-3234",
            "sku_description": "Rubber-Ball",
            "harmonized_tariff_code": "4016.99.20",
            "country_of_origin": "US",
            "description": "Pet Chew Toy",
            "product_url": "https://tinyurl.com/adorable-womabt",
            "mid_code": "123456",
            "vat_rate": 0.02,
            "weight": {
              "value": 1,
              "unit": "ounce"
            }
          },
          {
            "quantity": 2,
            "value": {
              "currency": "usd",
              "amount": 100
            },
            "sku": "3001-776-3234",
            "sku_description": "Tug-of-War-Rope",
            "harmonized_tariff_code": "6307.90.75",
            "country_of_origin": "US",
            "description": "Cotton Pet Chew Toy",
            "product_url": "https://tinyurl.com/adorable-womabt",
            "mid_code": "123456",
            "vat_rate": null,
            "weight": {
              "value": 2,
              "unit": "ounce"
            }
          }
        ],
        "package_id": "se-3",
        "package_code": "package",
        "weight": {
          "value": 9.6,
          "unit": "ounce"
        },
        "dimensions": {
          "unit": "inch",
          "length": 10.0,
          "width": 8.0,
          "height": 8.0
        },
        "insured_value": {
          "currency": "usd",
          "amount": 0
        },
      }
    ],
    "customs": {
      "contents": "merchandise",
      "non_delivery": "treat_as_abandoned",
      "terms_of_trade_code": "DDP",
      "declaration": "I hereby certify that the information on this invoice is true and correct and the contents and value of this shipment is as stated above.",
    },
    "tax_identifiers": [
      {
      "taxable_entity_type": "shipper",
      "identifier_type": "eori",
      "value": "GB987654312000",
      "issuing_authority": "GB"
      }
    ]
  }
}

Example Response

Note that the customs, products, and tax_identifier objects are not returned in the response. Any customs forms and commercial invoices you need to print will be returned in the form_download object. In this example, since it uses a USPS service, the customs details are printed directly on the label, so no additional forms are returned.

{
    "label_id": "se-120659535",
    "status": "completed",
    "shipment_id": "se-236919990",
    "ship_date": "2022-01-04T00:00:00Z",
    "created_at": "2022-01-04T19:34:43.6076942Z",
    "shipment_cost": {
        "currency": "usd",
        "amount": 60.18
    },
    "insurance_cost": {
        "currency": "usd",
        "amount": 0.0
    },
    "tracking_number": "LX678657357US",
    "is_return_label": false,
    "rma_number": null,
    "is_international": true,
    "batch_id": "",
    "carrier_id": "se-121493",
    "service_code": "usps_priority_mail_international",
    "package_code": "package",
    "voided": false,
    "voided_at": null,
    "label_format": "pdf",
    "display_scheme": "label",
    "label_layout": "4x6",
    "trackable": false,
    "label_image_id": null,
    "carrier_code": "stamps_com",
    "tracking_status": "unknown",
    "label_download": {
        "pdf": "https://api.shipengine.com/v1/downloads/10/79vVrg0ovkSgviVkZS1csg/label-120659535.pdf",
        "png": "https://api.shipengine.com/v1/downloads/10/79vVrg0ovkSgviVkZS1csg/label-120659535.png",
        "zpl": "https://api.shipengine.com/v1/downloads/10/79vVrg0ovkSgviVkZS1csg/label-120659535.zpl",
        "href": "https://api.shipengine.com/v1/downloads/10/79vVrg0ovkSgviVkZS1csg/label-120659535.pdf"
    },
    "form_download": null,
    "insurance_claim": null,
    "packages": [
        {
            "package_id": 127260247,
            "package_code": "package",
            "weight": {
                "value": 4.00,
                "unit": "pound"
            },
            "dimensions": {
                "unit": "inch",
                "length": 0.0,
                "width": 0.0,
                "height": 0.0
            },
            "insured_value": {
                "currency": "usd",
                "amount": 0.00
            },
            "tracking_number": "LX678657357US",
            "label_messages": {
                "reference1": null,
                "reference2": null,
                "reference3": null
            },
            "external_package_id": null,
            "sequence": 1
        }
    ],
    "charge_event": "carrier_default"
}

Your label and customs forms can be found by going to label_download.href and links.form_download in the response, respectively.

Shipping from US to Canada

If you ship from the US to Canada using USPS First-Class Mail International, Priority Mail International, or Priority Mail Express International, you have the option to create a Delivered Duty Paid (DDP) shipment.

When you create a DDP shipment, you will be charged a flat fee to pay duties or taxes in advance so that your recipient does not have to pay them upon delivery. The fee is $9.95 for all eligible services.

To use the pre-pay DDP option, add an advanced option object to your shipment object with the canada_delivered_duty property set to "sender_prepay".

{
  "shipment":{
      "advanced_options": {
        "canada_delivered_duty":"sender_prepay"
    },
  }
}

Example Response

The flat fee will display in the other_amount field of the rate_response object. (This response is truncated to more easily demonstrate the relevant property.)

{
  "rate_response": {
    "rates": [
      {
        "rate_id": "se-2095723696",
        "rate_type": "shipment",
        "carrier_id": "se-3377959",
        "shipping_amount": {
          "currency": "usd",
          "amount": 14.11
        },
        "insurance_amount": {
          "currency": "usd",
          "amount": 0.0
        },
        "confirmation_amount": {
          "currency": "usd",
          "amount": 0.0
        },
        "other_amount": {
          "currency": "usd",
          "amount": 9.9500
        },
      "rate_details": []
      }
    ],
    "billing_source": "Carrier",
    "rate_request_id": "se-301944927",
    "shipment_id": "se-458174406",
    "created_at": "2022-11-04T20:45:30.2987928Z",
    "status": "completed",
    "errors": []
  },
}

Shipping to and from Mexico

The Mexican government requires all shipments to, from, and within Mexico to include a Bill of Lading Complement (Complemento Carta Porte). The Bill of Lading must include package-level merchandise descriptions, which are separate from traditional customs item information requirements.

To create a Bill of Lading with your shipping label and other customs documents, include the content_description property in the packages object of your label request.

For more information about the Carta Porte requirement, visit the Gobierno de México Servicio de Administración Tributaria page (Español) or the US International Trade Administration's Carta Porte page (English).

Example Packages Object

{
  "packages": [
    {
      "content_description": "Dog Toys",
      "products": []
    }
  ]
}

Shipping to the EU

All shipments to and passing through most countries in the EU require Harmonization Codes to be included on customs forms with accurate descriptions of the package contents.

This means that descriptions such as "Clothes" will not be accepted. Instead, more detailed descriptions such as "Men's Cotton Shirt" or "Women's Leather Shoes" are required.

Learn more about the Harmonization Code requirement from the following resources:

• Stamps.com Blog: New Harmonized Code Requirement Coming March 1
• USPS.com: New Customs Requirements for Packages to European Union (EU) Countries

Shipping to Northern Ireland

For merchants shipping from Great Britain to Northern Ireland, see our page to learn how to ship in accordance with the Windsor Framework.

Shipping to New Zealand: Low Value Goods (LVG) Levy

The New Zealand Customs and the Ministry for Primary Industries (MPI) are overhauling how they charge for border clearance, replacing old "goods fees" with new "goods management levies." For e-commerce, the biggest shift is the end of consolidated reporting subsidies.

As of April 1st, 2026, low-value parcels shipped into New Zealand will attract a mandatory border levy per consignment.

1. How much is the new levy for low-value e-commerce orders? For standard e-commerce air freight, the new Low-Value Goods (LVG) import levy is NZD $2.21 plus GST per consignment. This is a combined fee made up of a Customs levy ($1.46) and an MPI biosecurity levy ($0.75). If you ship via sea freight, the combined levy is slightly lower at NZD $2.09 plus GST.

2. Is this fee charged per item (like the EU) or per package? Unlike the upcoming EU regulations that charge based on item categories (HS codes), the New Zealand levy is much simpler. It is charged per consignment (specifically, per low-value customs declaration). If your NZ customer orders three different items shipped in the same box, it only attracts a single NZD $2.21 levy.

3. What is considered a "low-value" good in New Zealand? New Zealand defines low-value consignments as those with a total customs value of NZD $1,000 or less. Anything above this threshold triggers a formal import entry.

4. Does this apply if I use standard postal mail (like Australia Post)? Yes, but the billing structure is different. For goods arriving via the Universal Postal Union (UPU) mail stream, New Zealand is introducing an Import UPU mail levy of NZD $1.28 plus GST per kilogram. This will be billed directly to the postal carriers, meaning you will likely see this cost passed down to you in the form of increased standard international postage rates.

5. Who actually pays this new $2.21 levy? Legally, the levy is billed to the entity submitting the customs declaration—typically your freight forwarder, express courier (like DHL or FedEx), or broker. However, they will absolutely pass this cost along. You need to check with your logistics provider immediately to see if they will bill this back to you (the retailer) as a line-item surcharge, bake it into your base shipping rates, or pass it to the consumer upon delivery.

6. Does this replace the New Zealand GST I already collect? No. If your business sells more than NZD $60,000 annually to New Zealand consumers, you are still legally required to collect 15% GST at your online checkout. This new $2.21 levy is strictly a border management and biosecurity screening fee, completely separate from your GST obligations.

7. What happens if a customer's order is over NZD $1,000? Consignments over NZD $1,000 are classified as "high-value" and have entirely different rules. Under the new April 2026 fee structure, a high-value air import will attract a hefty combined Customs and MPI levy of NZD $51.81. Traditionally, the NZ consumer is responsible for paying this (along with import duties and GST) before the package is released, unless you deliberately ship Delivered Duty Paid (DDP) for high-value carts.

8. Why is the New Zealand Government doing this? The explosion of cross-border e-commerce has put a massive strain on NZ Customs and biosecurity screeners. Previously, low-value goods were largely subsidised by the taxpayer because they were cleared in bulk cargo reports. The government is implementing these levies to ensure full, fair cost-recovery directly from the shipments creating the workload.

9. With the change happening next month, what must I do right now?

• Forecast the hit: Pull your New Zealand order volume from the last 12 months and multiply it by NZD $2.21 to understand your exact margin exposure.

• Call your shipping rep: Ask your couriers and freight forwarders exactly how this levy will appear on your April invoices.

• Adjust pricing: Decide whether you will absorb this cost, incrementally raise your retail prices for the NZ market, or bump up your flat-rate shipping fee to cover the difference.

If you require further support or need assistance, please contact our local support team: support@shipstation.com.au.

International Shipping FAQ

What are Harmonization Codes?

The purpose of a Harmonization Code (also referred to as Tariff Codes, Customs Tariffs, Harmonized Tariff Codes, and Harmonized System Codes or HS Codes) is to expedite the delivery of international shipments. The system of codes for your goods is a universal economic language used to trade merchandise that is shipped internationally and assess taxes.

Once an order reaches an international border, the Harmonization Codes help the customs office to identify what it is you are shipping. We recommend that you list and properly identify your Harmonization Codes at the time of label creation.

For a full list of Harmonization Codes, use the Harmonized Tariff Schedule search.

IMPORTANT: USPS International Shipping Update - HS Codes Required

As of September 1, 2025, the U.S. Postal Service will require all international commercial shipments to include a six-digit Harmonized System (HS) code on customs declarations for each item, regardless of mail class. The HS code system, created by the World Customs Organization, is used by customs authorities worldwide to classify goods and assess tariffs. This update aligns USPS mailing standards with new Universal Postal Union (UPU) regulations, also taking effect Sept 1, requiring all member countries to enforce six-digit HS codes for commercial goods.

Does ShipStation API print USMCA forms for international shipments?

Currently, ShipStation API does not receive USMCA forms (formerly called NAFTA forms) from carriers for international shipments. If you'd like to include a USMCA form with a shipment, you must download and fill out the form outside of ShipStation API.