GoatLabelsGoatLabels
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 and FedEx, or DHL on international lanes, so a failure costs you a question to the buyer, not a returned box.

UPSFedExDHLUSPSDHL: international
Delivery point, not map pinThe string is what is checked.
Failures name the defectMissing unit, ZIP mismatch.
Fixed pre-purchaseThe 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 badgeOn the address, pre-payment.
All-in quoteSurcharge priced in, not appended.
One prepaid walletCard, ACH, or crypto.

Updated

What does address validation actually check?

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.

Why does an address fail validation?

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.

FailureWhat actually went wrongThe one question to ask the buyerOverride 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 numberTypo, 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 streetBuyer 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 nameMany 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 addressNot 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.

Why does a new-construction or rural address fail?

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.

How does the residential or commercial flag change 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 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 is overriding a failed validation safe?

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 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.

2BillyDraft, 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
Each carrier, 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.

Thirteen store connectors, Shopify, Amazon, eBay, Etsy, TikTok Shop and more, 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.

Shopify logoShopify
Etsy logoEtsy
WooCommerce logoWooCommerce
TikTok Shop logoTikTok Shop
Amazon logoAmazon
eBay logoeBay
Squarespace logoSquarespace
Wix logoWix
Walmart logoWalmart
Shopify Plus logoShopify PlusSoon
Square logoSquare
BigCommerce logoBigCommerce
Magento logoMagento
Zapier logoZapierSoon
NetSuite logoNetSuiteSoon
Ecwid logoEcwidSoon
Temu logoTemu
Shein logoSheinSoon
ChannelAdvisor logoChannelAdvisorSoon
SkuVault logoSkuVaultSoon
Zoho Inventory logoZoho InventorySoon
Patreon logoPatreon
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.36USD
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.

BillyBillyLIVE
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

Every carrier quoted
on the same checked address

USPS, UPS and FedEx are priced against the identical validated domestic destination, DHL joins on international lanes, 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
UPSUPS$12.48
FedExFedEx$13.22
DHLDHL$14.10
USPSUSPS$11.79
Duties inside the quote where DDP applies

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 lb10×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 movesAccepted void → credit back to your walletMulti-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.

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 both plans: Free includes 100 validations a month (repeat lookups served from cache do not count), and Pro makes validation unlimited. Free covers 50 shipments a month; Pro is a flat monthly plan with unlimited shipments.

Pro

Most popular
$40/ month
Unlimited shipments — no monthly cap
Unlimited address validation
Billy AI on Telegram Telegram logo — fix an address without opening the dashboard
API access still free and unlimited

Rate by plan

illustrative
FreePro

pay for labels, not for seats

Free

$0 / forever

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

Address validation before you pay, 100 a month on Free (cached repeat lookups do not count)
The residential or commercial badge on the destination before you pay
50 shipments a month, no monthly fee
USPS, UPS and FedEx quoted on the same checked domestic destination, DHL on international lanes
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 planTelegram logoTelegram, 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

Put a real parcel through and compare the side-by-side rate against what that label costs you on

ShippoPirate ShipShipStation
No contractsNo per-lookup validation feeStart in seconds
USPSUPSFedExDHL

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

TikTok logo 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 a very 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

Etsy logo 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

Instagram logo

Sellers taking addresses in DMs

Messenger logo 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

Shopify logoWooCommerce logo 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 a very 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 logo 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 logo Etsy
The API is what every shipping API pretends to be. Idempotency that actually works.
S

Sasha R.

Staff engineer, marketplace

API user
Free up to 50 shipments a month. No fee to check.

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

Every destination validated and classified at quote time, every carrier on the lane 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.

Updated