USPS Web Tools Shut Down on January 25, 2026: What Broke and the Fastest Way to the v3 API

USPS retired Web Tools on January 25, 2026. The XML API that carried USPS integrations for two decades is gone, and every plugin, module, and hand-rolled script pointed at secure.shippingapis.com broke with it.

USPS says so on its own page, still, as of August 2026: the platform “was retired on January 25, 2026,” service disruptions “are underway,” and availability “may be degraded or interrupted at any time.”

What happened

Web Tools was a free XML over HTTP API from the early 2000s. You registered a USERID, built an XML body, and POSTed it to https://secure.shippingapis.com/ShippingAPI.dll. Address validation, rates, tracking, labels: all of it, one endpoint, no authentication beyond a string in the request.

USPS announced the deprecation in Q3 2024 and ran the v3 REST API in parallel through 2025, which gave integrators roughly a year. On January 25, 2026, the legacy endpoints went dark with no grace period.

Any code that still references secure.shippingapis.com, or builds an XML body around a USERID parameter, is dead code.

One thing has changed since the shutdown, and it catches people who did migrate: addresses are no longer free. More on that below.

What broke

The shutdown hit a wide surface area. Here are the systems with confirmed breakage:

WooCommerce USPS Shipping Method plugin. The official and third-party WooCommerce USPS plugins (including the popular one from WooCommerce.com) used Web Tools for live rate calculation at checkout. Sites running unpatched versions display no USPS shipping options, or throw fatal errors during checkout. See our WooCommerce USPS migration guide for the exact fix.

Magento built-in Magento_Usps module. Adobe Commerce and Magento Open Source ship with a native USPS module. It hard-coded Web Tools endpoints. Adobe tracked this as AC-15210. Any Magento store using the built-in USPS carrier is affected unless the patch has been applied. See our Magento AC-15210 fix guide.

Stamps.com legacy integrations. Third-party apps that integrated with Stamps.com’s old API layer (which itself proxied Web Tools in some configurations) may have inherited breakage. Direct Stamps.com accounts are unaffected; their internal migration was handled on their end.

ShipStation legacy connections. ShipStation’s USPS connection type has multiple modes. The “direct USPS” connection mode that used Web Tools credentials was deprecated. Stores using ShipStation’s carrier-branded labels through their platform are unaffected; only direct USPS connections through the legacy mode broke.

Custom integrations hitting secure.shippingapis.com. Any in-house code that directly calls the old endpoint is completely broken. This includes:

• PHP scripts using file_get_contents() or cURL to call ShippingAPI.dll
• Python scripts using requests or urllib to POST XML to the legacy URL
• Node.js integrations using axios, fetch, or got against the old endpoint
• Ruby, Java, .NET, and any other language making HTTP calls to secure.shippingapis.com

osCommerce and OpenCart USPS shipping modules. Both platforms shipped USPS modules that called Web Tools directly. These modules are not actively maintained for most legacy versions. Stores on osCommerce 2.x or OpenCart 2.x are almost certainly broken without manual patching.

Any rate-shopping or address-cleansing middleware. Internal tools, ETL pipelines, address hygiene workflows, and fulfillment middleware that hit the old API for address standardization or rate lookups are all affected.

The replacement: USPS v3 REST API

USPS replaced Web Tools with a proper REST API. Six things changed at the architecture level:

Authentication: Web Tools used a USERID query parameter, a plaintext identifier tied to your registration. The v3 API uses OAuth 2.0 client_credentials flow. You exchange your client_id and client_secret for a Bearer token, and that token goes in the Authorization header of every request. Tokens expire and must be refreshed.

Data format: Web Tools was XML in, XML out. The v3 API is JSON throughout. No more constructing XML request bodies or parsing XML responses. Standard JSON serialization/deserialization.

HTTP methods: Web Tools used POST for almost everything, with the operation name encoded in XML or a query parameter. The v3 API is RESTful: GET for lookups, POST for creates, DELETE for cancellations. Operations map to HTTP verbs and URL paths.

Rate limits: Web Tools had no meaningful rate limit for most operations. The v3 API enforces 60 requests per hour by default for address validation. This is the biggest operational change for high-volume users. You can request an increase from USPS at emailus.usps.com. For tracking and rates, limits vary by endpoint. See our rate limit guide for the full breakdown.

Registration: A developer account at developers.usps.com is still free and still issues OAuth credentials. What those credentials reach has narrowed twice. Label printing needs a separate Payment Authorization flow through the Business Customer Gateway. Address validation now needs a license of its own, and USPS is blunt about the consequence on its developer portal: “Customers who did not complete onboarding no longer have access to the Addresses API.” Migrating your code was necessary and is no longer sufficient.

Cost: No longer free. Effective August 1, 2026, USPS moved the Addresses API onto a consumption-tier pricing model. It runs $10 flat for up to 2,000 lookups a month, then $4.50, $4.25, and $4.00 per 1,000 as volume climbs, billed at a single tier on your total monthly consumption. Access “requires a signed license agreement,” and charges are debited from an Enterprise Payment Account. The figures and that condition come from the USPS Addresses API Tech Sheet, updated 2026-08-13. Tracking, rates, and service standards remain outside that fee curve. Full breakdown in the pricing guide.

Endpoint mapping

Here are the eight most critical Web Tools endpoints and their v3 equivalents:

A minimal address validation call in the old API looked like this:

POST https://secure.shippingapis.com/ShippingAPI.dll?API=Verify&XML=
<AddressValidateRequest USERID="YOURUID123">
<Address ID="0">
  <Address1></Address1>
  <Address2>1600 Pennsylvania Ave NW</Address2>
  <City>Washington</City>
  <State>DC</State>
  <Zip5>20500</Zip5>
  <Zip4></Zip4>
</Address>
</AddressValidateRequest>

The same call in v3:

curl "https://apis.usps.com/addresses/v3/address?streetAddress=1600+Pennsylvania+Ave+NW&city=Washington&state=DC&ZIPCode=20500" \
-H "Authorization: Bearer YOUR_OAUTH_TOKEN"

Or through RevAddress, which handles the OAuth layer for you:

curl "https://api.revaddress.com/api/address/validate?streetAddress=1600+Pennsylvania+Ave+NW&city=Washington&state=DC&ZIPCode=20500" \
-H "X-API-Key: rv_live_your_key_here"

The 9 migration gotchas

These catch developers off guard. Knowing them upfront saves hours.

1. Address1 and Address2 are swapped. Web Tools had a notoriously confusing field naming convention: Address1 was for the apartment or suite number, and Address2 was for the street address, the reverse of every other address API. The v3 API corrects this: streetAddress is the primary street line, and secondaryAddress is the unit/suite/apt. If you copy field mappings from old code, your addresses will silently fail or come back incorrect.

2. The 60 req/hr rate limit is real, and it is shared. Web Tools was effectively unlimited. The v3 API allows 60 requests an hour per application, and address validation, tracking, pricing, and labels all draw on the same window. Token fetches count too. A modest store hits this during peak hours. Ask for an increase at emailus.usps.com with your CRID, app name, and a specific monthly volume; reported grants run from roughly 300 an hour to 5,000-plus, answered in 1–5 business days with no published criteria. Until then, cache aggressively and queue. Architecture patterns that survive the default: the rate limit guide.

3. International country codes changed format. Web Tools accepted country names as strings ("Canada", "United Kingdom"). The v3 international prices API requires ISO 3166-1 alpha-2 country codes (CA, GB). Any international shipping code using country name strings breaks silently: a 400 or an empty response, never a helpful error message.

4. Label printing needs a second token, in a second header. Rates and addresses take the standard OAuth Bearer token from developers.usps.com. Labels additionally require a Payment Authorization token, built on enrollment credentials (CRID, MID, EPS account) from the Business Customer Gateway. Both must be present on a label call, and the second one is a header, not a body field: X-Payment-Authorization-Token. The USPS spec marks it required on label creation, reprint, and cancellation. Put it in the JSON body and the header is simply missing, which USPS reports as an authorization failure and reads like a credential problem when your credentials are fine.

5. COP claims linking is manual, and COP is not what you think. COP is the Customer Onboarding Portal at cop.usps.com, a third USPS system separate from both the Developer Portal and BCG. It is where your CRID, MIDs, and EPA get pushed into the token your app receives. Nothing links automatically, there is no API for it, and claims are baked into a token at issue, so a refresh changes nothing until you request a new token. This gates labels and payments; tracking and rates are unaffected.

6. There is no batch rate API. Web Tools’ RateV4 accepted multiple packages in one XML request. The v3 POST /prices/v3/total-rates/search is one rate per call, one mail class per call. Rating an order manifest now means parallelizing individual calls against a 60-per-hour budget, which is the real constraint rather than the loop. Batch address validation is a different story: RevAddress exposes POST /api/batch/validate on Growth and above, running against your own USPS license. Rates stay one call at a time everywhere.

7. Tracking number is now a URL path parameter, not a request body field. In Web Tools, the tracking number went inside the XML body. In v3, it goes in the URL path: GET /tracking/v3/tracking/9400111899223406923658. Any code that constructs a tracking request by inserting a number into an XML template needs to be rewritten to build a URL instead.

8. Dates are ISO 8601. Web Tools accepted various legacy formats. The v3 API is ISO 8601 throughout (2026-03-10T14:30:00Z), in shipping requests, service standard queries, and responses. Straightforward, and it breaks any code emitting MM/DD/YYYY.

9. Finishing the code migration is no longer enough. This one post-dates the shutdown by six months and blindsides teams who did everything right in January. Since August 1, 2026 the Addresses API requires a signed license agreement, and USPS states that “customers who did not complete onboarding no longer have access to the Addresses API.” A v3 integration that ran clean all spring can return 401 today with nothing wrong in the code. The license is requested through the Business Portal at cop.usps.com under My Account → API Licenses → Add an Addresses API License, signed by DocuSign, and countersigned by USPS on no published schedule. Budget weeks. Full enrollment walkthrough.

Migration paths by platform

WooCommerce. The fastest path is installing an updated USPS plugin that already calls the v3 API, or routing the store through RevAddress against your own USPS credentials. Full walkthrough: WooCommerce USPS migration guide.

Magento / Adobe Commerce. Adobe released a patch for AC-15210. Apply the official patch if you’re on a supported version. For older Magento versions without an official patch, the RevAddress Magento module is a drop-in replacement for the transport layer; the USPS rates and labels it fetches still run on your license. Full walkthrough: Magento AC-15210 fix guide.

Custom PHP. Two choices. Rewrite against v3 directly, handling OAuth, token refresh, and the field mapping changes above. Or composer require revaddress/usps-v3-php and replace the XML construction with method calls. Client docs at /sdks.

Python. pip install usps-v3. It wraps the OAuth flow, handles token refresh, normalizes field names, and covers addresses, tracking, prices, and labels. It is the drop-in replacement for the retired usps-api package, which is built on Web Tools XML and cannot be made to work. Source and docs: PyPI.

pip install usps-v3

from usps_v3 import USPSClient

client = USPSClient(
  client_id="your_client_id",
  client_secret="your_client_secret"
)

result = client.addresses.validate(
  street_address="1600 Pennsylvania Ave NW",
  city="Washington",
  state="DC",
  zip_code="20500"
)

print(result.address.street_address)
# 1600 PENNSYLVANIA AVE NW

Node.js. npm install usps-v3, the same package name as the Python client. Same architecture too: OAuth handled internally, field-name normalization, full TypeScript types. Documentation: /sdks.

npm install usps-v3

RevAddress API (any language). One API key instead of the OAuth lifecycle, no XML, flat monthly pricing for the infrastructure. The USPS data stays on your side of the line: bring your own credentials and RevAddress runs the token machinery against them, so DPV, rates, tracking, and labels bill on your license while the USPS relationship stays yours. See pricing or read the docs.

Timeline of the shutdown

Useful when you are explaining this to a client or a manager.

• Q3 2024 — USPS announces the Web Tools deprecation and publishes migration documentation.
• 2025 — The v3 REST API runs in production alongside Web Tools. USPS encourages parallel migration.
• January 25, 2026 — Web Tools retired. No grace period, no extension. USPS still describes the platform as retired with disruptions underway.
• March 2026 — Third-party intermediaries finish removing their own legacy connections. Any platform still advertising a “direct USPS Web Tools” connection is wrapping infrastructure that no longer answers.
• August 1, 2026 — The Addresses API moves to consumption pricing behind a signed license. Migrating in January was not the last step.

If your integration broke on or near January 25, 2026, the shutdown is the cause. If it broke in August, the license is.

The authorization flow, concretely

The biggest conceptual change is OAuth. Here is the exact token acquisition flow for the v3 API:

curl -X POST "https://apis.usps.com/oauth2/v3/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

{
"access_token": "eyJhbGciOiJSUzI1NiJ9...",
"token_type": "Bearer",
"issued_at": "1741612800000",
"expires_in": "28800",
"status": "approved",
"scope": "addresses tracking prices"
}

curl "https://apis.usps.com/addresses/v3/address?streetAddress=1600+Pennsylvania+Ave+NW&city=Washington&state=DC&ZIPCode=20500" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

Tokens last eight hours (expires_in is 28800 seconds), and USPS can invalidate one early, so detect 401 and re-authenticate rather than trusting the countdown. Cache the token: a token request costs a request against the same 60-per-hour budget as an address lookup, so re-authenticating per call halves your usable throughput. Every error you can hit here, with the fix, is in the OAuth troubleshooting guide.

Verifying your integration is broken

If you’re unsure whether your integration is using Web Tools, search your codebase for these strings:

# In your codebase or server logs, look for:
grep -r "shippingapis.com" .
grep -r "ShippingAPI.dll" .
grep -r "USERID" .
grep -r "AddressValidate" .
grep -r "TrackV2" .
grep -r "RateV4" .

Any match is a live dependency on Web Tools. Those calls are now failing.

What to do right now

1. Find every Web Tools dependency with the search patterns above.
2. Start the Addresses API license immediately, in parallel with everything else. It is the only step with a queue you do not control, and code changes are worthless without it. Fund the Enterprise Payment Account first, because ACH verification runs 2–3 business days and sits on the critical path.
3. Choose a migration path: direct v3, the usps-v3 SDK, or RevAddress.
4. Handle the Address1/Address2 swap explicitly. It corrupts addresses silently rather than raising an error, which makes it the most expensive item on this list.
5. Build token refresh with caching if you go direct. Eight-hour tokens, refresh on a buffer, honor Retry-After.
6. Test against 60 req/hr before deploying. Confirm your volume fits or file the increase request now.
7. Retest international with ISO 3166-1 alpha-2 country codes.

Steps 3 through 7 are a weekend. Step 2 is the calendar.

Start here

• Get a free API key — standardization, geocoding, and address extract on Census Bureau data, 1,000 requests a month, no credit card and no USPS license
• Migration checklist — the step-by-step version of this post
• CRID and MID enrollment — the license, the EPA, and claims linking
• What the v3 API costs — the fee curve and what third parties charge
• OAuth troubleshooting — every 401, 403, and 429 with its fix
• Shipping API comparison — EasyPost vs Shippo vs ShipEngine vs RevAddress

DPV, ZIP+4, rates, tracking, and labels are USPS data and run on your own USPS license on every plan. Census standardization and geocoding do not need one.