Installation

Requirements

• CS-Cart or CS-Cart Multi-Vendor 4.17.2 – 4.21.x.
• PHP 7.4 – 8.3 with the cURL and OpenSSL extensions (standard on CS-Cart hosting). The server must reach apis.usps.com (and apis-tem.usps.com for the USPS test environment) over HTTPS.
• A US Dollar currency in Administration → Currencies (USPS prices are in USD; CS-Cart converts them into your store currency).
• A USPS developer app (free) for rates, address validation and tracking.
• For labels: a USPS business account with a CRID, a Mailer ID (MID) and an Enterprise Payment Account (EPA), and the Labels and Payments APIs added to your app by USPS.

Register with USPS

1. Developer app (rates, addresses, tracking)

1. Open developers.usps.com and sign in or create a free USPS.com account.
2. Go to Apps → Add App, give it a name and create it.
3. Open the app and copy its Consumer Key and Consumer Secret. These are the add-on’s credentials.

The default app includes the Addresses, Domestic and International Prices, Shipping Options and Tracking APIs. USPS can also give you access to the test environment (TEM, apis-tem.usps.com).

2. Label account (labels only)

1. In the USPS Business Customer Gateway note your Customer Registration ID (CRID) and Mailer ID (MID).
2. Open or link an Enterprise Payment Account (EPA): postage for labels is paid from it.
3. Complete the Customer Onboarding Portal (COP) steps that USPS describes for the Labels API, and ask USPS to add the Labels and Payments APIs to your developer app.

Until these steps are done, rates, address validation and tracking work; buying a label shows which fields are missing.

Install

1. In the admin panel open Add-ons → Manage add-ons, click the + button and upload the add-on archive.
2. Click Install next to USPS Rates & Labels.
3. Enter your license key in the add-on settings, License section (or the Marketplace license number under Add-ons → Manage).

On install the add-on creates one CS-Cart shipping service per USPS service (carrier USPS (new APIs)) and three starter box presets.

Privileges

• Labels belong to orders: View orders to see them, Edit order details to buy, void and track.
• USPS account, box presets and the API log need Manage settings.
• Multi-Vendor vendors see the labels of their own orders. In the Vendors label mode they also manage their own USPS account and buy labels.

Cron (tracking updates)

Labels that are not delivered yet are refreshed every time the cron job runs (each label at most every 3 hours). Run it every 3 to 6 hours:

php /path/to/store/admin.php --dispatch=kv_usps_v3.cron

Or call the URL shown in the add-on settings (Tracking updates), which contains a secret key. Without cron, use Update tracking on the USPS labels page or Refresh tracking on the order.

Upgrading

Upload the new archive over the old one (Add-ons → Manage → upload). The add-on applies its own database changes on the next admin page load; settings, accounts and labels stay.

Uninstalling

Uninstalling removes the add-on tables (USPS account, labels and their PDF/ZPL files, box presets, log) and the USPS (new APIs) shipping services. Shipping methods that used them are disabled, not deleted. Shipments with USPS tracking numbers stay on the orders. Download the labels you still need before you uninstall.