About data handling and character normalization

When you send shipment data to Shipium's APIs, certain characters and formatting may be automatically transformed before being passed to carriers. This normalization ensures compatibility across the diverse systems used by shipping carriers, many of which have restrictions on supported character sets.

Understanding these transformations helps you set accurate expectations for how your data will appear on shipping labels and in carrier systems.

Why Shipium normalizes data

Shipping carriers operate on a wide range of technology platforms, from modern cloud-based systems to legacy infrastructure built decades ago. These systems often have different—and sometimes strict—requirements for the characters they accept in address fields, recipient names, and other shipment data.

When a carrier system encounters an unsupported character, it may reject the request entirely, replace the character with a placeholder like ? or _, or misinterpret the data in ways that affect delivery. Shipium's normalization process proactively transforms data to prevent these issues, maximizing successful label generation and accurate address interpretation across carriers.

Character set

Shipium APIs accept data encoded in UTF-8, which supports a wide range of international characters. However, because many carrier systems have more limited character support, Shipium applies transformations to ensure compatibility before sending data to carriers.

Standard transformations

The following transformations are applied to shipment data for all carriers.

Whitespace normalization

Shipium removes leading and trailing whitespace from field values and collapses multiple consecutive spaces into a single space. For example, " 123 Main Street " becomes "123 Main Street". This ensures clean, consistent data that meets carrier formatting expectations.

Special character replacement

Certain Unicode characters that appear visually similar to common ASCII characters are replaced with their ASCII equivalents. For example, the Unicode minus sign (−) is replaced with a standard hyphen-minus (-). This prevents carrier systems from treating these characters as unsupported special characters.

Accent and diacritic removal

Accented characters are converted to their non-accented equivalents to ensure compatibility with carrier systems that only support basic ASCII characters. Common examples include:

é → e
ñ → n
ü → u
ç → c

This means an address containing "Montréal" will be sent to the carrier as "Montreal."

Carrier-specific restrictions

Some carriers—primarily U.S. domestic carriers—have stricter character requirements than others. For these carriers, Shipium applies additional sanitization to remove characters that would cause errors or unexpected behavior.

For carriers with strict requirements, only the following characters are permitted:

Letters. A–Z, a–z
Numbers. 0–9
Permitted punctuation. apostrophe ('), period (.), comma (,), hyphen (-), parentheses ( )

Any character not in this set is removed from the data before it is sent to these carriers. This includes special symbols, currency signs, and other non-ASCII characters that survived the standard transformation process.

International carriers

International carriers often have broader character support to accommodate addresses in various languages and scripts. For these carriers, Shipium may apply less restrictive sanitization, preserving more of the original character data when the carrier's systems support it. The specific transformations applied depend on the requirements of each carrier.

Best practices

To ensure your shipment data is processed as expected, consider the following recommendations.

Use standard ASCII characters when possible. While Shipium accepts UTF-8 encoded data, using standard ASCII characters (A–Z, a–z, 0–9, and common punctuation) reduces the likelihood of unexpected transformations, particularly for U.S. domestic shipments.

Understand your shipping profile. If you primarily ship domestically within the United States, using ASCII characters provides the most predictable results. If you ship internationally, be aware that character handling may vary by carrier and destination.

Avoid special Unicode characters. Characters like smart quotes (" "), em dashes (—), and other typographic characters may be removed or replaced. Use their standard ASCII equivalents instead.

Test with representative data. If your shipment data regularly includes international characters or special symbols, test your integration to understand how these characters will appear after normalization.

Review label output. If you notice unexpected character replacements on shipping labels, review the original data you submitted to identify characters that may have been transformed.

Affected fields

Character normalization applies to text fields in shipment requests, including but not limited to:

Recipient name (destinationAddress.name)
Company name (destinationAddress.company)
Street address lines (destinationAddress.street1, destinationAddress.street2)
City name (destinationAddress.city)

Related resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful: