UPS API

Open developer.ups.com and sign in with your UPS account. Navigate to the Apps section and click 'Create App'. Give it a name (for example, 'FlutterFlow Tracker'), select the APIs you need — at minimum 'Tracking' for order status — and accept the terms. After creation, the portal displays your Client ID and Client Secret on the app detail screen. Copy both values and store them somewhere safe like a password manager; you will paste them into your Cloud Function's environment configuration and they must never appear in your FlutterFlow project. Note the two base URLs for UPS environments. For sandbox testing, use `https://wwwcie.ups.com` as the host. For production, use `https://onlinetools.ups.com`. Both environments use identical API paths — the only difference is the hostname. The token endpoint in both environments is `/security/v1/oauth/token`. The Tracking API path is `/api/track/v1/details/{trackingNumber}`. Setting a clear reminder to switch from sandbox to production before release is important: mixing environments causes 404 responses because sandbox tracking numbers don't exist in the production database and vice versa.

This step is the security core of the entire integration. The UPS client secret cannot safely live in a Flutter app because the compiled binary can be decompiled. It belongs exclusively in a Cloud Function environment variable on Google's servers. Open the Firebase console and navigate to your project. Go to Functions and create a new function named `upsTrack`. Set two environment variables under Edit Configuration: `UPS_CLIENT_ID` and `UPS_CLIENT_SECRET` — paste the values from the UPS developer portal here, not into any FlutterFlow field. The function below performs the full flow: it checks whether it already holds a valid cached token (UPS tokens last 14,400 seconds), requests a new one from UPS if needed, then calls the UPS Tracking API with the cached token and returns the package activity array to your FlutterFlow app. Your app only ever sends a tracking number to your Cloud Function URL — it never communicates directly with UPS and never holds any credentials. Note the CORS headers in the function. These are required for FlutterFlow web builds; native iOS and Android builds don't need them but including them keeps the same function usable across all targets without changes.

1// Firebase Cloud Function — index.js
2const functions = require('firebase-functions');
3const axios = require('axios');
4
5// In-memory token cache
6let cachedToken = null;
7let tokenExpiry = 0;
8
9const UPS_BASE = 'https://wwwcie.ups.com'; // change to onlinetools.ups.com for production
10
11async function getUpsToken() {
12  const now = Date.now();
13  if (cachedToken && now < tokenExpiry) {
14    return cachedToken;
15  }
16  const clientId = process.env.UPS_CLIENT_ID;
17  const clientSecret = process.env.UPS_CLIENT_SECRET;
18  const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
19
20  const response = await axios.post(
21    `${UPS_BASE}/security/v1/oauth/token`,
22    'grant_type=client_credentials',
23    {
24      headers: {
25        'Authorization': `Basic ${credentials}`,
26        'Content-Type': 'application/x-www-form-urlencoded',
27        'x-merchant-id': clientId
28      }
29    }
30  );
31
32  cachedToken = response.data.access_token;
33  // 400s safety buffer before the 14,400s UPS token expiry
34  tokenExpiry = now + 14000 * 1000;
35  return cachedToken;
36}
37
38exports.upsTrack = functions.https.onRequest(async (req, res) => {
39  res.set('Access-Control-Allow-Origin', '*');
40  if (req.method === 'OPTIONS') {
41    res.set('Access-Control-Allow-Methods', 'GET');
42    res.set('Access-Control-Allow-Headers', 'Content-Type');
43    return res.status(204).send('');
44  }
45
46  const trackingNumber = req.query.trackingNumber;
47  if (!trackingNumber) {
48    return res.status(400).json({ error: 'trackingNumber query param required' });
49  }
50
51  try {
52    const token = await getUpsToken();
53    const trackRes = await axios.get(
54      `${UPS_BASE}/api/track/v1/details/${trackingNumber}`,
55      {
56        headers: {
57          'Authorization': `Bearer ${token}`,
58          'transId': `ff-${Date.now()}`,
59          'transactionSrc': 'FlutterFlowApp'
60        }
61      }
62    );
63    const activity = trackRes.data
64      ?.trackResponse
65      ?.shipment?.[0]
66      ?.package?.[0]
67      ?.activity ?? [];
68    return res.json({ activity });
69  } catch (err) {
70    const status = err?.response?.status ?? 500;
71    return res.status(status).json({ error: err.message });
72  }
73});
74

In FlutterFlow, click 'API Calls' in the left navigation panel. Click '+ Add' and select 'Create API Group'. Name it 'UPS Tracker'. In the Base URL field, enter the root of your Cloud Function URL — everything before the function name path. For example: `https://us-central1-YOUR_PROJECT.cloudfunctions.net`. You do not need to add Authorization headers to this API Group. Your FlutterFlow app is calling your own Firebase Cloud Function (a public HTTPS endpoint), which handles all UPS authentication internally. Keep this API Group header-free. Inside the UPS Tracker group, click '+ Add API Call'. Name it 'Track Package'. Set the method to GET and the endpoint path to `/upsTrack`. Switch to the Variables tab and add one variable: `trackingNumber` (type String). Back on the main tab, update the endpoint to `/upsTrack?trackingNumber={{trackingNumber}}`. Click 'Response & Test'. Enter a UPS sandbox test tracking number in the `trackingNumber` test field and run the call. You should see the JSON response with an `activity` array. Click 'Generate from Response' to have FlutterFlow automatically create JSON Paths like `$.activity[*].location.address.city`, `$.activity[*].description.descriptionCode`, `$.activity[*].date`, and `$.activity[*].time`. These paths are what you will bind to Text widgets in your ListView.

1// Reference — API Call configuration
2// Group name: UPS Tracker
3// Base URL:   https://us-central1-YOUR_PROJECT.cloudfunctions.net
4// Call name:  Track Package
5// Method:     GET
6// Endpoint:   /upsTrack?trackingNumber={{trackingNumber}}
7//
8// Useful JSON Paths from response:
9// $.activity[*].description.descriptionCode  — event type
10// $.activity[*].location.address.city        — scan city
11// $.activity[*].location.address.stateProvince
12// $.activity[*].date                         — YYYYMMDD format
13// $.activity[*].time                         — HHMMSS format
14

Add a new Page to your FlutterFlow project named 'Track Package'. At the top, place a TextField for the tracking number input and a Button labeled 'Track'. Below these, add a ListView widget. Select the ListView and open its Backend Query settings. Set the Data Source to 'API Call', select 'UPS Tracker → Track Package', and bind the `trackingNumber` argument to the TextField's value using Set from Variable. Inside the ListView item template, add a Column containing: a Text widget bound to `$.activity[*].description.descriptionCode` (the event name), a Text widget for location using `$.activity[*].location.address.city` combined with `$.activity[*].location.address.stateProvince`, and a Text widget for the date and time. UPS returns dates in YYYYMMDD format and times in HHMMSS format — you may want to add a Custom Function to reformat these into a more readable string like 'Jul 10, 2026 at 2:30 PM'. UPS returns events in reverse-chronological order (newest first), so the ListView naturally shows the most recent scan at the top without sorting. Add a Conditional Visibility rule on a 'No tracking data yet' Text widget that appears when the activity list is empty — this handles invalid tracking numbers and shipments that haven't been scanned yet. For the Track button's action, set it to Rebuild the ListView's Backend Query with the current TextField value rather than navigating away, so results appear inline on the same screen after the user taps Track.

When you are ready to release the app, switch the Cloud Function from the UPS sandbox to production. In your Cloud Function code (`index.js`), change the value of `UPS_BASE` from `https://wwwcie.ups.com` to `https://onlinetools.ups.com` and redeploy the function from the Firebase console. Nothing in your FlutterFlow project needs to change — your app still calls the same Cloud Function URL; only the function's internal upstream target changes. For production use, log in to developer.ups.com and follow the steps to promote your app from sandbox to production status. Depending on which UPS APIs you use, you may need to provide a UPS account number. Tracking-only integrations are generally approved quickly; rating and label creation require more account verification. For rate limit management in production: UPS does not publish a single per-key rate limit, but treat it conservatively. The token caching in your Cloud Function already eliminates redundant auth requests. Avoid triggering tracking refreshes automatically on page load — instead, fire the API call only when the user taps Track, and store the last result in App State so navigating back to the screen doesn't re-request. If you need to track many shipments in bulk, use a Firebase Scheduled Function to pre-fetch and cache statuses in Firestore rather than hitting UPS in real time from the mobile app.

1// Flip one constant in index.js to switch environments:
2// const UPS_BASE = 'https://wwwcie.ups.com';      // sandbox
3// const UPS_BASE = 'https://onlinetools.ups.com';  // production
4// Redeploy the function — no FlutterFlow changes needed.
5