USPSv3 REST Shipping Rates

1. Overview

Jscriptz USPSv3 is a modern USPS shipping integration for Magento 2 that uses the new USPS REST APIs with OAuth2 authentication. This module provides real-time shipping rates, transit time information, and address validation capabilities using USPS's Shipping Options API.

2. Features

• OAuth2 Authentication: Secure token-based authentication with automatic token refresh
• Real-Time Shipping Rates: Get accurate, up-to-date rates from USPS
• Transit Time Information: Show estimated delivery dates with shipping methods
• Single API Call: Shipping Options API returns rates AND transit times together
• Rate Caching: Cache rates to reduce API calls and improve performance
• Fallback Support: Return cached rates if USPS API is temporarily unavailable
• Sandbox Mode: Test your integration before going live
• Address Validation: Validate and correct shipping addresses (optional)
• Multiple Price Types: Support for Retail, Commercial, and Commercial Plus pricing
• Handling Fees: Add a flat handling fee to all shipping rates
• Free Shipping Threshold: Offer free shipping above a cart subtotal
• Debug Logging: Detailed logging for troubleshooting

3. Requirements

• Magento 2.4.x
• PHP 8.1 or higher
• USPS Web Tools Account (free)
• USPS Developer Portal Account (free)

4. Installation

1 Get Your Composer Access Token

After purchasing the extension, log in to your Jscriptz account to get your Composer authentication token:

1. Go to mage.jscriptz.com/customer/account
2. Click on GitHub Access in the left sidebar
3. Click Generate New Token if you don't have one
4. Copy your access token (it will look like a long string of characters)

2 Configure Composer Authentication

Create or update your auth.json file in your Magento root directory:

{
    "http-basic": {
        "packages.jscriptz.com": {
            "username": "YOUR_LICENSE_KEY",
            "password": "YOUR_ACCESS_TOKEN"
        }
    }
}

Replace:

• YOUR_LICENSE_KEY - Your license key from My Licenses page
• YOUR_ACCESS_TOKEN - The token you copied in Step 1

3 Add Repository & Install Package

Add the Jscriptz package repository and install the module:

# Add the Jscriptz repository (first time only)
composer config repositories.jscriptz composer https://packages.jscriptz.com

# Install USPSv3 (includes ShippingCore dependency)
composer require jscriptz/module-uspsv3

4 Run Magento Setup

# Enable the modules
bin/magento module:enable Jscriptz_ShippingCore Jscriptz_USPSv3

# Run setup upgrade
bin/magento setup:upgrade

# Compile DI (production mode)
bin/magento setup:di:compile

# Deploy static content (production mode)
bin/magento setup:static-content:deploy -f

# Clear cache
bin/magento cache:flush

5 Activate Your License

After installation, you need to activate your license in the Magento admin:

1. Go to Stores → Configuration → Sales → Shipping Methods → Jscriptz USPSv3
2. Expand the License section
3. Enter your License Key from your Jscriptz License Account
4. Click Save Config
5. Click Verify License to confirm your license is active

5. USPS Developer Portal Setup

Before configuring the module in Magento, you need to create an API project in the USPS Developer Portal to obtain your API credentials.

1 Create a USPS Developer Account

Visit developers.usps.com and create a free developer account if you don't already have one.

2 Register for API Access

Complete the registration process to get access to the USPS APIs. You'll need to provide basic business information.

3 Follow the Getting Started Steps

After registering, USPS provides a guided setup process to help you create your API credentials.

4 Select Required APIs

When creating your API project, select the following APIs:

• Shipping Options API (v3) - Required for shipping rates and transit times
• Addresses API (v3) - Optional, for address validation

5 Retrieve Your API Credentials

After your project is created, you'll receive your API credentials. You'll need:

• Consumer Key (also called Client ID)
• Consumer Secret (also called Client Secret)

API Endpoints

6. Magento Configuration

Configure the module in the Magento Admin at:

Stores > Configuration > Jscriptz > Jscriptz USPSv3

General Settings

API Credentials

Shipping Options

Rate Caching

Address Validation

Shipping Restrictions

Developer Settings

7. Testing

Sandbox Testing

1. Set Environment to Sandbox
2. Enter your sandbox credentials from the USPS Developer Portal
3. Add a product to cart and proceed to checkout
4. Enter a valid US shipping address
5. USPS shipping methods should appear with rates

Debug Mode

Enable Debug Mode to log detailed API information:

1. Set Debug Mode to Yes
2. View logs at var/log/uspsv3.log
3. Look for entries prefixed with [USPSv3]

# View USPSv3 debug logs
tail -f var/log/uspsv3.log

Production Testing

1. Switch to Production environment
2. Enter your Production credentials
3. Clear Magento cache
4. Test checkout with real shipping addresses
5. Verify rates match USPS published rates for your price type

8. Supported Services

Domestic Services (US)

International Services

Price Types

Weight Limits

9. Troubleshooting

No Shipping Methods Displayed

1. Verify the module is enabled in configuration
2. Check that API credentials are entered correctly
3. Ensure origin address is configured in Shipping Settings
4. Enable Debug Mode and check uspsv3.log for errors
5. Verify the destination country is allowed
6. Check that allowed methods are configured (or leave empty for all)

Authentication Errors

Solution:

• Re-enter credentials through the Magento Admin (not CLI)
• Verify you're using the correct environment (Sandbox vs Production)
• Check that your USPS Developer account is active
• Ensure you're using the correct API endpoints for your environment

Empty Shipping Options Response

Solution:

• Verify the package weight doesn't exceed 70 lbs
• Check that origin and destination are valid US ZIP codes
• Ensure the API response structure matches expected format
• Check if specific mail classes are restricted for your route

Caching Issues

If rates seem outdated:

1. Clear Magento cache: bin/magento cache:flush
2. Reduce Cache TTL in configuration
3. Temporarily disable caching for testing

Missing Transit Times

Transit times come from the USPS Shipping Options API response. If not displayed:

• Enable Debug Mode and check if transit data is in the response
• Look for commitment.scheduleDeliveryDate in the API response
• Ensure the Jscriptz_Checkout module is installed (for transit time display)

Business Customer Gateway Errors

10. FAQ

Can I use this alongside Magento's built-in USPS module?

Yes, Jscriptz USPSv3 uses the carrier code uspsv3 and operates independently of Magento's core USPS module (usps). You can run both simultaneously, though we recommend disabling the core module to avoid customer confusion.

Do I need a USPS business account?

No! Unlike UPS and FedEx, USPS does not require an account number to use their APIs. You only need API credentials from the Developer Portal. However, for Commercial or Commercial Plus pricing, you may need a business relationship with USPS.

What's the difference between Retail and Commercial pricing?

Retail is standard pricing available to everyone. Commercial pricing offers discounts for businesses that ship regularly. Commercial Plus provides additional discounts for high-volume shippers. Most stores start with Retail pricing.

Why use the Shipping Options API instead of separate Rate and Transit APIs?

The Shipping Options API (v3) returns both pricing AND transit times in a single API call, reducing latency and improving checkout performance. This is more efficient than the older approach of making separate calls for rates and delivery estimates.

How often should I refresh cached rates?

The default TTL of 3600 seconds (1 hour) works well for most stores. USPS rates don't change as frequently as carrier rates, so caching is very effective. For high-traffic stores, keep caching enabled to reduce API calls.

Can I offer free shipping for USPS methods?

Yes, set a Free Shipping Threshold amount. When the cart subtotal exceeds this amount, all USPS rates will show as $0.00.

What's the maximum package weight for USPS?

Most USPS services support packages up to 70 lbs. This is lower than UPS and FedEx (150 lbs). First-Class Package is limited to 13 oz.

Why does USPS Ground Advantage show instead of First-Class or Priority Mail?

USPS Ground Advantage replaced several services in 2023, including First-Class Package Service, Parcel Select Ground, and Retail Ground. It's now the primary ground shipping option for packages up to 70 lbs.

Are international shipments supported?

Yes, the module supports international USPS services including Priority Mail International, Priority Mail Express International, First-Class Package International, and Global Express Guaranteed.

11. ShippingCore Integration

USPSv3 works seamlessly with the Jscriptz_ShippingCore module, which provides enhanced shipment management features in the Magento admin.

Enhanced Shipments Grid

When ShippingCore is installed, the Sales > Shipments grid is enhanced with additional columns and mass actions:

Additional Columns

Mass Actions

Process multiple shipments at once with these mass actions:

• Send Tracking Info - Send tracking notification emails to customers
• Create Shipping Label - Generate labels via carrier API
  • Combined PDF (single file with all labels)
  • ZIP of Separate PDFs (individual files)
• Create Label + Send Tracking - Combined workflow to create labels and send notifications
  • Combined PDF (single file with all labels)
  • ZIP of Separate PDFs (individual files)

Related Documentation

• ShippingCore User Guide - Complete documentation for shipments grid, delivery preferences, and automation features