Address mapping between a store and an ERP: one line, two lines or three fields

The problem in one address

A customer of a B2B store fills in the checkout. Shopify delivers the shipping address of the order like this:

{
  "shipping_address": {
    "company": "Harlow Industrial Supply and Fastener Co., Inc.",
    "name": "Dana Whitfield",
    "address1": "1250 North Commerce Parkway Building C Suite 400",
    "address2": "Attn: Receiving, dock 4",
    "city": "Worcester",
    "province": "Massachusetts",
    "province_code": "MA",
    "zip": "01608-1127",
    "country_code": "US"
  }
}

Every value is valid in the store. On the way to the ERP and the carrier, five of them need work: a company name of 47 characters, an address line of 48, an instruction in the second line, a state that exists as a name and as a code, and a ZIP code with a leading zero and a hyphen.

The two lines are free text, so customers fill them in every possible order:

One line or two is only part of it. USPS Publication 28 breaks a delivery address line into seven components: primary address number, predirectional, street name, suffix, postdirectional, secondary address identifier and secondary address. 1250 N COMMERCE PKWY STE 400 uses six of them. A system that wants number, street and unit as three fields needs that parsing. A rule written for US addresses, number first, fails on a Dutch or German address, where the number follows the street.

What each system stores

The field names below were read from each vendor's documentation on October 3, 2026.

Between two systems of the same shape little happens: the two lines of Shopify go into addr1 and addr2 of NetSuite unchanged. The work starts where the shapes differ. A BigCommerce order gives the state as Texas, and UPS accepts only TX. The customer table of Business Central has no field called state: the state goes into County.

Names differ in the same way. NetSuite has an addressee and an attention field on every address, and its field help marks attention as required for the UPS integration. UPS has Name for the company and AttentionName for the person. A consumer order has no company, so the person's name goes into addressee and Name, and the attention line stays empty.

State, ZIP code and country

State. USPS lists 62 two-letter codes: the 50 states, the District of Columbia, 8 territories and associated states such as PR and GU, and 3 codes for military mail, AA, AE and AP. A lookup table with 50 rows rejects 12 of them. The table also has to accept what people type: Massachusetts, Mass., ma. cXML, the format of PunchOut orders, carries the state a third way, as isoStateCode="US-MA".

ZIP code. A ZIP code is 5 digits, or 9 as ZIP+4. USPS writes ZIP+4 with a hyphen, 01608-1127; it is the one punctuation mark Publication 28 does not allow to be omitted. The UPS API wants 5 or 9 digits and allows 9 characters at most, so the same value goes to UPS as 016081127. ZIP codes in Massachusetts start with a zero. In a numeric column, or in a CSV file saved from Excel, 01608 becomes 1608. That is 4 digits and matches nothing. More on files in supplier CSV and Excel files.

Country. US, USA, United States and United States of America are four spellings of one country. Shopify and WooCommerce send the two-letter ISO code. BigCommerce sends the name and the code. NetSuite's SOAP web services use their own list, where the value is _unitedStates. Puerto Rico is a state code at USPS, PR, and a separate country or territory in NetSuite's list and in the UPS API. The same address in San Juan is state PR in country US in one system and country PR in the next, and the lookup has to know which form each target expects.

Field lengths that truncate silently

A value that is too long for its target is refused by the API or shortened by the software in front of it. Shortening is the common case, and it raises no error. The limits of the targets in this example:

Run the example through them. The company name has 47 characters. UPS takes 35, so 47 minus 35 is 12 characters that have to go. Cut at the end, the label reads Harlow Industrial Supply and Fasten. The address line has 48 characters. It fits NetSuite's 50 with 2 to spare and exceeds the UPS line by 13. With USPS abbreviations, N for North, PKWY for Parkway, BLDG for Building and STE for Suite, it becomes 1250 N Commerce Pkwy Bldg C Ste 400: exactly 35.

The order of events hides the problem. The address is accepted by the store and by the ERP, and it is shortened two steps later, when the warehouse requests the label. UPS documents one such cut itself: a city of up to 30 characters is accepted and only 15 are printed. Rancho Santa Margarita, 22 characters, comes out as Rancho Santa Ma. The integration therefore measures each value against the shortest field downstream at the moment the order comes in.

One ship-to per order, or one per customer

An ERP stores addresses as records of the customer. On a NetSuite sales order the ship-to is one of three things: an existing address of the customer, a new address that is saved with the customer, or a custom address for this transaction only.

An integration that always creates a new address adds one to the customer with every order. A customer who orders 3 times a week has 156 addresses after a year, all for the same dock. Comparing the raw text does not prevent it: 1250 North Commerce Parkway, Suite 400 and 1250 N Commerce Pkwy Ste 400 are different strings and the same place. The comparison runs after normalization. The same mechanism on the customer record itself is described in duplicate customers and duplicate orders.

The ship-to in a PunchOut session

In a PunchOut integration an address appears twice. The PunchOutSetupRequest that opens the session may carry a ShipTo. The cXML Reference Guide describes it as optional and meant for estimating delivery time or price. The delivery address of the order is the ShipTo in the OrderRequest, at header level or per line.

A cXML address has its own shape: Name holds the company, DeliverTo can occur twice, first the person and then the location in the building, and the Address element can carry an addressID such as 2000431. That ID is the buyer's code for the location. Mapping the ID to a ship-to record in the ERP is more reliable than parsing the street lines again on every order.

How an integration handles it

Per field, three things are written down: which form the source delivers, which form each target needs, and what happens to a value that fits nowhere. That is field mapping, applied to the address.

What this means for your integration

We write down per address field how it moves from your store to your ERP and your carrier: the form the source delivers, the form each target needs and the length each target allows. In the dry run before go-live your existing orders pass through those rules, so you see which addresses do not fit before a single label is printed. After go-live every address the integration cannot place is on a review list in the dashboard, with the original lines next to it.

The order flow as a whole is on orders, customers and shipping, and the NetSuite side on the NetSuite integration page. Tell us which store, ERP and carriers you use, and we map the address fields between them.