Address Validation

Address mistakes are easy to make and expensive to fix. If a package can't be delivered, it travels out, comes back, and goes out again once you've tracked down the right address -- and you pay for all three legs. Validation is here to catch that before you buy the first label.

ShipGenius checks US addresses against USPS data for you. It runs on the ship screen before you buy, and it's available through the API too if you're building your own checkout.

What Validation Tells You

You get back more than a simple pass or fail:

• The original input exactly as you typed it.
• A normalized version standardized to USPS formatting -- correct street abbreviations, tidied-up directionals, and ZIP+4 when it can be worked out.
• Residential status, which is what carriers use to decide whether a residential surcharge applies.
• Warnings about anything that looks ambiguous or was only partly corrected.

The Four Outcomes

Verified

Your address matched USPS records cleanly. You'll see a green Address verified badge, and there's nothing else for you to do.

Suggested Correction

USPS matched your address but sent back a tidied-up version that differs a little from what you typed -- a corrected street type, a fixed directional, an added ZIP+4, or the right city for that ZIP. You'll see the suggestion with two choices: use the suggested version, or keep yours.

It's usually best to take the suggestion unless you have a reason not to. The USPS format is what carriers' own systems expect, so shipping the standardized version means fewer sorting mix-ups along the way.

Applying a suggestion drops the corrected fields into this shipment as a one-time address and checks it again. Your saved address stays exactly as it was -- if you'd like the correction kept for next time, edit the saved address itself.

Warnings

The address is deliverable, but something about it is a little unclear, and we'll tell you exactly what. The most common case is a building that needs a unit number when none was given -- deliverable in principle, but it may sit with the carrier while they work out which apartment it belongs to.

Warnings won't stop you from buying a label. They're a heads-up so you can fill in the missing piece when you're able to.

Invalid

USPS couldn't match the address at all, so a package sent there probably won't arrive. It's worth a second look for transposed digits in the ZIP, a misspelled street name, a missing unit number, or a city and state that don't line up.

Why the Residential Flag Matters

Nearly every carrier charges more to deliver to a home than to a business. Validation works out residential status from USPS data, and that answer feeds straight into your rates.

It matters in both directions. If an address is marked commercial when it's really residential, your rate comes in lower than what the carrier eventually bills, and the difference shows up later as an adjustment. If it's marked residential when it's really commercial, you've paid a surcharge you didn't need to.

Validating before you run rates is what keeps the price you see and the price you're billed the same number.

Scope and Limitations

Validation covers US addresses. International addresses aren't validated -- there's no single authoritative dataset for the rest of the world, and formats vary too widely. For those, it's worth double-checking the address yourself and paying extra attention to the destination country's postal conventions.

Validation confirms that an address exists and is formatted correctly. It can't tell you whether anyone still lives there, whether a business is still operating, or whether the recipient will accept the package.

Saved Addresses Skip This

Addresses in your saved address list have already been validated, so picking one instead of typing it skips the check entirely. That's part of why saved addresses make repeat shipping so much quicker -- worth setting up even for destinations you only ship to once a month.

Validation in the API

The address validation query takes a list of addresses and gives you a result for each one, so a checkout or an order importer can check them all at once. Most people use it to catch problem addresses when the order comes in rather than when it ships, and to spot residential deliveries while rating, so the estimate shown to a customer is accurate.

FAQs

Does validation guarantee delivery?

No. It confirms the address exists and is formatted correctly. It can't tell you whether the recipient is still there, whether a business is still open, or whether the package will be accepted.

Can I ship to an address that failed validation?

Yes -- validation never blocks a purchase. An invalid result is a strong hint that something is off, though, and those shipments often come back to you, so a quick double-check first usually saves you a second label.

Why is my address getting a suggestion when it looks right?

USPS has firm preferences about abbreviations, directionals, and ZIP+4. Most suggestions are a formatting tidy-up rather than a real correction, so taking it won't change where your package goes.

Are international addresses validated?

No -- validation is US-only. It's worth double-checking international addresses yourself, especially the postal code format, which varies quite a bit from country to country.

What does the residential flag do to my rate?

Most carriers add a residential delivery surcharge. The flag goes to the carrier when you run rates, so an accurate flag is what keeps your rate and your invoice matching.

Does applying a suggestion change my saved address?

No. The correction applies to this shipment only, as a one-time address. If you'd like to keep it for next time, edit the saved address directly.

Can I validate addresses in bulk before importing orders?

Yes, through the API -- the validation query takes a list of addresses. It's the best way to catch problem addresses at order entry rather than at fulfillment.