Real-time USPS rates via the new REST API v3.
A shipping module for osCommerce 4 (Yii2-based) that provides real-time USPS rate quotes using the new USPS REST API v3 with OAuth 2.0 authentication. Replaces the legacy USPS XML Web Tools API (RateV4/IntlRateV2) which USPS discontinued on January 25, 2026. Supports domestic, international, and US territory shipping with full admin configuration.
Live domestic and international shipping rates fetched during checkout via the USPS Prices API v3. Handling fees and tax classes applied automatically.
Modern Client Credentials grant flow. Tokens cached in memory and automatically refreshed on expiry. Auto-retry on 401 responses clears stale tokens and re-authenticates.
Priority Mail Express, Priority Mail, USPS Ground Advantage, Parcel Select Ground, Media Mail, Library Mail, and Bound Printed Matter.
Priority Mail Express International, Priority Mail International, First-Class Package International Service, and Global Express Guaranteed.
Domestic rates automatically apply to US territories: PR, VI, GU, AS, MP, MH, FM, and PW. No extra configuration needed.
HTTPS enforced with SSL peer and host verification. No plaintext secrets in files — credentials stored in the database. No third-party dependencies.
Extends ModuleShipping with configure_keys(), describe_status_key(), describe_sort_key(), and $defaultTranslationArray. Multi-platform support via platforms_configuration.
Configurable default package dimensions (length, width, height in inches) for more accurate rate quotes. Weight and box count passed from osCommerce cart.
Built-in toggle between USPS production (apis.usps.com) and testing (apis-tem.usps.com) environments. Verify everything works before going live.
Get the module running in 6 steps. Requires osCommerce 4, PHP 7.4+, and a USPS Developer account.
Go to developer.usps.com, create an account (or log in), and create a new application under Apps. Subscribe to the Prices API (domestic and international pricing).
Note your Consumer Key (Client ID) and Consumer Secret. These are your OAuth 2.0 credentials for the USPS REST API v3.
Copy the two module files into your osCommerce 4 installation:
# Create the API client directory
mkdir -p /path/to/oscommerce/lib/common/classes/usps
# Copy the API client and shipping module
cp lib/common/classes/usps/UspsApiClient.php \
/path/to/oscommerce/lib/common/classes/usps/
cp lib/common/modules/orderShipping/usps.php \
/path/to/oscommerce/lib/common/modules/orderShipping/
Ensure both files are readable by the web server:
chmod 644 /path/to/oscommerce/lib/common/classes/usps/UspsApiClient.php
chmod 644 /path/to/oscommerce/lib/common/modules/orderShipping/usps.php
Log in to your osCommerce Admin Panel, go to Modules → Shipping, find USPS in the list, and click Install Module. The module's configure_keys() method automatically creates all configuration entries in the platforms_configuration table.
Alternative: For manual SQL installation, edit @PLATFORM_ID in the script and import:
mysql -u your_db_user -p your_db_name < install/usps_install.sql
Edit the USPS module in Modules → Shipping and fill in your settings:
Start with Test Mode = True using your USPS TEM (test) credentials. Verify rates return correctly for both domestic and international destinations. Once confirmed:
Use testConnection() and getLastError() on the API client for debugging if rates aren't returned.
The checkout flow from cart to selected shipping method.
Use these codes in the Domestic and International Services configuration fields.
PRIORITY_MAIL_EXPRESS
PRIORITY_MAIL
USPS_GROUND_ADVANTAGE
PARCEL_SELECT
MEDIA_MAIL
LIBRARY_MAIL
BOUND_PRINTED_MATTER
PRIORITY_MAIL_EXPRESS_INTERNATIONAL
PRIORITY_MAIL_INTERNATIONAL
FIRST-CLASS_PACKAGE_INTERNATIONAL_SERVICE
GLOBAL_EXPRESS_GUARANTEED
osCommerce 4 (Yii2-based), PHP 7.4+, cURL and JSON extensions, valid SSL certificate, USPS API account at developer.usps.com.
Common issues and how to resolve them.
Verify your Consumer Key and Consumer Secret are correct. Check that Test Mode matches your credential type (TEM credentials for test, production for live). Ensure Origin ZIP Code is set (5 digits) and at least one service is listed in the Domestic or International Services fields. Check your server's PHP error log for cURL or API errors.
Double-check credentials at developer.usps.com. Ensure your USPS API application has the Prices API subscribed. TEM credentials only work with the test environment; production credentials only work with production.
Ensure your server has an up-to-date CA certificate bundle. Verify cURL has SSL support: php -i | grep cURL. Check that your server can reach apis.usps.com on port 443.
Verify your package dimensions are realistic. Check that the correct services are enabled. Compare rates with the USPS Price Calculator. Use getLastError() on the API client for structured error details.
Built for the USPS REST API v3 — the legacy XML API was discontinued January 2026.
Get Notified on Release