postalref

USPS APIs and shipping software

The USPS APIs let a business's software verify addresses, price and label packages, and track them. Developers get access through the USPS Developer Portal and test in a separate environment before production. Click-N-Ship prints labels with postage on usps.com, and the Parcel Data Exchange API moves manifest files between a shipper's software and USPS.

Updated November 6, 202659 sources

Questions

How do I create a USPS shipping label at home?

Click-N-Ship, the USPS shipping application on usps.com, lets a customer print shipping labels with postage from their own computer. The customer signs in to a free USPS.com account to use it, which also offers file upload and bulk edits. Software built on the USPS APIs makes 4x5 or 4x6 inch shipping labels, thermal labels included, in file formats such as PDF and ZPL. Without a printer, a customer can print a label at a Post Office from a USPS Label Broker QR code.

How do I use the USPS address validation API?

Software sends a domestic address to the USPS Addresses API, which verifies and standardizes it and adds a missing ZIP + 4. Like every USPS API, it needs an app on the USPS Developer Portal and an OAuth token. From August 1, 2026, USPS charges for it monthly, under a license a business requests in the Business Portal and signs through DocuSign.

What replaced the USPS Web Tools API?

USPS retired the Web Tools platform on January 25, 2026, and its users move to the USPS APIs on the USPS Developer Portal. For tracking, they move to Tracking 3.2, the only Tracking API that PTR2, USPS's rebuilt tracking platform, supports.

Where do I download Click-N-Ship Business Pro?

Click-N-Ship Business Pro is a label program that users download from the Business Customer Gateway, USPS's entry point for online business services. USPS plans to retire it and will advise its users to move to Click-N-Ship.

How do I get a USPS API key?

A developer creates an app on the USPS Developer Portal, and the app gives them a key and secret. The key and secret get an OAuth token, which every USPS API call needs. The Business Portal, where a business opens its USPS account, can also create and update Developer Portal apps.

Does the USPS API have a rate limit?

Yes, each USPS API limits the requests a user may make in a day, by the type of API and data requested. USPS enforces the hourly call quota on each app, not on each business location or token. The Customer Access Team at APISUPPORT@usps.gov takes requests to raise it.

Is the USPS tracking API free?

From April 2026, the Tracking API and Tracking Webhook are free for merchants and shippers, and for platforms and label providers. Other businesses pay a monthly fee, charged per tracking number. Software vendors whose customers send manifests under their own credentials get no free tracking data.

Why doesn't the USPS tracking API show origin and destination?

USPS stopped giving package origin and destination details in the Tracking API and Tracking Webhook in June 2025, in every version. Tracking 3.2, the PTR2 version, also differs on purpose from USPS.com in some events and messages.

How it fits together

A business that ships with USPS opens a USPS business account, which holds three identifiers: a Customer Registration ID, a Mailer ID and an Enterprise Payment Account. It needs all three to use the USPS APIs, USPS Ship and Click-N-Ship. Its developers then create an app on the USPS Developer Portal and test it in MCAT, the test environment for USPS API users. USPS Web Tools, the older suite of USPS APIs, retired on January 25, 2026.

The USPS APIs price a package, create its label and generate its Shipping Services File, the electronic file of manifest and payment information. The Tech Sheets for APIs, Click-N-Ship, and USPS Ship are USPS's documents on these platforms. A shipper whose own software makes its labels sends its manifests through Parcel Data Exchange or a file-transfer protocol such as SFTP. USPS Ship, the platform in paying for packages, prices each package from its manifest and checks it against scans.

Once USPS scans a package, its tracking platform, Product Tracking and Reporting or PTR, makes the scan events available three ways. Software asks the Tracking API for a package's latest status, or subscribes to the Tracking Webhook to have events pushed to it. The third way, Scan Event Extract files sent through Data Transfer Services, belongs to package tracking.

Smaller shippers without a software vendor use Click-N-Ship, which prints labels with postage on usps.com. Merchants offer their customers return labels through the Merchant Returns API. The Informed Delivery API lets mailers and shippers manage Informed Delivery campaigns from their own applications.

The USPS APIs

The USPS APIs are an online platform that lets a business's software request USPS services and data for its shipping. Each API handles one part of shipping a package, from its address to its delivery.

JobAPI
Verify and standardize an addressAddresses
Price a domestic packageDomestic Prices
Price an international packageInternational Prices
Create a domestic label and its Shipping Services FileDomestic Labels
Create an international label and its customs formsInternational Labels
Link many labels to one form USPS scans at acceptanceSCAN Form
Find a Post Office or destination entry facilityLocations
Get delivery standards or expected delivery datesService Standards
Schedule a package pickupCarrier Pickup
Track a packageTracking
Register customers by creating customer and mailer IDsOrganizations

How a business's software gets access to the USPS APIs.

  1. Open a USPS business account in the Business Portal, which issues a Customer Registration ID, Mailer ID and Enterprise Payment Account.
  2. Create an app on the USPS Developer Portal, which gives a key and secret.
  3. Call the OAuth 2.0 API with the key and secret to get a token.
  4. Before making labels, get a payment token that names the payer and the label owner.
  5. Call each API with the token at apis.usps.com, the production host.

Every label needs a payer and a label owner, the Mailer ID that creates its tracking number. Other roles, such as the platform used to create labels, are optional. Labels get commercial rates unless the payment call names an authorized account or permit with contract rates.

A user of the USPS APIs agrees not to make more requests in a day than each API's limit allows. Each API's limit depends on the API and the data requested. USPS may change a limit without notice.

The Addresses API is not free: from August 1, 2026, USPS prices it in tiers, and its use needs a signed license agreement. USPS charges it monthly, and the month's number of record requests sets one tier for the whole month. Tier 1 is a flat fee, and tiers 2 to 4 charge per 1,000 requests or part of 1,000. USPS debits the month's Addresses Usage Fee from the Enterprise Payment Account at the start of the next month.

As of October 4, 2026, the Addresses API's monthly fees are these.

Record requests in a monthFee
Tier 1: up to 2,000$10.00 flat
Tier 2: up to 10,000$4.50 per 1,000
Tier 3: up to 50,000$4.25 per 1,000
Tier 4: over 50,000$4.00 per 1,000

How a business gets its Addresses API license.

  1. Create or log in to a Business Portal account.
  2. Create an Enterprise Payment Account if there is none, prefunded or debited from a bank account.
  3. Accept the updated Terms & Conditions in the Business Portal, at My Apps > Developer Apps > Manage.
  4. Add an Addresses API License in the Business Portal, at My Account > API Licenses.
  5. Sign the order form and license agreements that USPS sends by DocuSign email.

USPS Web Tools was the older suite of USPS APIs, for building USPS shipping into websites, call centers and back-office systems. USPS retired the Web Tools platform on January 25, 2026, and its tracking users move to Tracking 3.2.

USPS Developer Portal

Also called Developer Portal, USPS API Developer Portal

“The Developer Portal provides coding examples and downloadable specifications to accelerate integration.”

Platform

“The platform used to create labels”

USPS Application Programming Interfaces

Also called USPS APIs, USPS API Platform, USPS suite of APIs

“The USPS suite of APIs enables integrators to standardize an address, price a package, create a label, find a USPS acceptance facility, schedule a carrier pick-up, and track a package from entry to delivery.”

Payer

“Who is paying the postage”

Label Owner

“The mailer ID used to create the tracking number and generate manifest files”

Business Portal

Also called COP, Business Portal (Formerly Customer Onboarding Portal), Customer Onboarding Portal, USPS Business Portal

“The United States Postal Service (USPS)Business Portal (COP) offers business customers a modern, streamlined way to create and manage a USPS business account set-up and onboard core services.”

Test and production environments

MCAT, Mailer Customer Acceptance Testing, is the environment where USPS Ship and USPS API users test functionality before production. In MCAT, a developer can try an integration from authentication through label creation. USPS encourages API users to start in testing, then move to production at https://developers.usps.com.

Credentials belong to one environment: production credentials don't work in MCAT, and MCAT credentials don't work in production. A token made in MCAT can't call production APIs either. MCAT's APIs are at apis-cat.usps.com, and production's are at apis.usps.com.

MCAT runs every function of the production Labels API, but it watermarks each label and charges no postage. It holds no operational data such as scans or refunds. Load tests go to the Test Environment for Mailers instead, by a service request through Email Us, USPS's web contact page at https://emailus.usps.com/s/web-tools-inquiry.

Parcel Data Exchange, or PDX, the service that carries manifest files, keeps a separate test copy called PDX CAT. Each PDX upload also names its environment, such as TEM for test data. PDX CAT needs its own accounts and Mailer IDs.

Mailer Customer Acceptance Testing

Also called MCAT

“The objective of the Mailer Customer Acceptance Testing (MCAT) environment is to provide USPS Ship and USPS API users with a capability to validate new and upcoming functionality prior to production.”

Test Environment for Mailers

Also called TEM, Testing Environment for Mailers, TEM (Testing Environment for Mailers)

“The Test Environment for mailers (TEM) is a test platform designed to allow mailers to test their ability to submit electronic mailing information such as Full Service (FS) mailings to the Postal Service.”

PDX CAT environment

“separate from PDX Production and provides an isolated testing environment or “sandbox” for customers to test PDX file uploads, lists and downloads without impacting any Production data”

Manifest files through PDX

PDX is a web and API application that carries manifest files to USPS and outbound files back to the customer. The Domestic Labels API generates the Shipping Services File for each label it makes. Shippers whose own or off-the-shelf software makes labels send their manifests through PDX or a file-transfer protocol such as SFTP.

PDX is free for business customers and third-party vendors. Each call carries a Business Customer Gateway username and password. PDX skips the Data Transfer Services setup, so a shipper can enroll online and ship the same day. Its outbound files include the data extracts and error-warning reports that PTR generates.

PTR2 accepts Shipping Services Files only in versions 1.6, 1.7 and 2.0.

Tracking APIs and webhooks

USPS recommends that businesses building tracking into their systems use its Tracking API and webhooks. The right one depends on the business's need:

  • The Tracking API returns a package's latest tracking details when software asks, by tracking number. It suits software that wants occasional updates and can't store tracking events.
  • The Tracking Webhook pushes scan events to the subscriber as they happen, for a tracking number or a whole Mailer ID. USPS recommends it to a business that keeps its own tracking history.
  • Scan Event Extracts are files of scan events, kept for experienced partners that prefer existing transmission methods.

PTR2, the platform that replaces PTR, supports only Tracking 3.2. Tracking 3.2 became available on August 15, 2025, and USPS plans to retire Tracking 3.0 in 2026. USPS also plans to retire the Tracking Summary API, whose data is in Tracking 3.0 and Tracking 3.2.

The Tracking Webhook offers two subscriptions under Tracking 3.2. The Tracking Subscription sends the whole event history at each event, with the Tracking API's fields. The Detailed Scan Subscription sends only the current event, plus extract fields such as Mailer IDs and container information.

Starting April 2026, USPS controls access to tracking data to improve security and fight fraud. A label provider or consolidator needs MID authorization for a merchant's Mailer IDs, and other service providers need tracking authorization. Paid users add a payment token to each Tracking API request or webhook subscription.

Tracking Subscription

“This subscription provides the tracking results at the time of the event and includes the entire event history, along with the fields available on the Tracking API.”

Detailed Scan Subscription

“A new subscription that streamlines the payload by delivering only the current event, rather than the entire event history.”

USPS Tracking API

Also called Tracking APIs, PTR Tracking API

“User requests one-time update of the latest detailed tracking information, including package status and delivery updates, for a specific tracking number.”

Tracking Webhook

Also called Webhook, Webhook Subscriptions

“User subscribes to be pushed to scan events as they occur in near-real-time, for a specific tracking number or Mailer ID.”

scan event extract file

Also called CDE, DETEXTRO, Scan Event Extracts (PTR), Scan Event Extract, Customer Data Extract, Customer Daily Extract

“This file contains every scan event that occurs on every package that the mailer included in the Shipping Services file.”

MID authorization

“provides label providers and consolidators with access to label generation, rates and tracking for select MIDs”

Tracking authorization

“provides service providers and other companies with access to tracking data for select MIDs”

Click-N-Ship and Label Broker

Click-N-Ship is the USPS shipping application on usps.com that prints labels with postage on the customer's own computer. It serves smaller mailers who use no software vendor and don't presort. It sends USPS the Shipping Services File, with manifest, tracking and postage payment, for each label. A business account's Ship Now action opens it to print labels.

Click-N-Ship Business Pro is a label program that users download from the Business Customer Gateway. Shippers who used it with eVS, the electronic verification system, had to move to USPS Ship or the USPS APIs by February 2025. USPS Ship replaces eVS, not Click-N-Ship Business Pro. USPS Ship brings no change to how Click-N-Ship Business Pro makes and prints labels, and Business Pro users need no other software client. USPS plans to retire Click-N-Ship Business Pro itself and will advise its users to move to Click-N-Ship.

USPS Label Broker serves customers without a printer. It stores a label under a QR code or Label Broker ID, which the customer prints at a Post Office or on USPS.com. The Merchant Returns API can send its return labels to Label Broker.

Click-N-Ship Business Pro

Also called CNSBPro, CNBPro

“In CNSBPro, users can generate labels through the downloadable CNSBPro Graphical User Interface (GUI) from Business Customer Gateway (BCG)”

USPS Label Broker service

Also called USPS Label Broker, Label Broker

“facilitates shipping for consumers without access to a printer. It allows customers to print labels using a QR Code or Label Broker Label ID at a USPS® Post Office® or via USPS.com.”

Click-N-Ship

Also called CNS

“An online USPS shipping application through usps.com that enables customers to print shipping labels with postage from their own computers.”

Business Customer Gateway

Also called BCG, BCG (Business Customer Gateway)

“where shippers can manage their mailing activity”

What goes wrong

  • Credentials and tokens work only in the environment that issued them, so a token from MCAT fails in production.
  • USPS may limit or deny API access when it suspects data mining, address-list building or requests built to get around its terms.
  • Moving to PTR2 changes the data format of the Tracking API and webhooks, so existing users must cut over.
  • PTR2 no longer accepts Shipping Services File versions 1.3, 1.4 and 1.5.
  • A PDX account inactive for more than 90 days is deactivated, and five or more uploads a minute may deactivate it.
  • A merchant that generates many unused labels may lose its use of Label Broker.
  • USPS may revoke API credentials for a breach of its terms or for suspected fraud.

Index: 24 entries

Services (10)

Systems (7)

Document (1)

Roles (2)

Terms (4)

Sources