ClickCease

Magento 2 USPS OAuth Shipping Extension User Guide

This comprehensive guide will help you install, configure, and use the ToweringMedia USPS OAuth Shipping Extension for Magento 2. This extension integrates with the USPS OAuth REST API v3 to provide real-time shipping rates at checkout.

Table of Contents

Overview

The Magento 2 USPS shipping extension provides a modern, secure way to display real-time USPS shipping rates in your Magento 2 store. Unlike legacy USPS modules that use outdated username/password authentication, this extension uses the official USPS OAuth REST API with OAuth 2.0 client credentials authentication.

Key Features

  • Real-time USPS rates - Get live shipping quotes directly from USPS API
  • USPS OAuth authentication - Secure, modern authentication method
  • USPS REST API v3 - Uses the latest USPS Domestic Prices API
  • Intelligent rate filtering - Shows best shipping options to customers
  • Admin testing tools - Test connections and rates from Magento Admin
  • API quota protection - Integrated with Shipping Guard to prevent quota exhaustion
  • Comprehensive logging - Detailed logs for troubleshooting without exposing secrets

System Requirements

Magento Version

  • Magento 2.4.x (Magento 2.4.7, Magento 2.4.8, and other 2.4.x versions)
  • Compatible with both Magento Open Source and Adobe Commerce

PHP Requirements

  • PHP 8.1 or higher (PHP 8.2 recommended)

Database Requirements

  • MySQL 8.0 or higher (MySQL 8.4 recommended)

Search Engine

  • OpenSearch (recommended for Magento 2.4.8+)
  • Elasticsearch (for older Magento 2.4.x versions)

USPS API Credentials

  • USPS API Client ID
  • USPS API Client Secret
  • Active USPS API account with access to Domestic Prices v3 API

Composer

  • Composer package manager installed and configured
  • Access to composer.toweringmedia.com repository

Installation

Step 1: Get Your License

Purchase the Magento 2 USPS OAuth Shipping Extension from ToweringMedia. After purchase and invoicing, you'll receive:

  • Composer authentication credentials (public key and private key)
  • Access to the extension package

Step 2: Configure Composer Authentication

Add your credentials to your Magento installation:

  1. Create or edit auth.json in your Magento root directory
  2. Add the following configuration:
{
    "http-basic": {
        "composer.toweringmedia.com": {
            "username": "YOUR_PUBLIC_KEY",
            "password": "YOUR_PRIVATE_KEY"
        }
    }
}

Step 3: Add Composer Repository

Add the ToweringMedia repository to your composer.json:

composer config repositories.toweringmedia composer https://composer.toweringmedia.com

Step 4: Install the Extension

Install the USPS extension using Composer:

composer require toweringmedia/magento-2-usps-rest-api

This will automatically install the extension and its dependencies, including:

  • toweringmedia/base - Base module
  • toweringmedia/module-shipping-guard - API quota protection

Step 5: Enable and Configure Magento

  1. Enable the module:
php bin/magento module:enable Toweringmedia_USPSRestApi
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

Configuration

Accessing the Configuration

  1. Log in to Magento Admin
  2. Navigate to Stores → Configuration → Sales → Shipping Methods → USPS OAuth

Basic Configuration

1. Enable USPS OAuth

  • Enabled: Set to "Yes" to enable the shipping method

2. USPS API Credentials

  • Client ID: Enter your USPS API Client ID
  • Client Secret: Enter your USPS API Client Secret
  • Sandbox Mode: Enable for testing (uses USPS sandbox environment)

3. Shipping Origin

  • Configure your shipping origin address in Stores → Configuration → General → General → Country Options
  • The extension uses this address as the shipping origin for rate calculations

4. Allowed Shipping Methods

Select which USPS shipping methods to offer to customers:

  • Priority Mail Express
  • Priority Mail
  • USPS Ground Advantage
  • First-Class Mail
  • Media Mail
  • Parcel Select Ground

5. Rate Filtering

  • Show Cheapest Per Class: Display the cheapest option for each service class
  • Max Rates to Show: Limit the number of rates displayed (default: 10)

6. Handling Fee

  • Add a handling fee (fixed amount or percentage) to shipping rates if needed

Advanced Configuration

API Quota Protection

The extension includes built-in API quota protection via the Shipping Guard module:

  • Prevents API quota exhaustion during high-traffic periods
  • Session-based caching to reduce API calls
  • Automatic rate limiting

Logging

Enable detailed logging for troubleshooting:

  • Logs are written to var/log/usps_oauth.log
  • Sensitive credentials are automatically redacted from logs
  • Logs include API requests, responses, and error messages

Testing

Test Connection

Use the built-in test tools to verify your configuration:

  1. Navigate to Stores → Configuration → Sales → Shipping Methods → USPS OAuth
  2. Click the "Test Connection" button
  3. The system will verify your credentials and API connection

Test Rate Calculation

  1. In the same configuration page, click the "Test Rate" button
  2. Enter test shipping details (weight, dimensions, destination)
  3. The system will fetch sample rates from USPS API

Test in Checkout

  1. Add a product to cart
  2. Proceed to checkout
  3. Enter a shipping address
  4. Verify that USPS shipping rates appear correctly

Troubleshooting

No Shipping Rates Showing

  • Verify your USPS API credentials are correct
  • Check that "Enabled" is set to "Yes"
  • Verify your shipping origin address is configured
  • Check that at least one shipping method is enabled
  • Review logs in var/log/usps_oauth.log

Authentication Errors

  • Verify your Client ID and Client Secret are correct
  • Check that your USPS API account is active
  • Ensure you have access to the Domestic Prices v3 API
  • If using sandbox mode, verify you're using sandbox credentials

API Quota Exhausted

  • The Shipping Guard module should prevent this, but if it occurs:
  • Check your API usage in the USPS developer portal
  • Review the rate filtering settings to reduce API calls
  • Consider increasing the cache TTL

Rates Seem Incorrect

  • Verify package weight and dimensions are set correctly on products
  • Check that the shipping origin address is accurate
  • Verify you're using the correct USPS API environment (sandbox vs production)
  • Review the allowed shipping methods configuration

Check Logs

Detailed error information is available in:

var/log/usps_oauth.log

Logs include:

  • API request/response details
  • Authentication status
  • Error messages
  • Rate calculation details

Frequently Asked Questions

What is USPS OAuth?

USPS OAuth is the modern authentication method required by USPS for accessing their REST API. It uses OAuth 2.0 client credentials instead of the legacy username/password method.

Do I need a USPS account?

Yes, you need an active USPS API account with access to the Domestic Prices v3 API. You can sign up at the USPS Developer Portal.

Is this compatible with Magento 2.4.8?

Yes, the extension is fully compatible with Magento 2.4.8, as well as other Magento 2.4.x versions.

Can I use this with Elasticsearch?

Yes, the extension works with both OpenSearch (recommended for Magento 2.4.8+) and Elasticsearch (for older versions).

What shipping methods are supported?

The extension supports all major USPS shipping methods including Priority Mail Express, Priority Mail, USPS Ground Advantage, First-Class Mail, Media Mail, and Parcel Select Ground.

How does rate filtering work?

The extension intelligently filters rates to show customers the best options:

  • Shows the cheapest option for each service class
  • Displays up to 10 rates sorted by price
  • Eliminates duplicate or redundant options

What is Shipping Guard?

Shipping Guard is a dependency that protects against API quota exhaustion. It implements session-based caching and rate limiting to prevent excessive API calls during high-traffic periods.

Can I test in sandbox mode?

Yes, the extension includes sandbox mode support. Enable it in the configuration to test with USPS sandbox credentials before going live.

Where can I get support?

For technical support, please contact ToweringMedia support or refer to the extension documentation.

Additional Resources