USPS Web Tools to v3 REST API:
Complete Endpoint Mapping

Master Endpoint Mapping

Every Web Tools XML API and its v3 REST equivalent. Method colors: GET for reads, POST for writes.

Address APIs

Tracking APIs

Shipping & Label APIs

Pricing APIs

Service Standards & Locations

Authentication: Before & After

Web Tools embedded a plain-text USERID in every XML request body. No scopes, no expiry, no rotation. The v3 API uses standard OAuth 2.0 client credentials — tokens expire after 8 hours and support granular scopes.

<!-- Auth embedded in every XML request -->
POST https://secure.shippingapis.com
  /ShippingAPI.dll?API=Verify

<AddressValidateRequest
  USERID="YOUR_USERID">
  <Address>
    <Address1>Apt 2</Address1>
    <Address2>1600 Pennsylvania Ave</Address2>
  </Address>
</AddressValidateRequest>

<!-- USERID in plain text. No expiry.
     No scopes. No rotation. -->

// Step 1: Get OAuth token (valid 8 hours)
POST https://apis.usps.com/oauth2/v3/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&scope=addresses tracking prices labels

// Step 2: Use Bearer token in header
GET /addresses/v3/address
Authorization: Bearer {access_token}

// Scoped. Rotatable. Standard OAuth 2.0.

Key Gotchas

These are the migration landmines that don't show up in USPS's own documentation. Every one of these has broken a production system.

// Label creation requires TWO tokens:

// 1. Standard OAuth token (addresses, tracking, prices)
POST /oauth2/v3/token
  grant_type=client_credentials
  scope=addresses tracking prices

// 2. Payment Authorization token (labels only)
POST /payment-authorization/v3/payment-token
  Authorization: Bearer {standard_token}
  {
    "roles": [
      { "roleName": "PAYER",
        "CRID": "YOUR_CRID",
        "MID": "YOUR_MID" }
    ]
  }

// 3. Create label with BOTH tokens
POST /labels/v3/label
  Authorization: Bearer {standard_token}
  X-Payment-Authorization: {payment_token}

// Web Tools XML (REVERSED semantics)
<Address1>Apt 2</Address1>         ← secondary
<Address2>1600 Penn Ave</Address2>  ← primary street

// v3 REST JSON (correct semantics)
{
  "streetAddress": "1600 Penn Ave",   ← primary
  "secondaryAddress": "Apt 2"        ← secondary
}

// If you map Address1 → streetAddress, every
// apartment number becomes the street. Ask us
// how we know.

Quick Reference: Field Name Changes

Beyond the endpoint mapping, many field names changed between Web Tools XML and v3 JSON. Here are the most-used fields:

How RevAddress Handles This

RevAddress wraps all v3 endpoints with production-grade infrastructure — so you don't have to build the OAuth token management, rate limit handling, and caching yourself.

• 37 routes mapped — every v3 endpoint wrapped with validation, caching, and error normalization
• OAuth abstracted — tokens cached, refreshed proactively 30 minutes before expiry, Payment Auth handled automatically
• Rate limits managed — request queuing, burst smoothing, and automatic retry with exponential backoff
• BYOK support — bring your own USPS credentials to use your rate limit increase, with AES-GCM encryption at rest

Open-source SDKs handle the client-side integration: Python (PyPI) and Node.js (npm).