UPS API

Go to developer.ups.com and sign in with your UPS account credentials (or create a new UPS developer account — it is free). Once logged in, click 'My Apps' in the navigation and then 'Create App'. When creating the app, you will be asked to select API products. For a package tracking integration, select 'Track API'. For shipping rate quotes, select 'Rating API'. For address validation, select 'Address Validation API'. You can add multiple products to a single app. Give the app a name like 'Bubble Integration'. After creating the app, you will see your **Client ID** and **Client Secret** in the app detail page. Copy both immediately — the Client Secret may not be shown again in full. Store them in a password manager. IMPORTANT: UPS issues separate credentials for sandbox and production. The app dashboard shows both. Use the sandbox credentials while building — they connect to `wwwcie.ups.com`. Use the production credentials for your live app — they connect to `onlinetools.ups.com`. Do not mix them. Also note which API products you have added. The UPS REST API is modular — you need to explicitly add each product (Tracking, Rating, Address Validation) to your app before you can call it.

1# UPS API base URLs
2Sandbox:    https://wwwcie.ups.com
3Production: https://onlinetools.ups.com
4
5# Token endpoint (same path, different base URL)
6Sandbox:    https://wwwcie.ups.com/security/v1/oauth/token
7Production: https://onlinetools.ups.com/security/v1/oauth/token
8
9# Key API endpoints
10Tracking:   /track/v1/details/{inquiryNumber}
11Rating:     /rating/v2409/Rate
12Address:    /addressvalidation/v1/1

In your Bubble app, go to Settings → App Constants (this may be under Settings → General → App constants in your Bubble version). Add the following constants: - `ups_client_id` — your UPS Client ID (value: visible to all, no Private needed since Client ID is less sensitive) - `ups_client_secret` — your UPS Client Secret (mark this Private) - `ups_base_url` — `https://wwwcie.ups.com` for sandbox; change to `https://onlinetools.ups.com` for production Next, create a Bubble Data Type called 'UPSToken' with these fields: - `access_token` (text) — the Bearer token string returned by the UPS OAuth endpoint - `expiry_time` (date) — the calculated expiry datetime (current time + token TTL in seconds) - `is_active` (yes/no) — a flag you can use to quickly find the current valid token You only ever need one active UPS token record at a time. When you mint a new token, set `is_active` to 'No' on any existing records first, then create a new record with the new token and `is_active` set to 'Yes'. This gives you a simple 'Do a search for UPSToken where is_active is Yes → first item' lookup pattern at the start of each Backend Workflow execution.

1// Bubble App Constants to create:
2// ups_client_id       → "your_client_id_here"
3// ups_client_secret   → "your_client_secret_here" (Private)
4// ups_base_url        → "https://wwwcie.ups.com" (sandbox)
5
6// UPSToken Data Type fields:
7// access_token  (text)
8// expiry_time   (date)
9// is_active     (yes/no)

Go to the Backend Workflows tab in Bubble (visible only on paid plans). Click 'New API Workflow'. Name it 'UPS Get Token'. This workflow will be called internally by other Backend Workflows — it does not need to be exposed as a public API endpoint. Inside the workflow, add these steps: **Step 1 — Check for a valid cached token:** Add a 'Do when condition is true' check: 'Search for UPSToken where is_active is Yes and expiry_time > Current date/time → count > 0'. If a valid token exists, the main tracking/rating workflow can use it directly. Design the parent workflow to check this before calling the token workflow. **Step 2 — Call the UPS token endpoint:** Add an API Connector call. In the API Connector, create a new API group called 'UPS OAuth'. Add a single call: Method POST, URL = `[ups_base_url App Constant]/security/v1/oauth/token`. Set Content-Type to `application/x-www-form-urlencoded` (not JSON — the token endpoint uses form encoding, not a JSON body). In the request body, add: - `grant_type` = `client_credentials` - `client_id` = `[ups_client_id App Constant]` - `client_secret` = `[ups_client_secret App Constant — Private]` **Step 3 — Cache the token:** After the API call, add a workflow action: 'Make changes to all UPSToken' where is_active is Yes → set `is_active` to No. Then 'Create a new UPSToken' with: - `access_token` = the `access_token` field from the API response - `expiry_time` = Current date/time + [token TTL in seconds from the `expires_in` response field] - `is_active` = Yes The UPS token endpoint returns `expires_in` as a number of seconds. If this value varies, store it dynamically; otherwise use a conservative value like 3600 seconds (1 hour) as a cache duration.

1// POST /security/v1/oauth/token — request
2// Content-Type: application/x-www-form-urlencoded
3// Body (form-encoded):
4grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET
5
6// Success response (200)
7{
8  "token_type": "Bearer",
9  "issued_at": "1720483200000",
10  "client_id": "YOUR_CLIENT_ID",
11  "access_token": "eyJraWQiOiJ...",
12  "expires_in": "14399",
13  "status": "approved"
14}
15
16// Cache logic:
17// expiry_time = Current time + (expires_in seconds)
18// If current time < expiry_time → use cached token
19// If current time >= expiry_time → mint new token

Create a second Backend Workflow. Name it 'UPS Track Package'. Add an input parameter: `tracking_number` (text). This is the workflow the frontend will trigger. Inside the workflow: **Step 1 — Get a valid token:** Check if a valid UPSToken record exists (is_active = Yes, expiry_time > Current date/time). If yes, use the cached token. If no, trigger the 'UPS Get Token' Backend Workflow from Step 3 first, wait for it to complete, then fetch the new UPSToken. **Step 2 — Call the UPS Tracking endpoint:** In the API Connector, add a new call to the UPS OAuth API group (or create a separate 'UPS API' group for the downstream calls). Name it 'Track Shipment'. Method: GET. URL: `[ups_base_url]/track/v1/details/[tracking_number]`. Add a call-level header: `Authorization: Bearer [access_token from cached UPSToken]`. This header is dynamic — it references the UPSToken Data Type, not a static App Constant — so it does not need to be Private in the traditional sense, but it is never sent to the browser because it is inside a Backend Workflow. Add query parameters: - `locale` = `en_US` - `returnSignature` = `false` Initialize the call using a real UPS sandbox tracking number (UPS provides test tracking numbers in the developer portal documentation). Set 'Use as' to 'Data'. **Step 3 — Parse the response and return data:** The UPS tracking response has a nested structure: `trackResponse.shipment[0].package[0].activity[0]` holds the most recent status update with `status.description` and `location.address`. Use Bubble's 'Extract JSON body value' steps to surface the key fields. Store them in a Bubble Data Type called 'UPSTrackingResult' or return them to the frontend via a Custom State. RapidDev's team has built UPS tracking integrations with Bubble for e-commerce clients, including token refresh logic and multi-package dashboards. If your use case is complex, reach out at rapidevelopers.com/contact for a free scoping call.

1// GET /track/v1/details/{trackingNumber} — query params
2// ?locale=en_US&returnSignature=false
3// Headers: Authorization: Bearer eyJraWQiOiJ...
4
5// Sample response (simplified)
6{
7  "trackResponse": {
8    "shipment": [
9      {
10        "inquiryNumber": "1Z12345E0205271688",
11        "package": [
12          {
13            "trackingNumber": "1Z12345E0205271688",
14            "currentStatus": {
15              "description": "In Transit",
16              "code": "I"
17            },
18            "deliveryDate": [
19              { "date": "20260714", "type": "DEL" }
20            ],
21            "activity": [
22              {
23                "date": "20260709",
24                "time": "143000",
25                "location": {
26                  "address": {
27                    "city": "Louisville",
28                    "stateProvince": "KY",
29                    "country": "US"
30                  }
31                },
32                "status": {
33                  "description": "Package transferred to destination facility",
34                  "code": "I"
35                }
36              }
37            ]
38          }
39        ]
40      }
41    ]
42  }
43}

Add a second downstream call to the UPS API. Name it 'Get Rate'. Method: POST. URL: `[ups_base_url]/rating/v2409/Rate`. Add `Content-Type: application/json` and `transactionSrc: Bubble` headers at the call level, plus the dynamic `Authorization: Bearer [token]` header. The UPS Rating API accepts a detailed JSON body with shipper, destination, and package information. Create a Backend Workflow called 'UPS Get Rate' with parameters for the destination address and package dimensions. In the workflow, first check for a valid cached token (same pattern as the tracking workflow). Then call the Get Rate action with a dynamically constructed JSON body. The response contains a `RateResponse.RatedShipment` array with each service level (Ground, 2-Day Air, Next Day Air) and its `TotalCharges.MonetaryValue`. Surface this array to the frontend so the user can select a shipping method at checkout. For the initialize call in the API Connector, use the UPS developer portal's sample request JSON — the Rating API body is complex and all fields must be present for a valid test response. Bubble's initialize step needs a real successful response to detect the schema correctly.

1// POST /rating/v2409/Rate — simplified request body
2{
3  "RateRequest": {
4    "Shipment": {
5      "Shipper": {
6        "Address": {
7          "PostalCode": "78701",
8          "CountryCode": "US"
9        }
10      },
11      "ShipTo": {
12        "Address": {
13          "City": "<dynamic: to_city>",
14          "StateProvinceCode": "<dynamic: to_state>",
15          "PostalCode": "<dynamic: to_postal>",
16          "CountryCode": "US"
17        }
18      },
19      "ShipFrom": {
20        "Address": {
21          "PostalCode": "78701",
22          "CountryCode": "US"
23        }
24      },
25      "Package": {
26        "PackagingType": { "Code": "02" },
27        "PackageWeight": {
28          "UnitOfMeasurement": { "Code": "LBS" },
29          "Weight": "<dynamic: weight_lbs>"
30        }
31      }
32    }
33  }
34}
35
36// Response — RatedShipment array
37{
38  "RateResponse": {
39    "RatedShipment": [
40      {
41        "Service": { "Code": "03", "Description": "UPS Ground" },
42        "TotalCharges": { "CurrencyCode": "USD", "MonetaryValue": "12.45" }
43      },
44      {
45        "Service": { "Code": "02", "Description": "UPS 2nd Day Air" },
46        "TotalCharges": { "CurrencyCode": "USD", "MonetaryValue": "28.99" }
47      }
48    ]
49  }
50}

From the Bubble frontend (a button click, page load, or form submission), trigger the Backend Workflow using 'Schedule API Workflow' → select your Backend Workflow → pass the required parameters (tracking number, address fields, etc.). For tracking: add a 'Track' button to your order detail page. On click, trigger 'UPS Track Package' with the stored tracking number. After the Backend Workflow completes, the result is stored in a UPSTrackingResult Data Type or a Custom State — bind the tracking status display to this data. Before switching to production: 1. In UPS developer portal → My Apps → your app, get the PRODUCTION Client ID and Client Secret (separate from sandbox credentials) 2. Update the `ups_client_id` App Constant to the production Client ID 3. Update the `ups_client_secret` App Constant to the production Client Secret 4. Update the `ups_base_url` App Constant to `https://onlinetools.ups.com` 5. Clear any cached UPSToken records so the first production call mints a fresh production token Test with a real UPS tracking number from a recent shipment to verify the production credentials and base URL work together. The UPS tracking numbers in Sandbox documentation are test-only and will not resolve against `onlinetools.ups.com`.

1# Steps for switching from Sandbox to Production
2
3# 1. Update App Constant: ups_base_url
4# Sandbox:    https://wwwcie.ups.com
5# Production: https://onlinetools.ups.com
6
7# 2. Update App Constants with production credentials:
8# ups_client_id     → production Client ID
9# ups_client_secret → production Client Secret (Private)
10
11# 3. Clear cached tokens:
12# In Bubble, run a one-time workflow:
13# 'Make changes to all UPSToken where is_active = Yes'
14# → set is_active = No
15
16# 4. Test with a real tracking number from a recent real UPS shipment
17# Production tracking numbers: 1Z + 16 characters (e.g., 1Z12345E0205271688)
18# Sandbox test numbers: see UPS developer portal Track API documentation