How to Integrate UPS API with V0

Go to developer.ups.com and sign in with your UPS.com account (or create one). Navigate to Apps → Create App. Fill in the app name, description, and contact details. Select the API products you need: Rating, Tracking, and Address Validation are the most commonly needed for e-commerce apps. After creating the app, you receive a Client ID and Client Secret. Copy these immediately — the client secret is only shown once and you will need to regenerate it if lost. These credentials authenticate your app with UPS's OAuth2 token endpoint. UPS offers two environments: a test environment (CIE — Customer Integration Environment) and production. For development, use the CIE environment credentials. Production credentials are granted after UPS approves your app for live use. The CIE test environment uses test tracking numbers and does not generate real shipping labels or charges. If you want to use your company's negotiated UPS shipping rates in the Rating API, you also need to add your UPS Account Number to the developer app. Without an account number, the Rating API returns standard list rates. With your account number, it returns your negotiated discounted rates.

UPS API calls require a valid OAuth2 bearer token obtained from the UPS token endpoint. Create a utility function that handles the token exchange and caches the result to avoid re-authenticating on every request. The UPS OAuth2 client credentials flow works as follows: POST to https://onlinetools.ups.com/security/v1/oauth/token (production) or https://wwwcie.ups.com/security/v1/oauth/token (test) with grant_type=client_credentials in the body. The request uses HTTP Basic Authentication with your client ID as the username and client secret as the password. UPS returns a JSON response with access_token and token_type fields. Create the token caching logic at the module level so it persists across warm serverless function invocations. Cache the token along with its expiry time — UPS tokens expire after a set period (typically 14,400 seconds / 4 hours). Before each API call, check if the cached token is still valid. If it has expired, fetch a new one. Separating the token management into a utility function keeps your main API routes clean and ensures consistent token handling across all UPS API endpoints in your app.

1// lib/ups-auth.ts
2interface UPSToken {
3  accessToken: string;
4  expiresAt: number;
5}
6
7let cachedToken: UPSToken | null = null;
8
9export async function getUPSAccessToken(): Promise<string> {
10  // Return cached token if still valid (with 60 second buffer)
11  if (cachedToken && cachedToken.expiresAt > Date.now() + 60000) {
12    return cachedToken.accessToken;
13  }
14
15  const clientId = process.env.UPS_CLIENT_ID;
16  const clientSecret = process.env.UPS_CLIENT_SECRET;
17  const baseUrl = process.env.UPS_ENVIRONMENT === 'production'
18    ? 'https://onlinetools.ups.com'
19    : 'https://wwwcie.ups.com';
20
21  if (!clientId || !clientSecret) {
22    throw new Error('UPS_CLIENT_ID and UPS_CLIENT_SECRET must be set');
23  }
24
25  const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
26
27  const response = await fetch(`${baseUrl}/security/v1/oauth/token`, {
28    method: 'POST',
29    headers: {
30      Authorization: `Basic ${credentials}`,
31      'Content-Type': 'application/x-www-form-urlencoded',
32    },
33    body: 'grant_type=client_credentials',
34  });
35
36  if (!response.ok) {
37    const error = await response.text();
38    throw new Error(`UPS auth failed: ${error}`);
39  }
40
41  const data = await response.json();
42  cachedToken = {
43    accessToken: data.access_token,
44    expiresAt: Date.now() + (data.expires_in * 1000),
45  };
46
47  return cachedToken.accessToken;
48}

Create app/api/ups/rates/route.ts to fetch shipping rates. The UPS Rating API accepts origin and destination ZIP codes, package weight and dimensions, and optional services to quote. It returns available UPS services with rates. The UPS Rating API endpoint for fetching multiple service rates is at /api/rating/v2205/Rate (or the current version path — check the UPS API catalog). The request body is a JSON structure with Shipment details including Shipper address, Ship To address, and Package details. The Rating Code 'Shop' returns rates for all available services in a single call — this is more efficient than calling the Rate endpoint once per service. UPS rate responses include service names, service codes, and monetary amounts in both base rate and total with surcharges. Map UPS service codes to human-readable names in your UI: 03 = UPS Ground, 12 = UPS 3 Day Select, 02 = UPS 2nd Day Air, 01 = UPS Next Day Air Saver, 01 = UPS Next Day Air. The Guaranteed flag indicates services with guaranteed delivery dates.

1import { NextRequest, NextResponse } from 'next/server';
2import { getUPSAccessToken } from '@/lib/ups-auth';
3
4const UPS_SERVICE_NAMES: Record<string, string> = {
5  '03': 'UPS Ground',
6  '12': 'UPS 3 Day Select',
7  '02': 'UPS 2nd Day Air',
8  '59': 'UPS 2nd Day Air A.M.',
9  '13': 'UPS Next Day Air Saver',
10  '01': 'UPS Next Day Air',
11};
12
13export async function GET(request: NextRequest) {
14  const { searchParams } = new URL(request.url);
15  const originZip = searchParams.get('originZip') || process.env.UPS_ORIGIN_ZIP;
16  const destZip = searchParams.get('destZip');
17  const weight = searchParams.get('weight') || '1';
18
19  if (!destZip) {
20    return NextResponse.json({ error: 'destZip is required' }, { status: 400 });
21  }
22
23  const baseUrl = process.env.UPS_ENVIRONMENT === 'production'
24    ? 'https://onlinetools.ups.com'
25    : 'https://wwwcie.ups.com';
26
27  try {
28    const accessToken = await getUPSAccessToken();
29
30    const response = await fetch(`${baseUrl}/api/rating/v2205/Shop`, {
31      method: 'POST',
32      headers: {
33        Authorization: `Bearer ${accessToken}`,
34        'Content-Type': 'application/json',
35        transId: `rate-${Date.now()}`,
36        transactionSrc: 'MyApp',
37      },
38      body: JSON.stringify({
39        RateRequest: {
40          Shipment: {
41            Shipper: {
42              Address: { PostalCode: originZip, CountryCode: 'US' },
43            },
44            ShipTo: {
45              Address: { PostalCode: destZip, CountryCode: 'US' },
46            },
47            Package: {
48              PackagingType: { Code: '02' },
49              PackageWeight: { UnitOfMeasurement: { Code: 'LBS' }, Weight: weight },
50            },
51          },
52        },
53      }),
54    });
55
56    if (!response.ok) {
57      const error = await response.json();
58      return NextResponse.json(
59        { error: error.response?.errors?.[0]?.message || 'UPS rating failed' },
60        { status: response.status }
61      );
62    }
63
64    const data = await response.json();
65    const rates = data.RateResponse?.RatedShipment?.map((s: any) => ({
66      service: UPS_SERVICE_NAMES[s.Service?.Code] || `UPS Service ${s.Service?.Code}`,
67      serviceCode: s.Service?.Code,
68      totalCharge: s.TotalCharges?.MonetaryValue,
69      currency: s.TotalCharges?.CurrencyCode,
70      estimatedDays: s.GuaranteedDelivery?.BusinessDaysInTransit,
71    })) || [];
72
73    return NextResponse.json({ rates });
74  } catch (error) {
75    console.error('UPS Rating error:', error);
76    return NextResponse.json({ error: 'Failed to fetch shipping rates' }, { status: 500 });
77  }
78}

Add your UPS credentials to Vercel Dashboard → Settings → Environment Variables. You need: UPS_CLIENT_ID, UPS_CLIENT_SECRET, UPS_ENVIRONMENT (set to 'test' for CIE or 'production' for live), and optionally UPS_ORIGIN_ZIP for your business shipping origin. For Preview and Development environments, use your CIE test credentials and set UPS_ENVIRONMENT=test. For Production, use your production UPS credentials after your app has been approved for live use. Keeping test credentials in non-production environments prevents accidentally generating real UPS labels or incurring charges during development. After adding variables and redeploying, test the shipping rate calculator by entering a destination ZIP code. For CIE testing, use ZIP code 10001 (New York) as a destination. For package tracking, use UPS test tracking number 1Z999AA10123456784 which always returns a test tracking response in the CIE environment. If you need to add the UPS Tracking API route alongside the Rating route, it follows the same OAuth2 pattern — call getUPSAccessToken(), then POST to the UPS Tracking endpoint at /api/track/v1/details/{trackingNumber}. The tracking response includes activity array with date, time, location, description, and status for each checkpoint.