Magento 2 USPS OAuth Shipping Extension – User Guide | ToweringMedia

USPS OAuth Shipping Extension for Magento 2

Real-Time USPS Rates via REST API v3

📘 Overview

The USPS OAuth Shipping Extension enables your Magento 2 store to connect directly to the United States Postal Service (USPS) REST API v3 using OAuth 2.0 authentication. This replaces deprecated username/password integrations and ensures secure, accurate, and compliant communication with USPS.

Customers will see real-time USPS shipping rates during checkout, including domestic and international services.

✨ Key Features

Secure OAuth 2.0 authentication (no more API usernames/passwords)
Real-time USPS domestic and international rates
Support for Priority Mail, First-Class, Express, and more
Enable or disable individual USPS services
Set handling fees or discounts per rate
Sandbox mode for testing
Compatible with Magento multi-store and multi-origin setups
Tested with Magento 2.4.6–2.4.8 and PHP 8.2–8.3

⚙️ Installation

1. Via Composer

composer require toweringmedia/module-usps-oauth
bin/magento module:enable ToweringMedia_UspsOauth
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

2. Manual Installation

Upload the module to:

app/code/ToweringMedia/UspsOauth

Then run:

bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

🔐 Obtaining USPS OAuth Credentials

To use the extension, create a project in the USPS Developer Portal.

Log in to developer.usps.com
Click “My Projects” → “Create New Project”
Enable the following APIs:
- USPS Rate API v3
- OAuth 2.0 Authentication
Copy your Client ID and Client Secret

Tip: USPS may take up to 24 hours to approve production credentials.

🧭 Configuration

Go to Stores → Configuration → Sales → Shipping Methods → USPS OAuth.

Setting	Description
Enabled	Enable or disable the USPS OAuth shipping method
Title	Displayed title at checkout
Mode	Choose Sandbox or Production
Client ID	Enter your USPS Client ID
Client Secret	Enter your USPS Client Secret
Origin ZIP Code	ZIP code used to calculate rates
Allowed Methods	Select USPS services (Priority, First-Class, etc.)
Handling Fee	Add or subtract a fee per shipment
Free Shipping Threshold	Optional free shipping minimum
Debug Mode	Enable logging to `var/log/usps_oauth.log`

📦 How It Works

At checkout, Magento requests USPS rates through the OAuth API.
The extension retrieves and caches an access token.
USPS returns available services and rates.
Customers select their preferred USPS method and complete checkout.

🧪 Testing the Integration

Enable Sandbox Mode in configuration.
Enter sandbox Client ID/Secret from USPS.
Place a test order to confirm rates display correctly.
Check logs at var/log/usps_oauth.log for API responses.

🪶 Logging & Debugging

Enable Debug Mode to log all API requests and responses:

var/log/usps_oauth.log

Each entry includes a timestamp, endpoint, request payload, and response body for troubleshooting.

💡 Common Issues

Problem	Possible Cause	Solution
No rates showing	Invalid OAuth credentials	Check Client ID/Secret and correct API mode
403 Forbidden error	Production access not yet approved	Use Sandbox or wait for approval
Incorrect rates	Origin ZIP mismatch	Confirm correct ZIP in configuration
Token expired	Cron not running	Verify `bin/magento cron:run` executes regularly

🕒 Cron Job Requirements

The extension relies on Magento’s cron to refresh OAuth tokens.

bin/magento cron:run

Add this to your system cron (every 5 minutes):

*/5 * * * * php /path/to/magento/bin/magento cron:run | grep -v "Ran jobs by schedule" >> /path/to/magento/var/log/magento.cron.log

📄 Changelog

v1.0.0 – Initial Release

OAuth 2.0 integration with USPS REST API v3
Real-time rate retrieval
Sandbox & production support
Comprehensive logging and error handling

📧 Support

For help, feature requests, or integration guidance:

Email: support@toweringmedia.com
Website: https://toweringmedia.com