GoatLabels GoatLabels
The failure is a clue, not a verdict.

Why a real address fails validation


Fix it before the label, not after the return.

Address validation checks a delivery point against the carrier's database, so a failure means one of a few defects: a missing unit number, a street the database doesn't know yet, a ZIP that doesn't match the city, or a vanity city name. Each has a specific fix — applied before purchase, it costs nothing.

Checked at quote time, before money moves

Every destination is validated against the carrier's delivery-point data while you are still comparing USPS, UPS, FedEx, and DHL — a failure costs you a question to the buyer, not a returned box.

UPSFedExDHLUSPS all four
Delivery point, not map pin The string is what is checked.
Failures name the defect Missing unit, ZIP mismatch.
Fixed pre-purchase The cheap place to be wrong.

Residential or commercial, badged before you pay

The classification that moves the price on UPS and FedEx shows on the address as a badge at quote time, so the surcharge is inside the number you compare.

VisaMastercardAmerican ExpressApple PayGoogle PayBitcoinEthereumTether (USDT)
Classification badge On the address, pre-payment.
All-in quote Surcharge priced in, not appended.
One prepaid wallet Card, ACH, or crypto.

What validation actually checks: the delivery-point database

Address validation is widely misunderstood as a map lookup, and the misunderstanding is why the failures feel so wrong. The validator never asks whether a building exists. It asks whether the exact string you submitted resolves to a delivery point — an entry in the carrier's database of places mail is actually delivered. A delivery point is more specific than a building: in a multi-unit property, every apartment is its own entry, which is why a tower with four hundred units and a correct street address can still fail on a missing unit line. The database is compiled from carrier operations, not from satellite imagery, so it encodes how mail is delivered rather than what is physically there.

That distinction explains every failure class on this page. A house can stand, receive packages daily, and still fail validation because the string arrived misspelled, incomplete, or in a locally popular format the database does not prefer. Equally, validation passing is not a guarantee of delivery — it is a guarantee that the address is a known deliverable point, which is the strongest pre-purchase signal available. GoatLabels runs this check at quote time, on every address, before any money leaves the wallet, because the entire value of the check is its timing: a failure caught at quote costs a message to the buyer, while the same failure caught by the carrier costs postage, weeks, and often the sale.

The failure taxonomy: missing secondary, unknown street, ZIP mismatch, vanity names

Almost every validation failure a small seller will ever see falls into one of five classes, and each class points at a different root cause with a different fix. The triage below is the whole discipline: read which failure you have, ask the buyer the one question that resolves it, and only override where the table says an override is defensible.

Failure What actually went wrong The one question to ask the buyer Override safe?
Missing secondary (unit, apt, suite) Multi-unit building — the street address alone is not a delivery point; every unit is its own database entry. Which apartment or unit number should be on the label? No. The parcel may reach the lobby and stop there, or come straight back.
Unknown street or number Typo, transposed digits, or a street the database has not learned yet (new construction). Can you copy the address exactly as your other deliveries print it? Only for confirmed new construction — never for an unconfirmed typo.
ZIP does not match the city or street Buyer typed the town they say they live in, not the town the ZIP belongs to — or one digit is wrong. Is the ZIP code exactly right? Which does your mail actually use? No. A wrong ZIP routes the parcel to the wrong sort facility first.
Vanity or preferred city name Many places accept several city names for one ZIP; the database prefers one. The address is fine, the label wording differs. Nothing — accept the validator's suggested standard form. Take the suggestion instead. The corrected form is the same place.
Destination is a PO Box or military address Not a defect at all — an eligibility rule. Some carriers cannot deliver there, so the quote list shrinks. Nothing — pick a service that can actually deliver to it. Not applicable — this is carrier selection, not address correction.

Two rows deserve a second look. The vanity-name row is the one failure where nobody is wrong: many ZIP codes accept several city names, and the validator is simply nudging you toward the standard form — take the suggestion and move on. The last row is not a defect at all but an eligibility rule: some destinations decide the carrier before price does, and which carriers can reach a PO Box or an APO address is its own subject. Everything else in the table is a genuine defect in the string, and the fix is a question, not a workaround.

New construction and rural routes: when the database is the thing that's wrong

The database lags reality in a few well-known places. A new subdivision exists as concrete and mailboxes before it exists as delivery points; the carriers add streets on their own operational schedule, and until they do, a perfectly real address fails as unknown. Rural addresses carry a different version of the problem: many were renumbered when counties adopted emergency-services addressing, so the address a long-time resident recites from memory and the address the database holds can be two different strings for one farmhouse. In both cases the buyer is the authority the database lacks. Ask how their mail and parcels actually arrive — the format printed on something recently delivered — and use that string.

This is also the honest boundary of validation as a tool. It is a database check, and a database can be behind. The discipline is to treat a failure as a prompt for evidence rather than as either an immovable wall or an ignorable nag: when the buyer supplies evidence the database lacks, override with confidence; when they cannot, the validator was probably right. Sellers importing a spreadsheet of addresses get the same check applied to every row of a CSV before any label in the file is bought, which turns this triage from a per-order chore into a batch report.

The residential/commercial flag, and what it changes about the price

Validation returns one more fact that has nothing to do with deliverability: whether the delivery point is residential or commercial. On UPS and FedEx that classification moves the price, and the destination-fee mechanics behind it are covered in our guide to shipping surcharges. What matters on this page is where the fact surfaces. A seller who quotes against a rate card discovers the classification when the bill does; GoatLabels resolves it during validation and shows a residential or commercial badge on the address before payment, so the four-carrier comparison is between all-in numbers that already know what kind of door they are pricing. A home that looks commercial because a business is registered there, or a storefront the database still lists as residential, is visible as a badge you can question — before it is a line item you cannot.

When overriding a failed validation is safe, and when it isn't

The override exists because the database is not perfect, and it is dangerous because the database is mostly right. The safe overrides share one property: independent evidence. A buyer confirming a new-construction address against mail they already receive, a rural recipient dictating the exact renumbered format — in those cases you know something the database does not, and shipping on the buyer's string is the correct call. The unsafe overrides share the opposite property: impatience. Overriding a missing unit number because the buyer is slow to reply, or a ZIP mismatch because the label needs to go out tonight, converts a free question into a gamble with postage on the table.

The stakes of that gamble are not abstract. An undeliverable parcel is refused or returned on the carrier's terms, and what happens to a returned parcel — including who pays for the journey home — is a separate process with its own bill. Validation at quote time exists precisely so that page stays theoretical: the defect classes above are all visible before purchase, every one of them is fixable for free while the label is still a draft, and the only failures worth carrying past the check are the ones where you hold better evidence than the database.

Where the check runs

Validated at quote. Fixed before payment.

The triage above is built into the flow. An address arrives however the order arrived — synced store, pasted DM, CSV row — and is checked against delivery-point data while the four carrier quotes are being built. A failure names its defect class, you resolve it with the buyer while the label is still a draft, and money only moves once the destination is a known delivery point with its classification badge attached.

1
The address as it arrived
Store sync, pasted message, or CSV row
order_2214

Buyer pasted their address from a saved note — building number present, apartment line missing.

Synced order
Checkout field, typed once by the buyer
CSV row
One line of a batch file, validated like the rest
Validation result
Street
matched
Unit
missing — multi-unit building
ZIP
matches city
Classification
residential
Ask the buyer the one question the failure names

A failed check stops nothing except payment. The draft label waits while you confirm the fix, and nothing is charged until the address resolves.

2 Draft, checked

Every draft is validated before it can be bought.

Billy AI
  • The destination is resolved against delivery-point data, not a map pin
  • Failures name the defect class: missing secondary, unknown street, ZIP mismatch
  • The residential or commercial badge is attached to the address pre-payment
  • Overrides are explicit — a deliberate decision, never a silent default
Validated. Classified. Ready to buy.
3
Quote on a known delivery point
Four carriers, classification priced in
All-in price locked at quote
Residential surcharge inside the number, not after it
$12.47
USPS
Label bought from the wallet
On an address the carrier recognises
$12.47

The corrected address costs nothing. The uncorrected one costs return postage, weeks of transit, and often the sale — which is the entire argument for checking before money moves.

Every channel types an address differently

One delivery-point check, whatever typed the address.

Shopify, Etsy, WooCommerce, and TikTok Shop sync into the To Ship queue, and every synced destination goes through the same delivery-point check as one you typed yourself. A checkout form that accepted a missing apartment line has not validated anything — it has handed you an unvalidated address, tidily formatted.

Via AItiles: paste a DM or a screenshot and Billy lifts the address out of it — the check runs on that string exactly as it does on a synced one.

Shopify logo Shopify
Etsy logo Etsy
WooCommerce logo WooCommerce
TikTok Shop logo TikTok Shop
Instagram logo Instagram AI Facebook logo Facebook AI
Amazon logo Amazon
eBay logo eBay
Show 15 more Show less
Squarespace logo Squarespace
Wix logo Wix
Walmart logo Walmart
Shopify Plus logo Shopify Plus Soon
Square logo Square
BigCommerce logo BigCommerce
Magento logo Magento
Zapier logo Zapier Soon
NetSuite logo NetSuite Soon
Ecwid logo Ecwid Soon
Temu logo Temu
Shein logo Shein Soon
ChannelAdvisor logo ChannelAdvisor Soon
SkuVault logo SkuVault Soon
Zoho Inventory logo Zoho Inventory Soon
What quote-time validation is attached to

A checked address is the start,
not the feature.

Validation earns its place because of what happens next: four honest quotes on a destination the carrier recognises, paid from a balance that only moves when you buy.

One prepaid wallet,
charged only on purchase

Card, Apple Pay, Google Pay, ACH, and crypto top up one balance. A failed validation charges nothing — the draft waits while you confirm the fix with the buyer, and the wallet moves only when a validated label is actually bought.

Wallet balance
$1,247.36 USD
AI

Billy reads the address
out of the mess

Paste the DM, drop the screenshot, or speak the address — Billy drafts the label and the destination goes through the same delivery-point check as a typed one. The apartment line a buyer buried in a follow-up message is exactly the defect the validator is there to catch.

Billy LIVE
Where's the package to Maya?
It's in transit via UPS. Expected Friday, Aug 7.
UPS
1Z8923A6B05G4123456
In transit
Austin, TX → Dallas, TX
Ask Billy anything...

Classification priced in,
not appended later

The residential or commercial badge resolved at validation feeds the quote, so the number you compare across carriers already includes the destination fees that classification triggers. What you see at quote is what leaves the wallet.

Shipment summary
UPS Ground $12.49
Insurance $0.75
Fuel surcharge $0.32
Total $13.56

Four carriers quoted
on the same checked address

USPS, UPS, FedEx, and DHL are priced against the identical validated destination, and eligibility rules are applied first — a destination only one carrier can reach shows you that carrier, not a quote that will bounce.

Compare rates
UPS UPS $12.48
FedEx FedEx $13.22
DHL DHL $14.10
USPS USPS $11.79
Duties & taxes paid

The same check,
over the API

Address validation runs on API-created shipments exactly as in the dashboard, with unlimited calls on every plan and signed webhooks for the lifecycle — so a checkout integration can catch the missing unit while the buyer is still on the page.

POST /v1/shipments
{
"to": { "name": "Maya" },
"from": { "name": "Alex" },
"service": "ups_ground",
"label_format": "pdf"
}
Webhook delivered
GoatLabels mobile shipments queue showing validated destinations
Billy flagging a missing apartment line on a pasted address on mobile

Address validated

CL-1044 · unit line added

Triage from wherever you packed it

The failure, named on the screen in your hand.

A validation failure is only cheap if you can act on it in the minute it appears. The queue, the defect class, the one question worth sending the buyer, and the re-checked address all fit on a phone — no laptop leg, no waiting until you are back at a desk.

Paste or snap the buyer's message — Billy pulls the address out and runs the delivery-point check on it.
A failure names its class: missing secondary, unknown street, ZIP mismatch, vanity city name.
Send the one question that resolves it and re-check the corrected string on the same screen.
The residential or commercial badge sits on the address before you pay, so the price already knows the door.
Nothing is charged while a draft waits — the wallet moves only when a validated label is bought.
Billy is included, not a paid tier

Read the address out loud. Let the check disagree.

Speaking an address is how a lot of them arrive anyway — off a phone call, off a note, off a buyer standing in front of you. Hold the mic, say it, and Billy writes it into the shipment, resolves it against delivery-point data, and tells you which part failed before anything is bought. It remembers repeat buyers, so an address you corrected once stays corrected. Included on every plan. This is the real product, not a render.

goatlabels.io/dashboard/shipments — Billy
Billy reading back a validated destination and its classification over the purchased labels list

Listening

"Did the Brooklyn address ever get its unit number?"

Validated, out for delivery

CL-1044 · Brooklyn, NY · residential

Speaks plain English · names the defect class out loud · says the residential or commercial classification · included on every plan, never a pricier tier.

Quoted on a checked address

A validated destination, priced three ways.

A carrier comparison only means something once every column is pricing the same known delivery point with the same classification attached. These three quote a residential address that passed the check, each as one all-in number, and the column you pick is exactly what leaves your prepaid balance. Figures are illustrative.

Denver, CO → Austin, TX (residential) 1.4 lb 10×7×4 in
Cheapest on this checked address
USPS

USPS

Ground Advantage

2–5 days

$7.40

$1.20 of Premium insurance included

all-in · classification already applied

UPS

UPS

Ground

3–4 days

$10.80

$1.20 of Premium insurance included

all-in · classification already applied

FedEx

FedEx

Home Delivery

2–4 days

$11.40

$1.20 of Premium insurance included

all-in · classification already applied

Validated before the wallet moves Void → credit straight back to your wallet Multi-currency display
Public API v1

Catch the missing unit while the buyer is still on the page.

The same delivery-point check runs on API-created shipments, so a checkout integration can surface a defect class at the one moment the buyer can still fix it themselves. REST, JSON, one Bearer header, signed webhooks instead of polling, real idempotency keys, and unlimited calls on every plan.

Validation runs on API shipments exactly as it does in the dashboard
The residential or commercial classification comes back with the validated address
Signed webhooks instead of polling for everything that happens after purchase
Real idempotency keys — a retried order never buys two labels to one bad address
Read the API docs Get a free API key $0 on every plan
curl https://api.goatlabels.io/api/v1/shipments
POST /api/v1/shipments
Authorization: Bearer sk_live_…
Idempotency-Key: ord_8421

{
  "to": { "name": "Joyce", "city": "Berlin", "country": "DE" },
  "parcel": { "weight": 2.6, "weight_unit": "lb" },
  "service": "fedex_intl_priority"
}
Pricing for a check that has to run every time

Two plans. Validation on both, never metered.

A check billed per lookup is a check you start skipping on the cheap orders — which are exactly the orders one returned parcel wipes out. Address validation runs on every shipment on every plan here, Free included, and it is not a credit pack you can run down. Free covers 50 shipments a month; Pro is a flat monthly plan with unlimited shipments and cheaper label pricing.

Pro

Most popular
$40 / month
Unlimited shipments — no monthly cap
Cheaper label pricing that scales down as your volume grows
Billy AI on Telegram — fix an address without opening the dashboard
API access still free and unlimited

Volume pricing

illustrative
less volume more volume

more volume → lower per-label rates

Free

$0 / forever

Fund a wallet, check every address, and pay only for the labels you actually buy.

Address validation on every shipment — never metered, never a credit pack
The residential or commercial badge on the destination before you pay
50 shipments a month, no monthly minimum to print
USPS, UPS, FedEx, and DHL quoted on the same checked destination
REST API with unlimited calls; fund by card, Apple Pay, Google Pay, ACH, or crypto

Billy is not an upsell

The assistant that lifts an address out of a DM, a screenshot, or a spoken sentence and puts it through the same delivery-point check runs unlimited in the web app on Free. Pro adds Billy on Telegram.

Web — every plan Telegram — Pro

API free on every plan

GET /api/v1/shipments

200 OK · plan: free

Unlimited calls on Free — still unlimited on Pro.

Bring what you pay today

On Pro we will work with you to beat the label rates you are already getting from

ShippoPirate ShipShipStation
No contracts No per-lookup validation fee Start in seconds
USPS UPS FedEx DHL

A failed check charges nothing at all — the draft simply waits while you ask the buyer. An undeliverable parcel charges the outbound label first and the journey home afterwards, which is why the free check is the one that pays for itself. Full pricing details

Where bad addresses cluster

The same five defect classes, over and over.

Same check, same wallet, same one-tap fix, whether that is four parcels a week or four hundred. These are the four shapes of seller whose order book produces the most failed validations — and the most returned boxes when the check gets skipped.

Sellers shipping into apartment buildings

Cities, towers, missing unit lines

Missing secondary

Buyers type their building and forget their apartment, and a street address alone is not a delivery point. It is the most common failure an ecommerce seller sees, and one message fixes it — as long as the check ran before the label was bought.

5 defect classes checked pre-payment classification badged
goatlabels.io/dashboard/shipments
GoatLabels shipments queue showing validated destinations with classification badges

Makers shipping to rural and renumbered addresses

Where the database is the thing that is wrong

Emergency-services renumbering left plenty of homes with two truthful addresses: the one the resident recites and the one the carrier holds. Ask how their parcels actually arrive, use that string, and override only on the evidence they hand you.

Override on evidence, never on impatience

A buyer-confirmed new build is a reason; a slow reply is not

Sellers taking addresses in DMs

Typed by a buyer, in a hurry, on a phone

sending it now — 123 Main St, Brooklyn NY 11201
Unit line missing · asked before buying

Anyone importing a spreadsheet of orders

Every row checked before any label is bought

CSV

validated row by row, so the triage is a batch report instead of a per-order chore

Address validation failures, answered

Why does a real, deliverable address fail validation?
Because validation does not check whether a building exists — it checks whether the exact string you typed matches a delivery point in the carrier's database. A real address fails when the string is incomplete (a missing unit number), when the database has not caught up (new construction), or when the human-friendly version of the address differs from the postal version (a vanity city name, or a PO Box that locals write as a street). The building is fine; the string is the problem.
What is a missing secondary number?
The secondary is the line after the street address: apartment, suite, unit, floor. In a multi-unit building the street address alone is not a delivery point — every unit is its own entry in the database, so a validator that sees the building but no unit flags the address as incomplete. It is the single most common validation failure for e-commerce sellers, because buyers routinely type their building and forget their apartment.
My buyer's new-construction address won't validate — what now?
First confirm the address with the buyer, ideally with the exact format their other mail arrives under. New delivery points enter the carriers' databases on the carriers' schedule, not the builder's, so a genuinely new street can lag behind reality. If the buyer confirms mail is already delivered there, this is the one failure class where overriding the validator is reasonable — you have independent evidence the database lacks.
What does the residential vs commercial classification change?
The price, on some carriers. UPS and FedEx price residential delivery differently from commercial delivery, so the classification of the destination feeds directly into the quote. GoatLabels runs the classification at quote time and shows a residential or commercial badge on the address before you pay, so the surcharge is inside the number you compare rather than a correction that arrives later. The trigger mechanics live in our guide to shipping surcharges.
Should I ever override a failed validation?
Only when you know something the database does not — a buyer-confirmed new build, a rural address the buyer swears by in that exact format. Never override to save a round trip with the buyer, because the failure is usually pointing at a real defect: a missing unit, a wrong ZIP, a misspelled street. An override on a genuinely bad address turns a free fix into a returned parcel with a bill attached.
Real sellers, real words

Sellers who stopped shipping to an address they hoped was right.

A video took off and I had 80 TikTok Shop orders by morning. I printed every label from my phone on the bus to the post office.
E

Early customer · TikTok

TikTok Shop seller

TikTok Shop
I run my Etsy shop from the kitchen. The AI reads the order, picks the carrier, the label prints. That's the whole workflow now.
E

Early customer · Etsy

Etsy maker

Etsy
The API is what every shipping API pretends to be. Idempotency that actually works.
S

Sasha R.

Staff engineer, marketplace

API user
No monthly minimum to print. No fee to check.

Catch the bad address
while it is still free to fix.

Every destination validated and classified at quote time, four carriers priced on the checked address, and nothing charged until you buy the label.

Sign up in seconds. No card required. Validation runs on every plan.