USPS Rates & Labels for OpenCart

Overview

USPS Rates & Labels brings USPS shipping back to your OpenCart 4 shop on the new USPS APIs. USPS retired its Web Tools API on 25 January 2026, and many OpenCart USPS extensions still call it. This extension talks to the new USPS APIs (OAuth 2.0) with your own USPS developer account: live prices and delivery estimates at checkout, labels bought and printed from the order page, tracking in the order history, void and refund. You pay USPS postage only; there is no aggregator account and no per-label fee.

What it does

• Live prices at checkout. One USPS shipping method with a line per service you enable: USPS Ground Advantage, Priority Mail, Priority Mail Express, Media Mail, Library Mail, Bound Printed Matter, the flat rate envelopes and boxes, and the international services. Each line shows the USPS delivery estimate. Services that do not serve the destination are skipped.
• Price rules. Retail, commercial or contract prices; percent markup and a fixed handling fee; rounding up; a free shipping threshold; a fallback rate when USPS cannot be reached; signature confirmation priced in; tax class and geo zone like any OpenCart shipping method.
• Packaging. Package presets with packing weight and maximum weight, the smallest preset that carries the cart, the product's own size for single-item carts, heavy carts split into several packages, USPS dimensional weight reported.
• Labels from the order page. A USPS tab on the order: pick the service (preselected from what the customer chose), check weight and size, get the rate, buy. PDF, ZPL or PNG labels, domestic and international with the customs declaration and remembered HS codes, signature confirmation, insurance.
• Tracking. The tracking number is written to the order history (the customer sees it in the account, with an optional e-mail), tracking refreshes by cron, and delivery can move the order to a status you choose.
• Void and refund. Unused labels are cancelled; labels already scanned get a refund request.
• Address check. USPS standardizes the shipping address on the order page; one click uses the suggestion on the label.
• Safe. Credentials and tokens are stored encrypted, secrets never reach the log, label files are only served to logged-in administrators. Events, cron and a shipping extension only: no OCMOD, no core edits. OpenCart 4, tested on 4.1.0.4.

Limits to know

• You need a free USPS developer account (developers.usps.com) and an app. Rates and address validation need only its Consumer Key and Secret. Labels also need the Customer Registration ID (CRID), Mailer ID (MID) and an Enterprise Payment Account (EPS or permit), and USPS must add the Labels and Payments APIs to your app. USPS decides who may use them.
• Prices are in US dollars and converted to the store currency with the currencies of your shop (add USD to Localisation > Currencies when the store currency is another one).
• One label per order covers all shippable items (one package). Global Express Guaranteed is priced but USPS offers no label API for it.
• The extension was tested against a stand-in of the USPS APIs built from the official USPS OpenAPI specifications, not against the live USPS production service. Run the manual steps in the Developer notes with your own account once.
• USPS does not allow every address type or service for every account; USPS error messages are shown as they are.

USPS is a trademark of the United States Postal Service. This extension is not affiliated with, endorsed by or sponsored by USPS.

Installation

Requirements: OpenCart 4.1.0.x, PHP 7.4 or newer with cURL and OpenSSL, a free USPS developer account.

1. In the admin open Extensions > Installer, upload kv_usps_v3.ocmod.zip and click Install.
2. Open Extensions > Extensions, choose Shipping, find USPS Rates & Labels and click the green Install button, then the blue pencil to open the settings.
3. On the USPS account tab enter your Consumer Key and Consumer Secret and the ship-from address, click Save account, then Test connection. A green message with a Ground Advantage price means the connection works.
4. On the Checkout tab choose the services, set the status to on and save.
5. Make sure the OpenCart cron job runs (see Orders and tracking), so tracking refreshes by itself.

Uninstall: Extensions > Shipping > Uninstall removes the settings, the account, the labels and the log. Labels already bought stay valid at USPS and their tracking numbers stay in the order history. Then remove the extension in Extensions > Installer.

Update: upload the new zip in the Installer; the settings and the account stay.

Configuration

Extensions > Extensions > Shipping > USPS Rates & Labels.

Checkout

USPS account

Consumer Key and Secret come from your app on developers.usps.com. For labels add CRID, MID, the payment account (EPS or permit) and the ship-from address. The secret is stored encrypted and never shown again; leave the field empty to keep it.

Packaging

Package presets (name, size, packing weight, maximum weight), the preset used for prices (automatic = the smallest that carries the weight), a default size, packing weight, the maximum weight of one package (carts above it are split), and whether a single item uses its own length, width and height from the product. Weights and sizes are converted from your OpenCart units (kg, g, lb, oz, cm, mm, in).

Orders and tracking

Order status after a label is bought, order status when USPS reports delivery, e-mail to the customer with the tracking number, debug log (every request; secrets are masked). The tab also shows the cron command and a secret web address for the tracking refresh.

Usage

At checkout

The customer chooses the shipping method USPS and one of its lines, for example "Priority Mail (2 Days) - $23.05".

Buy a label

Open the order (Sales > Orders > view) and the USPS tab under the history.

1. The service is preselected from the customer's choice; the weight and size come from the packaging settings. Change them to what is really in the box.
2. Optional: Check address with USPS, then Use this address.
3. Get rate shows the postage, delivery estimate, zone and billable weight. Buy label creates the label.
4. International orders also show the customs declaration: description, quantity, value, weight, HS code and origin per line.

The tracking number is added to the order history (and the status you chose). Print opens the PDF; ZPL labels download. Refresh reads the tracking from USPS; the cron job does it every hour for open labels.

Void

Void cancels an unused label. A label USPS has already scanned gets a refund request, shown as "Refund requested".

Developer notes

Identity

Events and cron

USPS API conformance

Endpoints, request and response shapes follow the official OpenAPI specifications published on developers.usps.com.

Not covered: SCAN forms and manifests, pickup requests, Priority Mail Open and Distribute, USPS Connect, hold for pickup, and any service needing a contract.

Testing

tests/unit.php (php81 and php83) runs against tests/mock-server/mock.php, a stand-in built from the specifications, and a throw-away MariaDB database. tests/e2e.js drives an OpenCart 4.1.0.4 store in a headless browser: account form and connection test, checkout quotes (domestic, international, markup, free threshold, fallback, services, geo zone, product size, split), label purchase, print, tracking, cron, void, address check, uninstall.

Manual steps with your own account (not done by us): enter the Consumer Key and Secret and save; compare two checkout prices with the USPS Postage Price Calculator; with CRID, MID and payment account and the Labels and Payments APIs enabled, buy, print and void one domestic and one international label (use the Testing Environment for Mailers if USPS granted it).

USPS is a trademark of the United States Postal Service. This extension is not affiliated with, endorsed by or sponsored by USPS.

FAQ

Is this the old USPS Web Tools API?

No. Web Tools was retired by USPS on 25 January 2026. This extension uses the new USPS APIs with OAuth 2.0.

Do I need an aggregator account?

No. You use your own USPS developer account and pay USPS postage only.

Why do I need a CRID, MID and payment account?

Only for labels. USPS requires them to charge postage. Rates and address checks need only the Consumer Key and Secret.

Can I use it for non-US stores?

The prices are USPS prices in US dollars for parcels shipped from the United States; they are converted to the store currency.

Does it work with OpenCart 3?

No, OpenCart 4.1 only.

Does it use OCMOD?

No. A shipping extension, events and cron.

Where is the tracking number?

In the order history and on the USPS tab. The customer sees it in the account.

Is it affiliated with USPS?

No. USPS is a trademark of the United States Postal Service.