FedEx API

Go to developer.fedex.com and click 'Log In' or 'Join FedEx Developer' to register. You'll need a FedEx account for registration — if you don't have a FedEx customer account, you can register for one during this process. Once logged in, go to 'My Projects' and click 'Create a Project.' Give the project a name (for example, 'Bubble App Integration'). Under 'APIs,' select the API products you need. For tracking: select 'Track API.' For rate quoting and label generation: also select 'Ship API' and 'Rates and Transit Times.' After creating the project, go to the project's settings. In the 'Production Credentials' section, you'll find your **API Key** and **Secret Key**. Copy both. In the 'Testing Credentials' section, copy your **Sandbox API Key** and **Sandbox Secret Key** — these are separate credentials for the sandbox environment. Important: FedEx sandbox tracking uses simulated tracking numbers documented in the developer portal. Real FedEx tracking numbers from live packages will NOT work in the sandbox — use the specific test tracking numbers provided in FedEx's developer documentation to test different status scenarios (in transit, exception, delivered). Plan for a potential 24–48 hour approval delay for full production API access. Sandbox access is typically instant.

In your Bubble editor, click 'Plugins' → 'Add plugins' → search 'API Connector' (by Bubble) → Install. Click 'API Connector' in your plugins list, then 'Add another API.' Name it 'FedEx.' For the base URL, start with the sandbox: `https://apis-sandbox.fedex.com`. You'll change this to `https://apis.fedex.com` for production. Add your first call: click 'Add a call,' name it 'Fetch Token.' Set the method to POST and the path to `/oauth/token`. Set the body type to 'URL encoded form' (this is critical — FedEx's token endpoint requires `application/x-www-form-urlencoded`, not JSON). In the body fields, add: - `grant_type`: value `client_credentials` (static — no dynamic marker needed) - `client_id`: value `<your_sandbox_api_key>` — check the **'Private'** checkbox on this field - `client_secret`: value `<your_sandbox_secret_key>` — check the **'Private'** checkbox on this field Under 'Use as,' select 'Action.' Click 'Initialize call.' A successful response returns `access_token` (a long JWT string), `token_type` (bearer), `expires_in` (3600), and `scope`. Bubble will auto-detect these fields. If you see an error, verify the body type is URL-encoded form, not JSON — FedEx's token endpoint rejects JSON-encoded credentials.

1{
2  "api_name": "FedEx",
3  "base_url_sandbox": "https://apis-sandbox.fedex.com",
4  "base_url_production": "https://apis.fedex.com",
5  "calls": [
6    {
7      "name": "Fetch Token",
8      "method": "POST",
9      "path": "/oauth/token",
10      "body_type": "x-www-form-urlencoded",
11      "body": {
12        "grant_type": "client_credentials",
13        "client_id": "<private: sandbox_api_key>",
14        "client_secret": "<private: sandbox_secret_key>"
15      },
16      "use_as": "Action",
17      "response_fields": [
18        "access_token",
19        "token_type",
20        "expires_in",
21        "scope"
22      ]
23    }
24  ]
25}

Now add the operational call. Click 'Add a call,' name it 'Track Shipment.' Set the method to POST and the path to `/track/v1/trackingnumbers`. Set the body type to 'JSON body.' The FedEx tracking request body structure is: Add a call-level header (not a shared header): key `Authorization`, value `Bearer <token>`. Mark this as a **dynamic** parameter — it will be filled in at workflow runtime with the stored access token. This is different from the Private static header pattern used for API keys — here the value changes with each token fetch. In Bubble's API Connector, you can make a header value dynamic by using the `<` and `>` markers: enter `Bearer <token>` where `token` is a named dynamic parameter. Set 'Use as' to 'Data.' The response structure is deeply nested: `output.completeTrackResults[0].trackResults[0].latestStatusDetail.description` for the current status, and `output.completeTrackResults[0].trackResults[0].dateAndTimes` (array) for scan timestamps. Click 'Initialize call' and provide a sandbox test tracking number from FedEx's documentation as the test value (and a placeholder Bearer token for the `token` parameter). Bubble will detect the deeply nested response fields. IMPORTANT after Initialize: the deeply nested structure means Bubble will detect the outer wrapper fields. Use the `:get` operator in workflows to navigate to inner fields: `result's output's completeTrackResults first item's trackResults first item's latestStatusDetail's description`.

1{
2  "call_name": "Track Shipment",
3  "method": "POST",
4  "path": "/track/v1/trackingnumbers",
5  "headers": [
6    {
7      "key": "Authorization",
8      "value": "Bearer <dynamic: access_token>",
9      "note": "Dynamic — filled from stored token at workflow runtime"
10    },
11    {
12      "key": "Content-Type",
13      "value": "application/json"
14    }
15  ],
16  "body": {
17    "trackingInfo": [
18      {
19        "trackingNumberInfo": {
20          "trackingNumber": "<dynamic: tracking_number>"
21        }
22      }
23    ],
24    "includeDetailedScans": true
25  },
26  "response_path_to_status": "output.completeTrackResults[0].trackResults[0].latestStatusDetail.description",
27  "response_path_to_events": "output.completeTrackResults[0].trackResults[0].scanEvents"
28}

The core complexity of the FedEx integration is managing the 1-hour token lifecycle. Here's how to implement it cleanly in Bubble. First, add two custom states to your main page (or to a reusable element if you need the token across multiple pages): name the first `fedex_token` (Text type) and the second `fedex_token_fetched_at` (Date type). Create a Bubble workflow named 'Ensure FedEx Token.' This workflow uses a conditional action: - Condition: `(Current date/time - Page's fedex_token_fetched_at) > 50 minutes` OR `Page's fedex_token is empty` - If true: Run API call 'FedEx — Fetch Token' → Set state `fedex_token` to `result's access_token` → Set state `fedex_token_fetched_at` to `Current date/time` - If false: do nothing (the cached token is still valid) Now create the 'Track Package' workflow triggered by your tracking button: 1. Run workflow 'Ensure FedEx Token' (this runs the conditional check and re-fetches only if needed) 2. Run API call 'FedEx — Track Shipment' with `token` parameter set to `Page's fedex_token` and `tracking_number` set to the Input field's value 3. Display the result This pattern ensures the token is always fresh without making unnecessary token-fetch calls on every button click. The 50-minute threshold (rather than 60) provides a safety buffer — a token fetched at 55 minutes remaining will still be valid for the operational call that follows.

1{
2  "custom_states": [
3    { "name": "fedex_token", "type": "text" },
4    { "name": "fedex_token_fetched_at", "type": "date" }
5  ],
6  "ensure_token_workflow": {
7    "condition": "(Current datetime - fedex_token_fetched_at) > 50 minutes OR fedex_token is empty",
8    "if_true": [
9      "Run API: FedEx Fetch Token",
10      "Set state fedex_token = result's access_token",
11      "Set state fedex_token_fetched_at = Current datetime"
12    ],
13    "if_false": "skip — cached token still valid"
14  },
15  "track_package_workflow": [
16    "Step 1: Run 'Ensure FedEx Token' workflow",
17    "Step 2: Run API: FedEx Track Shipment — token: Page's fedex_token, tracking_number: Input's value",
18    "Step 3: Display result fields in UI elements"
19  ]
20}

FedEx's tracking response is among the most deeply nested API responses you'll encounter — 5 to 6 levels of nesting to reach the data you need. Here's how to navigate it in Bubble's workflow editor. After the Track Shipment call, the result structure is: - `result's output` → tracking output object - `result's output's completeTrackResults` → array of tracking results (one per tracking number in bulk calls) - `result's output's completeTrackResults's first item` → the result for your tracking number - `result's output's completeTrackResults's first item's trackResults` → array (usually one item) - `result's output's completeTrackResults's first item's trackResults's first item's latestStatusDetail` → current status - `...latestStatusDetail's description` → human-readable status string (e.g., 'Delivered') - `...latestStatusDetail's statusByLocale` → localized status - `...trackResults's first item's dateAndTimes` → array of dates (actual delivery, scheduled delivery) - `...trackResults's first item's scanEvents` → array of scan events, each with `date`, `eventDescription`, and `scanLocation` For display: create a Repeating Group with data source as the `scanEvents` array from the API result (set data type to 'API result's scan event' — Bubble detects custom types from Initialize call). Inside the cell, bind Text elements to `Current cell's date`, `Current cell's eventDescription`, and `Current cell's scanLocation's city`. For the status badge: bind a Text element to the first item in the chain: `Get data from external API — Track Shipment's result's output's completeTrackResults's first item's trackResults's first item's latestStatusDetail's description`. Test each level of the chain individually in Bubble's expression editor — clicking through the chain step by step is much easier than typing the full path.

1{
2  "response_navigation": {
3    "root": "result",
4    "level_1": "output",
5    "level_2": "completeTrackResults (array)",
6    "level_3": "[0] = first tracking number's result",
7    "level_4": "trackResults (array)",
8    "level_5": "[0]",
9    "current_status": "latestStatusDetail.description",
10    "delivery_dates": "dateAndTimes (array — filter by type 'ACTUAL_DELIVERY')",
11    "scan_history": "scanEvents (array)",
12    "scan_event_fields": [
13      "date",
14      "eventDescription",
15      "scanLocation.city",
16      "scanLocation.stateOrProvinceCode",
17      "scanLocation.countryCode"
18    ]
19  },
20  "bubble_expression_example": "result's output's completeTrackResults first item's trackResults first item's latestStatusDetail's description"
21}

When your integration is working correctly in sandbox mode, switching to production requires two changes in Bubble's API Connector: 1. Change the base URL from `https://apis-sandbox.fedex.com` to `https://apis.fedex.com` 2. Update the `client_id` and `client_secret` in the 'Fetch Token' call from your sandbox credentials to your production API Key and Secret Key from developer.fedex.com After switching, always re-initialize the Fetch Token call with production credentials to confirm the connection. Click 'Initialize call' on the Fetch Token call — a successful response confirms your production credentials are working. IMPORTANT: after changing the base URL, you must also re-initialize the Track Shipment call (and any other operational calls) because the Initialize call configuration is tied to the base URL environment. Click through each call's 'Initialize call' with valid production test data. For Privacy rules on any FedEx tracking data saved to Bubble's database: go to Data tab → Privacy → click on your tracking data type (e.g., 'Shipment'). Add a rule: 'Current User' can view 'when this Shipment's customer = Current User.' Set 'Everyone else' to no permissions. Tracking data with customer names, addresses, and delivery status is personal data — Bubble's default open access must be restricted.

1{
2  "environment_switch_checklist": [
3    "1. Update base URL: apis-sandbox.fedex.com → apis.fedex.com",
4    "2. Update client_id in Fetch Token call to production API Key",
5    "3. Update client_secret in Fetch Token call to production Secret Key",
6    "4. Re-initialize Fetch Token call to confirm production credentials work",
7    "5. Re-initialize Track Shipment call with a real production tracking number",
8    "6. Clear any cached sandbox tokens from custom states",
9    "7. Test end-to-end with a real FedEx tracking number"
10  ]
11}