UPS Shipping API Integration: Developer Guide

Integrating with the UPS API allows your application to programmatically create shipments, generate labels, track packages, validate addresses, and access the full range of UPS services. This developer guide walks through every aspect of the UPS API integration process, from authentication to production deployment, with practical code examples and best practices.

UPS API Overview

UPS offers a comprehensive suite of RESTful APIs through the UPS Developer Kit. In 2024, UPS completed a major migration from their legacy XML-based APIs to modern OAuth 2.0 REST APIs. All new integrations should use the REST APIs.

Available APIs

API Environments

Authentication: OAuth 2.0

All UPS REST APIs use OAuth 2.0 client credentials flow for authentication.

Step 1: Create a UPS Developer Account

Go to https://developer.ups.com

Register for a developer account

Create a new application

Note your Client ID and Client Secret

Step 2: Obtain an Access Token

Request an access token from the OAuth endpoint:

POST https://onlinetools.ups.com/security/v1/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic {base64(clientId:clientSecret)}
grant_type=client_credentials

Response:

{
  "token_type": "Bearer",
  "issued_at": "1706803200000",
  "client_id": "your_client_id",
  "access_token": "eyJhbGciOi...",
  "expires_in": "14399",
  "status": "approved"
}

Step 3: Use the Token in API Calls

Include the access token in the Authorization header of all subsequent API calls:

Authorization: Bearer eyJhbGciOi...

Token Management Best Practices

Rating API: Getting Shipping Rates

The Rating API is typically the first API you integrate because it allows you to display shipping costs to customers.

Basic Rate Request

POST /api/rating/v2403/rate
Authorization: Bearer {token}
Content-Type: application/json
transId: {unique-transaction-id}
{
  "RateRequest": {
    "Request": {
      "SubVersion": "2403",
      "TransactionReference": {
        "CustomerContext": "order-12345"
      }
    },
    "Shipment": {
      "Shipper": {
        "Name": "Your Business Name",
        "ShipperNumber": "YOUR_ACCOUNT",
        "Address": {
          "AddressLine": ["123 Main St"],
          "City": "New York",
          "StateProvinceCode": "NY",
          "PostalCode": "10001",
          "CountryCode": "US"
        }
      },
      "ShipTo": {
        "Name": "Customer Name",
        "Address": {
          "AddressLine": ["456 Oak Ave"],
          "City": "Los Angeles",
          "StateProvinceCode": "CA",
          "PostalCode": "90001",
          "CountryCode": "US"
        }
      },
      "ShipFrom": {
        "Name": "Your Warehouse",
        "Address": {
          "AddressLine": ["123 Main St"],
          "City": "New York",
          "StateProvinceCode": "NY",
          "PostalCode": "10001",
          "CountryCode": "US"
        }
      },
      "Package": [
        {
          "PackagingType": {
            "Code": "02",
            "Description": "Customer Supplied Package"
          },
          "Dimensions": {
            "UnitOfMeasurement": { "Code": "IN" },
            "Length": "12",
            "Width": "10",
            "Height": "8"
          },
          "PackageWeight": {
            "UnitOfMeasurement": { "Code": "LBS" },
            "Weight": "5"
          }
        }
      ]
    }
  }
}

Rate Response Key Fields

UPS Service Codes Reference

Shop Rates (Compare All Services)

To get rates for all available services in one call, use the "Shop" request option:

{
  "RateRequest": {
    "Request": {
      "RequestOption": "Shop"
    },
    "Shipment": { ... }
  }
}

This returns an array of RatedShipment objects, one for each available service, sorted by cost.

Shipping API: Creating Labels

Once a customer selects a service and confirms their order, use the Shipping API to create the shipment and generate a label.

Create Shipment Request

POST /api/shipments/v2409/ship
Authorization: Bearer {token}
Content-Type: application/json
{
  "ShipmentRequest": {
    "Request": {
      "SubVersion": "2409",
      "TransactionReference": {
        "CustomerContext": "order-12345"
      }
    },
    "Shipment": {
      "Shipper": {
        "Name": "Your Business",
        "AttentionName": "Shipping Dept",
        "ShipperNumber": "YOUR_ACCOUNT",
        "Phone": { "Number": "2125551234" },
        "Address": {
          "AddressLine": ["123 Main St"],
          "City": "New York",
          "StateProvinceCode": "NY",
          "PostalCode": "10001",
          "CountryCode": "US"
        }
      },
      "ShipTo": {
        "Name": "John Customer",
        "Phone": { "Number": "3105559876" },
        "Address": {
          "AddressLine": ["456 Oak Ave"],
          "City": "Los Angeles",
          "StateProvinceCode": "CA",
          "PostalCode": "90001",
          "CountryCode": "US"
        }
      },
      "PaymentInformation": {
        "ShipmentCharge": [{
          "Type": "01",
          "BillShipper": {
            "AccountNumber": "YOUR_ACCOUNT"
          }
        }]
      },
      "Service": {
        "Code": "03",
        "Description": "UPS Ground"
      },
      "Package": [{
        "Packaging": {
          "Code": "02"
        },
        "Dimensions": {
          "UnitOfMeasurement": { "Code": "IN" },
          "Length": "12",
          "Width": "10",
          "Height": "8"
        },
        "PackageWeight": {
          "UnitOfMeasurement": { "Code": "LBS" },
          "Weight": "5"
        }
      }]
    },
    "LabelSpecification": {
      "LabelImageFormat": {
        "Code": "ZPL"
      },
      "LabelStockSize": {
        "Height": "6",
        "Width": "4"
      }
    }
  }
}

Label Format Options

Response: Tracking Number and Label

The response contains:

Tracking API: Package Status

Single Package Tracking

GET /api/track/v1/details/{trackingNumber}
Authorization: Bearer {token}
transId: {unique-id}
transactionSrc: your-app-name

Tracking Response Key Fields

Common Status Codes

Address Validation API

Validating addresses before creating shipments prevents failed deliveries and costly address corrections.

Validation Request

POST /api/addressvalidation/v2/validate
Authorization: Bearer {token}
Content-Type: application/json
{
  "XAVRequest": {
    "AddressKeyFormat": {
      "AddressLine": ["456 Oak Avenue"],
      "PoliticalDivision2": "Los Angeles",
      "PoliticalDivision1": "CA",
      "PostcodePrimaryLow": "90001",
      "CountryCode": "US"
    }
  }
}

Response Classification

Residential Indicator

The Address Validation API also returns whether the address is residential or commercial:

This is valuable for accurate rate quoting — knowing the address type before rating prevents unexpected surcharges.

Error Handling

UPS APIs return structured error responses that you should handle gracefully:

Common Error Codes

Error Handling Best Practices

Rate Limiting and Performance

UPS API Rate Limits

Performance Optimization

Webhook Integration for Real-Time Tracking

Instead of polling the Tracking API, UPS offers webhook notifications (Quantum View) that push tracking events to your server:

Setting Up Webhooks

Contact your UPS account representative to enable Quantum View

Provide your webhook endpoint URL

Configure which events you want to receive

Implement the webhook receiver

Webhook Event Types

Webhook Receiver Implementation

Your webhook endpoint should:

Accept POST requests with JSON payloads

Validate the webhook signature (provided in headers)

Return a 200 status within 10 seconds

Process the event asynchronously (do not block the response)

Handle duplicate events idempotently

Testing in Sandbox

Sandbox Test Credentials

UPS provides a sandbox (Customer Integration Environment, CIE) for testing:

Testing Checklist

Test Tracking Numbers

UPS provides test tracking numbers in the sandbox:

Production Deployment Checklist

Before going live with your UPS API integration:

Conclusion

Integrating with the UPS API opens up powerful shipping capabilities for your application. The modern OAuth 2.0 REST APIs are well-documented, reliable, and performant. Start with the Rating and Address Validation APIs for customer-facing features, add the Shipping API for label generation, and implement webhook-based tracking for real-time visibility. Follow the best practices outlined in this guide — especially around token management, error handling, rate caching, and thorough testing — to build a robust, production-ready integration that scales with your business.