UPSv3 REST Shipping Rates

Overview

Jscriptz UPSv3 is a modern UPS shipping integration module for Magento 2 that uses UPS's latest REST APIs with OAuth2 authentication. It provides real-time shipping rates, delivery date estimates, and address validation capabilities.

Requirements

• Magento 2.4.x
• PHP 8.1 or higher
• UPS Developer Account with API credentials
• UPS Account Number (shipper number)

Features

Installation

Prerequisites

• Magento 2.4.4 or higher
• PHP 8.1 or higher
• Composer 2.x
• Valid Jscriptz license (purchased from mage.jscriptz.com)

Step 1: Get Your Composer Access Token

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

Step 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 with your license key from My Licenses page, and YOUR_ACCESS_TOKEN with the token from Step 1.

Step 3: Install via Composer

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

# Install UPSv3 (includes ShippingCore dependency)
composer require jscriptz/module-upsv3

Step 4: Run Magento Setup

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

# 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

Step 5: Activate Your License

After installation, activate your license in the Magento admin:

UPS Developer Portal Setup

Before configuring the module in Magento, you need to set up your application on the UPS Developer Portal to obtain API credentials.

Step 1: Create a UPS Developer Account

Step 2: Create an Application

Navigate to My Apps

Click "My Apps" in the top navigation bar.

My Apps page in UPS Developer Portal

Create New App

Click "Add Apps" or "Create New App" button. Enter a name for your application (e.g., "Magento Store Integration").

Select Billing Account

Choose your UPS account number that will be used for billing and shipments.

Add the Rating API

In the "Add Products" section, search for "Rating" and enable it. This is required for getting shipping rates.

Step 3: Add Additional APIs

After creating your app, you can add more APIs for enhanced functionality:

Click Edit App

From your app details page, click the "Edit App" button.

App details showing credentials and current APIs

Search for Time in Transit

In the "Add Products" panel, search for "Time in Transit" and toggle it on.

Adding Time in Transit API to your application

Search for Address Validation

Search for "Address Validation" and toggle it on for address verification capabilities.

Adding Address Validation API

Save Your Changes

Click "Save" to submit your changes. APIs are typically approved instantly.

All APIs approved and ready to use

Magento Configuration

Navigate to Stores > Configuration > Sales > Shipping Methods > UPS V2 to configure the module.

General Settings

API Credentials

Shipping Options

Time in Transit Settings

Per-Service Cutoff Times

Configure different cutoff times for different UPS services. Express services typically have later cutoffs than Ground services.

Per-Service Cutoff JSON Format

The JSON maps UPS service codes to their cutoff hour in 24-hour format:

{
    "03": 14,  // Ground - 2:00 PM
    "12": 14,  // 3 Day Select - 2:00 PM
    "02": 16,  // 2nd Day Air - 4:00 PM
    "59": 16,  // 2nd Day Air A.M. - 4:00 PM
    "01": 17,  // Next Day Air - 5:00 PM
    "13": 17,  // Next Day Air Saver - 5:00 PM
    "14": 10   // Next Day Air Early - 10:00 AM
}

Rate Caching

Label Generation

UPSv3 provides full label generation capabilities directly from the Magento admin. Create shipping labels, view/download them, and void shipments when needed.

Creating Shipping Labels

After an order is shipped, you can create UPS shipping labels from the shipment view page in admin.

Label Configuration

Canceling/Voiding Labels

If you need to void a shipment (e.g., order cancelled, wrong address), you can cancel it directly from admin.

Webhook Tracking

UPSv3 supports real-time tracking updates via UPS Track Alert webhooks. When enabled, UPS sends tracking events directly to your Magento store as they happen—no polling required.

Webhook Setup

UPS Developer Portal Requirements

Before enabling webhooks, add the Track Alert API to your UPS application:

1. Go to developer.ups.com
2. Navigate to My Apps and edit your application
3. Search for "Track Alert" in Add Products
4. Enable the API and save your changes

Magento Configuration

Navigate to Stores > Configuration > Jscriptz > Jscriptz UPSv3 > Webhook Tracking

Register Webhook

After enabling webhook tracking, use the Register Webhook button in the configuration to set up the webhook with UPS. The status will show:

• Registered - Webhook is active and receiving events
• Not Configured - Click Register to set up
• Per-Shipment - Webhooks registered automatically per tracking number

Tracking Events

The following tracking event types are captured and stored:

Admin Tracking History

View complete tracking history in admin by navigating to Sales > Shipments and viewing a UPS shipment. The "UPS Tracking History" section shows all events with timestamps and locations.

Customer Tracking View

Customers can view their tracking history on the frontend order shipment page. The tracking timeline displays all events with:

• Current delivery status with visual indicator
• Full event timeline with timestamps
• Location information for each scan
• Direct link to track on UPS.com
• Proof of delivery photo (when available)
• Signature confirmation (when captured)

Webhook Simulator (Sandbox Testing)

Test your UPS webhook integration without creating real shipments. The webhook simulator lets you send mock tracking events to verify your setup is working correctly before going live.

Requirements

• Environment: Set to Sandbox (Stores > Configuration > Jscriptz > Jscriptz UPSv3 > General > Environment)
• Webhook Tracking: Enabled (Webhook Tracking > Enable Webhook Tracking = Yes)
• Simulator Enabled: Yes (Stores > Configuration > Jscriptz > Shipping Preferences > Webhook Testing)

Accessing the Simulator

1. Navigate to Stores > Configuration > Jscriptz > Shipping Preferences
2. Expand the Webhook Testing (Sandbox) section
3. Ensure "Enable Webhook Simulator" is set to Yes
4. Select UPS from the Carrier dropdown

Available Event Types

Running a Simulation

Testing with Real Shipment Data

For the most realistic testing:

1. Go to Sales > Shipments and find a UPS shipment
2. Copy the UPS tracking number
3. Paste it into the simulator's tracking number field
4. Simulate events like "In Transit" or "Delivered"
5. View the shipment to see tracking events appear in history

UPS Service Codes

The following UPS services are supported by this module:

Troubleshooting

No Shipping Rates Displayed

• Verify API credentials are correct
• Check that the carrier is enabled (active = Yes)
• Ensure environment matches your credentials (Sandbox vs Production)
• Check var/log/jscriptz_upsv3.log for API errors
• Verify shipping origin is configured in Magento (Stores > Configuration > Sales > Shipping Settings > Origin)

Authentication Errors (401)

• Verify Client ID and Client Secret are correct
• Check that the API is approved in your UPS Developer Portal app
• Clear Magento cache: bin/magento cache:clean

Time in Transit Not Showing

• Ensure transit_enabled is set to Yes
• Verify "Time In Transit" API is added and approved in UPS Developer Portal
• Check that pickup days and cutoff time are configured

Label Generation Issues

• Ensure "Shipping" API is enabled in your UPS Developer Portal app
• Verify shipper address is complete and valid
• Check that package weight doesn't exceed service limits
• For void errors, verify the label hasn't been scanned by UPS yet

Webhook Not Receiving Events

• Verify "Track Alert" API is enabled in UPS Developer Portal
• Check that your store URL is accessible from the internet (not localhost)
• Ensure SSL certificate is valid (UPS requires HTTPS)
• Check var/log/jscriptz_upsv3.log for webhook errors
• For per-shipment webhooks, tracking is only received for labels created after enabling

Debug Mode

Enable debug mode to log all API requests and responses:

bin/magento config:set carriers/upsv3/debug 1
bin/magento cache:clean config

Logs are written to: var/log/jscriptz_upsv3.log

API Reference

This module uses the following UPS REST API endpoints:

Useful Commands

# Check current configuration
bin/magento config:show carriers/upsv3

# Enable the carrier
bin/magento config:set carriers/upsv3/active 1

# Switch to production
bin/magento config:set carriers/upsv3/environment production

# Clear cache after changes
bin/magento cache:clean config

ShippingCore Integration

UPSv3 integrates with the Jscriptz_ShippingCore companion module to provide enhanced admin and checkout features.

Enhanced Shipments Grid

ShippingCore extends the Sales > Shipments grid with additional columns and mass actions:

Additional Columns

Mass Actions

• Send Tracking Info: Bulk send tracking emails to customers
• Create Shipping Label: Generate labels for multiple shipments
  • Combined PDF: All labels in a single file
  • ZIP of Separate PDFs: Individual label files
• Create Label + Send Tracking: Combined workflow for efficiency

Checkout Features

• Carrier Logos: Official UPS logo at checkout instead of text
• Transit Badges: "Fastest" and "Best Value" badges on shipping methods
• Cutoff Countdown: "Order within X hours" timer
• Delivery Preferences: Signature and location options
• Dark Mode Support: Automatic adaptation to user preferences

For complete documentation, see the ShippingCore User Guide.