How to correctly format international addresses: A guide for shipping APIs

For machine-readable international shipping labels, each recipient address must be output as a structured field set, with the destination country always appearing in capital letters on the last line. Those formatting international addresses don't need a single global format, but rather a system that understands country-specific field rules, returns component confidence, and triggers a review queue in case of uncertainty instead of blocking checkout.

The three rules that every address must meet before a label is printed:

• Structured fieldset: recipient_name, company, address_line_1 (Street + house number), address_line_2 (Additional floor/level), postal_code, city, administrative_area, country_code — in this order, stored separately, never as a free text blob.
• Last line = COUNTRY IN CAPITAL LETTERS: Written out in full in an internationally understandable language, never abbreviated.
• Component confidence before label printing: Each field receives its own confidence score; fields with a low score trigger customer confirmation or manual review, not a hard checkout rejection.

Key insights

Correctly formatted foreign addresses with component confidence and automatic review queue are the most reliable method to prevent carrier rejections and returns.

Theme	Details
Mandatory structure for labels	Structured fieldset with country_display as the last line in capital letters, maximum five lines.
Country-first capture	Identifying the target country first improves parsing accuracy and activates country-specific validation rules.
Confidence scoring	Each address field receives its own score; low scores trigger customer confirmation or review queue.
Transliteration and original script	Both versions are saved: Latin script for Carrier API, original script for local delivery.
International Package	Automated label and customs form generation, multi-carrier mapping and address validation in one platform.

Table of Contents

• Which address fields your system must output by default
• Which UPU and country rules you must always follow
• When to transliterate, when to ask the customer.
• What the automated validation workflow should look like
• What you need to consider regarding label layout and barcode specifications
• Developer checklist and sample JSON mapping
• Which test cases prevent shipping errors?
• International package automates formatting, validation, and label generation
• Sources

Which address fields your system must output by default

A carrier API does not accept free-text addresses. It requires discrete, named fields. The following table shows the minimum schema for international shipping labels:

The field raw_local_script It may seem optional, but for carriers like DHL it is often mandatory for shipments to Japan or China because local delivery personnel cannot read the transliterated version. International autocomplete and verification solutions Reduce typos early and standardize addresses before saving.

Pro tip: Speichern Sie raw_local_script Always alongside the transliterated version. Provide the carrier with the Latin text field; keep the original for returns and local delivery services.

Which UPU and country rules you must always follow

The Universal Postal Union (UPU) recommendsThe formatting of the destination address must follow the specifications of the respective destination country, and the country name must appear in full, in capital letters, on the last line. This is not a recommendation that can be ignored: Carrier sorting systems read the last line as the country code.

Other binding requirements that often cause problems:

• Maximum five lines on the shipping label; more lines are often not fully captured by automatic scanners.
• Right half placement The shipping label and customs form must be on the same page, with no overlap with the barcode or address field. USPS International Mail Manual It prescribes capital letters for all address lines and requires a separate return address.
• Machine-readable font, no pencil, no handwriting on carrier labels.
• Country-specific features: In the USA, the state is represented by a two-letter abbreviation (e.g. CA, NY) Mandatory. In France, the postal code comes before the city (75001 PARISJapan and China expect the address in reverse order (country → province → city → street → name), which must be converted to a Western format for label printing. Russia requires Cyrillic for local delivery but Latin script for international carriers. Countries without postal codes (e.g., Ireland, Hong Kong) require precise city names or district names instead.

When to transliterate, when to ask the customer.

Transliteration means transferring the characters of a script into Latin equivalents, not a translation of the content. Москва becomes Moskva, not to MoscowThis difference is relevant for carrier systems because a translation can distort the place name.

Practical rules for common writing systems:

• Cyrillic (Russia, Ukraine, Bulgaria): Use ISO 9 or GOST 7.79 as the transliteration standard; always save both versions.
• Kanji/Kana (Japan): Hepburn romanization for carrier APIs; local delivery requires the original.
• Arabic: ALA-LC transliteration for postal services; retain original script for local delivery personnel.
• Diacritics (French, Spanish, German): Carriers like USPS accept ASCII normalization (é → e), but many European carriers process UTF-8 correctly. Explicitly test your carrier's behavior.

Automatic conversion is risky in situations of high uncertainty. USPS recommends For non-Latin scripts, an English interline translation or romanized representation should be provided. If the system cannot provide a reliable transliteration, the checkout should prompt the customer for a Latin script.

Pro tip: Show the customer a preview field with the transliterated address at checkout and ask for confirmation. This takes two seconds and prevents misdeliveries.

What the automated validation workflow should look like

A production-ready pipeline for international addresses consists of five steps, which take place in this order:

• Country code first: Enter the destination country in the first field. Country-first capture This improves parsing accuracy because all subsequent rules (field order, postal code format, mandatory fields) are country-dependent.
• Parsing in components: Parsing free-text input into discrete fields. House number parsing is particularly error-prone: In Germany, the house number follows the street name (Hauptstraße 12), in the USA before (12 Main Street).
• Normalization: Explain abbreviations (Str. → Straße), Check postal code formats (US-ZIP: 5 or 9 characters, DE-PLZ: 5 characters), force uppercase for label lines.
• Reference matching and confidence scoring: Comparison against postcode databases (e.g., Google Address Validation API, Loqate). Google recommends three possible response scenarios: Accept (Address correct, continue) Confirm (Deviation detected, obtain customer confirmation) Fix (Critical fields are missing, demand is required).
• Fallback and review queue: If a reference check at the building level is not possible, downgrade to the postal code and city level. Component-related confidence scores and a manual review queue are better than a hard checkout block.

Pro tip: Call the validation API at checkout, not after payment is complete. Correcting an address after order confirmation is significantly more work than waiting a second at checkout.

What you need to consider regarding label layout and barcode specifications

The shipping label and customs form must be on the same side of the package, preferably on the right-hand side. The barcode and address field must not overlap. Specific requirements:

• Barcode standard: GS1-128 or carrier-specific formats (DHL: Waybill barcode, UPS: MaxiCode + Code 128). Adhere to the minimum contrast and minimum size specified by the carrier; a barcode printed too small will result in scan errors.
• Font: Sans-serif font, minimum size 8 pt for address lines, 10 pt recommended. No footnotes or advertising copy in the address lines.
• Return address: Full sender address in Latin script, top left, clearly separated from the recipient address.
• Customs declaration: Always electronic and computer-generated. USPS and major carriers require computer-generated customs declarations with a complete description of goods. Handwritten customs documents will result in delays or rejection by major carriers. See instructions for correct placement of Shipping documents can be found in the International Package documentation.

Developer checklist and sample JSON mapping

The recommended JSON schema for an international shipping stack:

Field name	Type	mandatory	Parser note
country_code	ISO alpha-2 code	Ja	Always capture first
recipient_name	String, max. 35 characters	Ja	Please observe the carrier limit
company	String, max. 35 characters	Optional	Leave blank if not present
address_line_1	String, max. 35 characters	Ja	Street + house number, country-specific order
address_line_2	String, max. 35 characters	Optional	Apartment, Floor, c/o
postal_code	String	conditioned	Validate regular expressions for each country
city	String	Ja	Latin script
administrative_area	String	conditioned	Mandatory for USA, Canada, Australia
raw_local_script	String	Optional	Original text for local delivery
transliterated	String	conditioned	Latin script version for Carrier API

A typical mapping from raw input to label output:

{
  "raw_input": "田中太郎, 東京都渋谷区神南1-19-11",
  "parsed_components": {
    "country_code": "JP",
    "recipient_name": "田中太郎",
    "address_line_1": "神南1-19-11",
    "city": "渋谷区",
    "administrative_area": "東京都",
    "raw_local_script": "東京都渋谷区神南1-19-11"
  },
  "formatted_label_output": {
    "line_1": "TANAKA TARO",
    "line_2": "1-19-11 JINNAN",
    "line_3": "SHIBUYA-KU, TOKYO 150-0041",
    "line_4": "JAPAN"
  }
}

Further points for implementation:

• Set API timeouts to a maximum of 2 seconds; configure a secondary validation provider as a fallback.
• Store confidence scores and normalization rules in the audit trail field (raw_input, reference data source used, confidence per component, timestamp).
• Document overwrites made by employees; do not silently accept them.
• Handle address data in accordance with GDPR: limit storage duration, restrict access to the shipping team, and do not share data with third parties without a legal basis. Paket International offers pre-configured interfaces for API and plugin integrations.

Which test cases prevent shipping errors?

These cases should be explicitly tested before going into production:

• Missing postal code: Countries without postal codes (Ireland, Hong Kong) must be able to be processed without a mandatory postal code field.
• Duplicate place names: Springfield It exists in over 30 US states. Without administrative_area The address is ambiguous.
• Special characters and umlauts: Müller → Mueller or MullerTest the carrier behavior explicitly for each destination country.
• Long names: Carrier limits are often 35 characters per line. Names like Gesellschaft für internationale Handelsbeziehungen mbH must be abbreviated without jeopardizing deliverability.
• APO/FPO addresses (US military): It uses its own formatting rules, not a standard street format.
• Mixed writings: An address with a Cyrillic street name and a Latin city name must be correctly separated and transliterated.
• Bulky goods: For large shipments, additional address fields may be required by shipping companies. See below for further information. Planning of special transports demonstrate how documentation is structured for complex freight shipments.

Monitoring metrics that should be continuously tracked: response rate per destination country, scan error rate per carrier, percentage of manual reviews, confidence distribution per field type. Set up alerts for increasing carrier rejection rates for individual countries or postal code areas.

Pro tip: Perform a monthly bulk revalidation of older address data. Street names, postal code boundaries, and carrier requirements change. An SLA for manual reviews (e.g., 24 hours) prevents unresolved issues from blocking shipments.

International package automates formatting, validation, and label generation

Anyone looking to scale international shipping processes will quickly reach the limits of manual address maintenance. Paket International combines these steps into a single platform: Multi-carrier shipping software with automatic label and customs form generation, confidence-based address handling and direct connection to DHL, UPS, FedEx, DPD and DB Schenker.

 

The platform handles parsing, normalization, and carrier mapping, generates customs declarations electronically, and directs insecure addresses to a review queue instead of blocking checkout. For online shops, a WooCommerce plugin ready; an open API for individual stacks. automated customs clearance Reduces manual intervention and lowers the error rate in customs documents. Test the integration now and process your first international shipment fully automatically.

Sources

Recommended resources for implementation and compliance:

• Address Elements and Formatting An International Address — UPU
• How to Send an International Package | USPS
• International Addressing Guidelines — USPS IMM
• Address validation for checkout | Google Maps Platform
• Make international address data accuracy your business's hidden superpower — Smarty

Suggestions

• Creating shipping labels for online retailers made easy
• Shipping documents: Important information and tips
• Send international shipments worry-free and stress-free
• Shipping to Switzerland Customs: How to avoid delays