Carrier’s official API

USPS API: integration guide

The United States Postal Service runs a REST/JSON API platform at apis.usps.com, documented on the USPS Developer Portal. It covers address validation, domestic and international prices, labels, tracking, carrier pickup, delivery standards, post office and drop-off locations, and SCAN forms. It replaces the legacy XML Web Tools APIs, which USPS retired on January 25, 2026; the Web Tools page now warns that the old platform may be degraded or interrupted at any time. The APIs are used by ecommerce sites, shipping platforms, 3PLs and anyone building USPS shipping into their own software.

This guide covers USPS’s own API (apis.usps.com). Credentials come from USPS, not from FreightAPIs, and we are not affiliated with them.

Want one API key for carrier terminals, NMFC and ports instead? USPS location API · FreightAPIs API docs →

Interface REST/JSON (most APIs also accept XML)Endpoints 39Reviewed 2026-10-09Open in ChatGPT↗Open in Claude↗

At a glance

CarrierUSPS (United States Postal Service)
TypeNational postal carrier (parcel & mail)
InterfaceREST/JSON (most APIs also accept XML)
AuthenticationOAuth 2.0 (client credentials) bearer token
CapabilitiesAuthentication, Address validation, Domestic & international prices, Shipping options & delivery standards, Labels, Payment authorization, Tracking & proof of delivery, Carrier pickup, Locations, SCAN forms & containers

Getting access

  • Sign in to, or create, a USPS Business Account through the USPS Customer Onboarding Portal (COP). The portal configures the account for the USPS APIs.
  • In the COP Business Portal, open "My Apps", create an app and copy its Consumer Key and Consumer Secret. These are the OAuth client_id and client_secret.
  • Every new app gets a default product: OAuth, Addresses, Domestic Prices, International Prices, Locations, Service Standards, Service Standards Files, Shipping Options, UserInfo and Tracking.
  • Other APIs, and higher quotas, are requested through a USPS API service request on the Email Us page. The Labels APIs need extra approval: you must be enrolled in USPS Ship for outbound and return labels and have an Enterprise Payment Account.
  • Web Tools user IDs do not work on the new platform. Migrating users must onboard again and use the USPS mapping spreadsheets to map each Web Tools API to its replacement.
  • Calls are limited by an hourly quota per API product, and exceeding it returns HTTP 429.

Authentication

OAuth 2.0 (client credentials) bearer token.

  • POST to /oauth2/v3/token with `grant_type=client_credentials`, `client_id` (Consumer Key) and `client_secret` (Consumer Secret). The body can be JSON or form-encoded.
  • The response returns `access_token`, `token_type` (Bearer), `issued_at` (epoch milliseconds), `expires_in` and `scope`. The documented example shows expires_in of 28,799 seconds, about 8 hours. Request a new token before it expires.
  • Send `Authorization: Bearer <token>` on every API call. Each API checks the token, its expiry and its scope, so a token only works for the API products your app has been granted.
  • Refresh-token and authorization-code grants also exist (for resource-owner access), and POST /oauth2/v3/revoke invalidates a token.
  • Label purchases need a second token: POST /payments/v3/payment-authorization returns a payment authorization token (valid eight hours) that you send in the `X-Payment-Authorization-Token` header. The PAYER and LABEL_OWNER roles are required.

Environments

Productionhttps://apis.usps.com
Testing Environment for Mailers (TEM)https://apis-tem.usps.com

Endpoints

Authentication

Issue and revoke OAuth 2.0 tokens for your app.

POST/oauth2/v3/tokenExchange client credentials (or a refresh token or auth code) for an access token.
POST/oauth2/v3/revokeInvalidate a token.
Key inputsgrant_typeclient_idclient_secret
Key outputsaccess_tokentoken_typeissued_atexpires_inscope

Address validation

Standardizes an address to USPS format, looks up the city and state for a ZIP Code, or finds the ZIP Code for an address.

GET/addresses/v3/addressReturn the standardized address for the input address.
GET/addresses/v3/city-stateReturn the city and state for a ZIP Code.
GET/addresses/v3/zipcodeReturn the ZIP Code for an address.
Key inputsstreetAddress (required)secondaryAddress, city, state, ZIPCode, ZIPPlus4, firm, urbanization

Domestic & international prices

Price searches by rate ingredients. total-rates returns every eligible price including extra-service fees in one call, while base-rates prices one specific product. Separate endpoints cover extra services and First-Class letters, and the International Prices API mirrors the same set for outbound international mail.

POST/prices/v3/total-rates/searchList eligible prices, including extra-service fees, for a package.
POST/prices/v3/base-rates/searchGet the base price for one mail class and rate indicator.
POST/prices/v3/base-rates-list/searchSearch eligible products for the given rate ingredients.
POST/prices/v3/extra-service-rates/searchSearch extra-service prices for a package.
POST/prices/v3/letter-rates/searchPrice First-Class Mail letters, flats and cards.
POST/international-prices/v3/total-rates/searchList eligible international prices including extra services.
POST/international-prices/v3/base-rates/searchGet an international base price.
Key inputsoriginZIPCode, destinationZIPCodeweight (pounds), length, width, height (inches)mailClass or mailClasses (e.g. USPS_GROUND_ADVANTAGE, PRIORITY_MAIL, PRIORITY_MAIL_EXPRESS, PARCEL_SELECT)priceType (RETAIL, COMMERCIAL, CONTRACT)mailingDate (today to 7 days ahead)accountType (EPS, PERMIT, METER) and accountNumber for contract rates
Key outputsrateOptions[] with prices, SKUs and extra-service fees

Shipping options & delivery standards

Shipping Options returns the available products for a package with price and expected delivery together. Service Standards returns delivery-day estimates between two ZIP Codes, including cutoff times and acceptance locations.

POST/shipments/v3/options/searchReturn shipping options with pricing and delivery estimates.
GET/service-standards/v3/estimatesEstimate delivery dates between two ZIP Codes.
GET/service-standards/v3/standardsReturn the published service standard for a lane.
Key inputsoriginZIPCode, destinationZIPCodemailClass, acceptanceDate, acceptanceTime (estimates)weight and dimensions (optional)
Key outputsmailClassserviceStandardcutOffTimedeliveryacceptanceLocations

Labels

Creates domestic and international labels with Intelligent Mail package barcodes, prices the shipment, validates addresses and submits the shipping services file for you. Labels can be returned as PDF, image or ZPL, and you can also cancel or refund, edit, reprint and create return labels. Requires extra approval and a payment authorization token.

POST/labels/v3/labelCreate a domestic shipping label.
POST/labels/v3/return-labelCreate a domestic return label.
PATCH/labels/v3/label/{trackingNumber}Edit label attributes.
DELETE/labels/v3/label/{trackingNumber}Cancel a label or request a refund by tracking number.
POST/labels/v3/label-reprint/{trackingNumber}Reprint a domestic label.
POST/international-labels/v3/international-labelCreate an international label with customs data.
DELETE/international-labels/v3/international-label/{trackingNumber}Cancel or refund an international label.
Key inputsX-Payment-Authorization-Token header (required)X-Idempotency-Key header (optional; also usable to cancel or reprint)toAddress, fromAddress, senderAddress, returnAddresspackageDescription (mail class, weight, dimensions, extra services)imageInfo.imageType (PDF, TIFF, JPG, PNG, GIF, SVG, ZPL203DPI, ZPL300DPI, EPL300DPI…), imageInfo.labelTypecustomsForm (international and APO/FPO)
Key outputstracking numberpostagelabel image (multipart or JSON response)

Payment authorization

Creates the eight-hour payment token that label calls require, naming who pays, whose rates apply and who owns the label.

POST/payments/v3/payment-authorizationCreate a payment authorization token for label purchases.
GET/payments/v3/payment-account/{account-number}Check a payment account.
Key inputsroles[] (roleName such as PAYER, RATE_HOLDER, LABEL_OWNER, PLATFORM; CRID; MID; accountType; accountNumber)
Key outputspaymentAuthorizationToken

Tracking & proof of delivery

Tracking v3r2 takes a batch of up to 35 tracking numbers in one POST and returns status, expected delivery and events for each. You can also register email notifications and request a proof-of-delivery record by email for items with signature or Return Receipt (Electronic) service. A separate Subscriptions - Tracking API pushes events to your endpoint.

POST/tracking/v3r2/trackingGet tracking status and events for 1 to 35 tracking numbers.
POST/tracking/v3r2/tracking/{trackingNumber}/notificationsRegister email notifications for a package.
POST/tracking/v3r2/tracking/{trackingNumber}/proof-of-deliveryRequest a proof-of-delivery record by email.
POST/subscriptions-tracking/v3r2/subscriptionsSubscribe to pushed tracking events.
Key inputstrackingNumber (4–34 alphanumeric)mailingDate and destinationZIPCode (optional, help resolve duplicate numbers)
Key outputsstatus, statusCategory, statusSummarydeliveryDateExpectationmailClass, origin and destinationtrackingEvents[]

Carrier pickup

Checks whether an address is eligible for free carrier pickup, then schedules, reads, changes or cancels the pickup. Pickups are available Monday to Saturday for Priority Mail Express, Priority Mail, USPS Ground Advantage, international services and returns.

GET/pickup/v3/carrier-pickup/eligibilityCheck that an address is eligible for pickup.
POST/pickup/v3/carrier-pickupSchedule a pickup.
GET/pickup/v3/carrier-pickup/{confirmationNumber}Get a scheduled pickup.
PUT/pickup/v3/carrier-pickup/{confirmationNumber}Change a scheduled pickup.
DELETE/pickup/v3/carrier-pickup/{confirmationNumber}Cancel a scheduled pickup.
Key inputspickupDatepickupAddresspackagesestimatedWeightpickupLocation
Key outputsconfirmationNumber

Locations

Finds post offices, parcel lockers and drop-off (destination entry) locations near an address or coordinates, with service filters.

GET/locations/v3/post-office-locationsSearch post offices by address, ZIP Code or coordinates.
GET/locations/v3/parcel-locker-locationsSearch USPS parcel lockers.
GET/locations/v3/dropoff-locationsFind a valid entry location for destination-entry parcels.
Key inputsZIPCode or streetAddress/city/state, or LAT and LONGradius, limit, offsetservice filters such as passportService or pickupService

SCAN forms & containers

Creates a SCAN form (a manifest of labels for acceptance scanning) and manages container labels and container manifests for bulk drop-offs.

POST/scan-forms/v3/scan-formCreate a SCAN form for a set of packages.
POST/containers/v3/containersCreate a container label.
POST/containers/v3/containers/manifestClose a container.
Key inputsmailingDate, entryFacilityZIPCode, destinationEntryFacilityType, fromAddress, shipment

Example request

Get an OAuth token, then price a packagebash
# 1) Client-credentials token (Consumer Key / Consumer Secret from your app) curl -X POST "https://apis-tem.usps.com/oauth2/v3/token" \ -H "Content-Type: application/json" \ -d '{ "grant_type": "client_credentials", "client_id": "YOUR_CONSUMER_KEY", "client_secret": "YOUR_CONSUMER_SECRET" }' # 2) All eligible prices for a 2 lb box curl -X POST "https://apis-tem.usps.com/prices/v3/total-rates/search" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "originZIPCode": "20260", "destinationZIPCode": "94107", "weight": 2, "length": 12, "width": 9, "height": 4, "mailClasses": ["USPS_GROUND_ADVANTAGE", "PRIORITY_MAIL"], "priceType": "COMMERCIAL", "mailingDate": "2026-10-12" }'

TEM uses your production credentials; only the host changes (apis-tem.usps.com instead of apis.usps.com). Labels created in TEM are watermarked and not charged.

Integration notes

  • Testing happens in TEM with your production account and keys. There is no separate sandbox signup, so you must finish onboarding before you can test.
  • Weights are in pounds and dimensions in inches. Prices use the greater of actual and dimensional weight, and a mailingDate can be at most 7 days ahead.
  • The single mailClass field on price requests is deprecated in favour of the mailClasses list, and priceType NSA is deprecated in favour of CONTRACT. If you send an accountNumber, it overrides the requested priceType.
  • Use Tracking v3r2 for new work. USPS says the legacy Tracking 3.0 and Subscriptions - Tracking 3.0 APIs retire on July 31, 2027, and v3r2 can show slightly different events and wording than USPS.com.
  • A label call needs two tokens: the OAuth bearer token and a payment authorization token in X-Payment-Authorization-Token. The payment token lasts eight hours, so cache it alongside the OAuth token.
  • Send an X-Idempotency-Key when creating labels. It protects against double purchases on retries, and you can later cancel or reprint a label with the same key.
  • Carrier pickups for the same day must be booked before 2:00 AM Central time; after that, schedule for a later date (up to a year ahead).
  • HTTP 429 means you hit your hourly quota. Ask for a quota increase through a USPS API service request rather than retrying aggressively.

FAQ

Are the USPS Web Tools APIs still available?

USPS retired the Web Tools API platform on January 25, 2026 and warns that it may be degraded or interrupted at any time. Migrate to the REST APIs at apis.usps.com; Web Tools credentials do not carry over.

How do I get a USPS API key?

Create a USPS Business Account through the Customer Onboarding Portal, add an app under My Apps, and copy its Consumer Key and Consumer Secret. Exchange them for an OAuth token at /oauth2/v3/token.

How long does a USPS OAuth token last?

The documented example shows expires_in of 28,799 seconds, about 8 hours. Read expires_in from each token response and refresh before it lapses.

Is there a USPS API sandbox?

Yes. The Testing Environment for Mailers (TEM) at apis-tem.usps.com uses your production credentials. Labels created there are watermarked and not charged.

Can I create USPS shipping labels with the API?

Yes, but the Labels APIs are not in the default product. You need extra approval, USPS Ship enrollment and an Enterprise Payment Account, plus a payment authorization token on each label request.

On FreightAPIs

USPS locations lookup →Free: which location serves a ZIP, no account needed.USPS location API →Our JSON API for the same data, one key for every carrier.Freight class calculator →Density and estimated class before you request a quote.Accessorial codes by carrier →Liftgate, residential, limited access — each carrier’s code.

Official resources

Written from USPS’s published API documentation and last checked 2026-10-09. FreightAPIs is not affiliated with USPS; endpoints and access rules can change, so confirm details in the carrier’s own documentation before going live.

Other carrier API guides

ABF Freight · Estes Express Lines · Saia LTL Freight · TForce Freight · Old Dominion Freight Line · XPO (LTL) · AAA Cooper Transportation · AIT Worldwide Logistics