Address Validation API for Shipping and Logistics
What to check on every order before the label is bought, what UPS and FedEx charge when they have to fix an address, and what to do with each result.
An address validation API for shipping and logistics checks each order's address before you buy the label. It tells you whether the address is a confirmed delivery point, whether a unit number is missing, what kind of record it is (street, high-rise, PO box) and whether it is a private mailbox. A check costs a fraction of a cent. A carrier fix costs more: UPS lists $25.25 and FedEx $25.50 per address correction in 2026.
What to check before you buy a label
The field names in the middle column are sthan.io's. The code definitions are as published in Smarty's US Street API field reference. Other verification APIs may name or code these results differently, so map each vendor's response to your own actions.
| Check | Field | What it tells the shipping step |
|---|---|---|
| Is it a delivery point? | dpvConfirmation, deliverableStatus | The DPV (delivery point validation) code. Y: the whole address is confirmed. D: the building is confirmed but the apartment or suite is missing. S: the building is confirmed but the unit given was not recognized. N: not confirmed. |
| Is the unit there? | unitType, unitNumber, matchCode.unit | Whether the apartment or suite was supplied and matched. A parcel for a building with units and no unit number may not reach the right door. |
| What kind of address? | recordType | S street; H high-rise (a building with apartment or suite units); P PO box; R rural route or highway contract; F firm. Check your carrier's rules for PO boxes before choosing a service. |
| Is it a private mailbox? | cmar | Y means the address belongs to a commercial mail receiving agency (CMRA): a business through which mail may be sent or received, such as the UPS Store or Mailboxes Etc. |
| What did the API change? | matchCode, footnotes | Which fields were corrected (street, ZIP), so you can tell the customer or log it before shipping to an address they did not type. |
What a carrier address correction costs
When a parcel goes out with a wrong or incomplete address, the carrier may fix it and bill you. The UPS guide says that "if any shipment has an incorrect or incomplete address, UPS will make reasonable efforts to secure the correct or complete address" and that "an Address Correction charge will be assessed to the shipper." The published amounts, read from each carrier's own rate documents on October 16, 2026:
| Carrier | Address correction charge | Maximum per shipment | Source |
|---|---|---|---|
| UPS | $25.25 for package shipments | UPS Ground with Freight Pricing: $25.25 per package, up to $175.25 per shipment | 2026 UPS Rate and Service Guide, Daily Rates, updated September 7, 2026 |
| FedEx, 2026 | $25.50 per correction (it was $24 in 2025) | $178.50 with FedEx Express Multiweight Pricing; $76.50 with FedEx Ground Multiweight Pricing | FedEx 2026 changes to surcharges and fees (effective January 5, 2026) |
| FedEx, from January 4, 2027 | $27 per correction | $189 with FedEx Express Multiweight Pricing; $81 with FedEx Ground Multiweight Pricing | FedEx 2027 changes to surcharges and fees (effective January 4, 2027) |
Two details in the carriers' documents matter for your pipeline. First, UPS says "an address validated by UPS may be incorrect or incomplete for purposes of completing delivery and may be corrected by UPS," so a carrier's own check at label time does not rule out the charge. Second, residential delivery is priced separately: UPS lists a Residential Surcharge of $6.50 for UPS Ground Services, and FedEx lists a Residential Delivery Charge of $6.45 per package for FedEx Ground and FedEx Home Delivery in 2026. If you need to know residential or commercial before you rate a shipment, choose a verification API that returns that flag (Smarty's response has a residential delivery indicator; sthan.io's does not).
One correction, counted in address checks
The table divides each carrier charge by the price of one sthan.io verification on the Basic plan ($12 for 10,000 a month, or $0.0012 each). It shows how many orders you could check for the cost of one correction. These are our own calculations from the published prices above.
| Carrier charge | Amount | Address checks at $0.0012 each |
|---|---|---|
| UPS address correction, package | $25.25 | about 21,000 |
| FedEx address correction, 2026 | $25.50 | 21,250 |
| FedEx address correction, from January 4, 2027 | $27 | 22,500 |
| FedEx Ground Multiweight maximum, 2026 | $76.50 | 63,750 |
| UPS Ground with Freight Pricing maximum | $175.25 | about 146,000 |
| FedEx Express Multiweight maximum, 2026 | $178.50 | 148,750 |
Put simply: if checking every order prevents one correction in about 21,000 shipments, the checks have paid for themselves, before counting the delay and the customer's wait. These are the published amounts; check your own carrier contract.
Five real responses, and what a shipping system should do with each
We sent five addresses to the sthan.io verification API on October 16, 2026. The results show the signals from the first table in live responses.
| Input | What came back | Shipping action |
|---|---|---|
| 1355 Market St Suite 900, San Francisco, CA 94103 (a building with suites) | 1355 Market St STE 900, San Francisco, CA 94103-1337. DPV Y, Confirmed, record type H, cmar N | Use the standardized address on the label, if your carrier and service accept it |
| 1355 Market St, San Francisco, CA 94103 (no suite) | 1355 Market St, San Francisco, CA 94103-1326. matchTier Exact, but deliverableStatus Unknown with no DPV code and no record type | Hold the order and ask the customer for the suite number (the row above shows this building has suites) |
| 1355 Markit St Ste 900, San Francisco CA 94102 (typo, wrong ZIP) | 1355 Market St STE 900, San Francisco, CA 94103-1337. matchTier Approximate, confidence 0.85, street and ZIP marked Corrected, DPV Y, Confirmed | Confirmed after two corrections: show the customer the corrected address, or log the change, before you buy the label |
| 2443 Fillmore St # 380, San Francisco, CA 94115 | 2443 Fillmore St, San Francisco, CA 94115-1814. cmar Y, DPV Y, record type S, matchTier Near, unit marked Unmatched | Private mailbox: apply your CMRA policy. The box number did not come back in the standardized address, so keep the customer's "# 380" on the label |
| 98765 University Ave, Sacramento, CA 95825 (a house number we made up) | HTTP 404, not found | No match was found, which does not by itself prove the address is wrong. Hold the order and ask the customer to check it |
Status-to-action table for fulfillment
At checkout you can let the customer continue with an unconfirmed address (see how to validate addresses at signup and checkout). The label step is different: the parcel is about to leave, so the safe default for anything unconfirmed is to hold and ask. A confirmed result is not a delivery promise either. It means the address matched a postal delivery point. Smarty's reference has separate flags for vacant addresses and for addresses listed as "no-stat" (temporarily not receiving deliveries), and sthan.io returns neither. The rows below are starting points; set them to your carrier's rules and your own unit and mailbox policies.
| Result | Before the label |
|---|---|
| DPV Y, nothing corrected | Use the standardized address and ZIP+4, if your carrier, unit and mailbox rules allow it |
| DPV Y, a field corrected | Ship if the correction is small (ZIP+4 added, street suffix); otherwise confirm with the customer first |
| DPV D (unit missing) | Hold; email or text the customer for the unit number |
| DPV S (unit not recognized) | Hold or ship with the unit as typed, depending on order value |
| Status Unknown (a match, but no postal confirmation) | Hold; confirm the address with the customer |
| DPV N, or no match found | Hold; ask the customer to check the address |
| Record type P (PO box) | Route to a service that delivers to PO boxes, or ask for a street address |
| Private mailbox flag Y | Apply your policy; keep the box number from the customer's input |
| Timeout or API error | Retry once, then queue the order for manual review |
Where verification sits in an order pipeline
- Checkout. Autocomplete while the customer types, verify on submit. This catches problems while the customer is still on the page.
- Order import. Orders that arrive from marketplaces, phone orders or spreadsheets never passed your checkout. Verify them as they land in your order system.
- Before the label. Run the status-to-action table on every order that has no stored result, or whose address was edited after checkout.
- After a carrier correction. When an invoice shows an address correction, update the customer's saved address so the next order does not repeat it.
Store the standardized address on the order, the customer's typed address next to it, and the result fields (DPV code, record type, private mailbox flag, match code). That record lets support answer "why did this ship late" without calling the API again.
Where sthan.io fits. sthan.io's US Address Verification API returns the standardized address, ZIP+4, unit, record type, private mailbox flag, DPV code, a deliverability status and a per-field match code, as in the responses above. Its response has no residential, vacant or no-stat flag. 3,000 verifications a month are free (up to 100 a day and 10 a minute) with no credit card; paid plans start at $12 a month for 10,000. For a spreadsheet of orders, the Address Cleaner takes an Excel, .csv or .tsv file of up to 100,000 rows with no account, charges $1.20 per 1,000 rows found in postal records ($1.00 minimum when any row is charged), and the first 100 rows each day are free. sthan.io is not CASS-certified.
Frequently Asked Questions
Sources
All read October 16, 2026:
- 2026 UPS Rate and Service Guide, U.S. 48, Alaska and Hawaii Daily Rates, updated September 7, 2026, Other Charges section (linked from ups.com/us/en/support/shipping-support/shipping-costs-rates/daily-rates).
- FedEx, 2026 changes to FedEx surcharges and fees (fedex.com/content/dam/fedex/us-united-states/services/surcharge_and_fee_changes_2026.pdf).
- FedEx, 2027 changes to FedEx surcharges and fees (fedex.com/content/dam/fedex/us-united-states/services/surcharge_and_fee_changes_2027.pdf) and the FedEx rate changes page, updated September 18, 2026 (fedex.com/en-us/shipping/rate-changes.html).
- Smarty US Street API field reference (smarty.com/docs/apis/us-street-api/reference).
- sthan.io US Address Verification product page (sthan.io/products/address-verification-usa), API docs (sthan.io/docs) and Address Cleaner (sthan.io/address-cleaner).
- Five live calls to the sthan.io US Address Verification API on October 16, 2026.
Carrier fees change; check the carrier's current guide before you rely on a number.
Check addresses before the label
3,000 free verifications a month, no credit card. Standardized address, ZIP+4, unit, record type and private mailbox flag with each successful match.