Shippo

Log in to your Shippo account at app.goshippo.com. In the left sidebar, click API under the developer settings section. You will see two tokens: a Test Token and a Live Token. The test token starts with `shippo_test_` and allows you to fetch real carrier rates and simulate label purchases without incurring any charges. This is what you should use throughout all development and testing. Copy your test token. Store it securely — you will paste it into your Cloud Function environment variables in the next step, not into any FlutterFlow field. The test token starts with `shippo_test_` followed by a long alphanumeric string. Understand what this token can do: the live token can purchase real shipping labels, which generates real charges to your Shippo account and real postage on real carriers. For this reason, it absolutely must not appear in a FlutterFlow API Call header, an App State variable, or any other location that is compiled into the app bundle. A token embedded in an iOS or Android binary can be extracted by anyone who downloads your app. The Cloud Function proxy pattern is mandatory for any token that can initiate financial transactions. You will return to the Shippo dashboard at the end of development to copy the live token and update your Cloud Function environment variable. Until then, always use the test token.

Open the Firebase Console at console.firebase.google.com and select your Firebase project. Click Functions in the left sidebar. If you haven't deployed functions before, click Get Started and follow the prompts — you will need to upgrade to the Blaze (pay-as-you-go) plan. The free tier allocation covers development and low-traffic testing at no practical cost. Create a new Cloud Function and name it `shippoProxy`. Set the trigger to HTTP so it gets a public URL. In the function's source code editor, paste the Node.js code shown below. This is the most critical step: pay close attention to line where the Authorization header is set. It MUST be `'Shippo ' + token` — not `'Bearer ' + token`. The 'Shippo' prefix is a capital S followed by exactly one space, followed by the token value. Any deviation from this format — lowercase s, two spaces, adding 'Bearer', or any other variation — causes the Shippo API to return HTTP 200 with an empty `rates` array and no error message. In the Runtime environment variables section of the Cloud Function configuration, add a variable named `SHIPPO_TOKEN` with the value of your test token from Step 1. Deploy the function. Firebase will provide you with an HTTPS URL for the function — copy it for use in FlutterFlow.

1const functions = require('firebase-functions');
2const fetch = require('node-fetch');
3
4exports.shippoProxy = functions.https.onRequest(async (req, res) => {
5  res.set('Access-Control-Allow-Origin', '*');
6  res.set('Access-Control-Allow-Methods', 'POST, GET, OPTIONS');
7  res.set('Access-Control-Allow-Headers', 'Content-Type');
8
9  if (req.method === 'OPTIONS') {
10    res.status(204).send('');
11    return;
12  }
13
14  // CRITICAL: Shippo auth is 'Shippo <token>' — NOT 'Bearer <token>'
15  // Using Bearer returns HTTP 200 with empty rates[] and NO error message.
16  const token = process.env.SHIPPO_TOKEN;
17  const path = req.query.path || 'shipments';
18
19  try {
20    const response = await fetch(`https://api.goshippo.com/${path}`, {
21      method: req.method === 'GET' ? 'GET' : 'POST',
22      headers: {
23        'Content-Type': 'application/json',
24        'Authorization': 'Shippo ' + token  // Capital S, one space
25      },
26      body: req.method !== 'GET' ? JSON.stringify(req.body) : undefined
27    });
28
29    const data = await response.json();
30    res.status(response.status).json(data);
31  } catch (err) {
32    res.status(500).json({ error: err.message });
33  }
34});

In your FlutterFlow project, navigate to the shipping screen where you want to add the rate calculator. Add the following form fields to collect the data Shippo needs: a TextField for the recipient's name, a TextField for the delivery street address, city, state, and zip code (you can use separate fields or combine them), and TextFields for the parcel weight (in oz or grams), length, width, and height in inches. Add a Button labeled 'Get Rates'. Now click API Calls in the left navigation. Click + Add → Create API Group. Name the group 'Shippo' and set the Base URL to your Cloud Function URL from Step 2 (for example, `https://us-central1-your-project.cloudfunctions.net/shippoProxy`). No Authorization headers are needed in FlutterFlow — the token is handled inside the function. Inside the Shippo API Group, click + Add Call. Name this Call 'GetRates'. Set the method to POST. In the Body tab, set the body type to JSON and paste the shipment request body shown in the code block below. Use `{{ variable }}` syntax for each field that will come from the user's form inputs (recipientName, recipientStreet, recipientCity, recipientState, recipientZip, parcelWeight, parcelLength, parcelWidth, parcelHeight). Switch to the Variables tab and add variables matching each {{ variable }} placeholder in the body. Set sensible test defaults (for example, weight: 16 for a 1-pound parcel). Click Test and fill in a real delivery address — the function should return a rates[] array with multiple carrier options within a second or two.

1{
2  "address_from": {
3    "name": "Your Business Name",
4    "street1": "215 Clayton St",
5    "city": "San Francisco",
6    "state": "CA",
7    "zip": "94117",
8    "country": "US"
9  },
10  "address_to": {
11    "name": "{{ recipientName }}",
12    "street1": "{{ recipientStreet }}",
13    "city": "{{ recipientCity }}",
14    "state": "{{ recipientState }}",
15    "zip": "{{ recipientZip }}",
16    "country": "US"
17  },
18  "parcels": [{
19    "length": "{{ parcelLength }}",
20    "width": "{{ parcelWidth }}",
21    "height": "{{ parcelHeight }}",
22    "distance_unit": "in",
23    "weight": "{{ parcelWeight }}",
24    "mass_unit": "oz"
25  }],
26  "async": false
27}

In your FlutterFlow project, click the Data Types section and add a Custom Data Type named 'ShippoRate'. Add the following fields: `objectId` (String), `provider` (String — the carrier name like 'USPS'), `serviceName` (String — like 'Priority Mail'), `amount` (String — the formatted price), `currency` (String), `estimatedDays` (int or String), and `duration_terms` (String for delivery estimate text). Navigate back to your shipping screen. In the Action Flow Editor, wire the 'Get Rates' button to an action sequence: first call the Shippo → GetRates API Call, passing each form field value to the corresponding variable. After the API Call completes, use an Update App State action to store the rates array in a List-type App State variable using your ShippoRate Custom Data Type. Use these JSON paths to map the Shippo response: `$.rates[*].object_id`, `$.rates[*].provider`, `$.rates[*].servicelevel.name`, `$.rates[*].amount`, `$.rates[*].currency`, and `$.rates[*].estimated_days`. Add a ListView widget below the form fields. Set it to generate children from the App State rates list. Inside the list item template, add a Card with: a Text widget showing `rate.provider + ' ' + rate.serviceName`, a Text widget showing `'$' + rate.amount`, and a Text widget showing `rate.estimatedDays + ' days'`. Add a 'Select' button on each card that stores the selected rate's `objectId` in a separate App State variable. After the user selects a rate, they can tap a 'Buy Label' button that triggers a second API Call — 'CreateTransaction' — that POSTs `{ 'rate': selectedRateId }` to your proxy with path set to 'transactions'. The response contains a `label_url` field that you can open in a WebView or launch in the device browser for printing.

1// JSON paths for ShippoRate binding:
2// Rate ID:           $.rates[*].object_id
3// Carrier:           $.rates[*].provider
4// Service name:      $.rates[*].servicelevel.name
5// Price:             $.rates[*].amount
6// Currency:          $.rates[*].currency
7// Transit days:      $.rates[*].estimated_days
8// Delivery terms:    $.rates[*].duration_terms
9
10// Transaction body for label purchase:
11// { "rate": "{{ selectedRateId }}", "label_file_type": "PDF", "async": false }
12
13// Label URL JSON path after transaction:
14// $.label_url

When your app is ready for production and you have tested the rate calculator and label purchase flow thoroughly with your `shippo_test_` token, go back to the Shippo dashboard at app.goshippo.com. Under API in the left sidebar, find your Live Token and copy it. In the Firebase Console, navigate to your `shippoProxy` Cloud Function → Runtime environment variables. Update the `SHIPPO_TOKEN` variable from your test token to your live token. Re-deploy the function (Firebase will deploy the updated environment variable without code changes). Verify the live token is working by making one test rate request from your FlutterFlow app — the rates should still appear as before since test and live tokens return the same rate data. However, note that label purchases made with the live token will now generate real charges on your Shippo account and real postage with real tracking numbers. Add a confirmation step in your app before the 'Buy Label' action: show the user the carrier, price, and delivery estimate, and ask them to confirm before the purchase is committed. This prevents accidental label purchases from users who tap the button twice or confirm the wrong rate selection. For tracking existing shipments, add a 'Track' API Call to your Shippo API Group. The endpoint is `GET /tracks/{carrier}/{tracking_number}`. Shippo unifies tracking across all supported carriers — pass the carrier slug (for example, `usps`) and the tracking number as URL path segments, and Shippo returns a unified tracking timeline regardless of which carrier actually shipped the package.

1// Tracking request (add as a GET call in the Shippo API Group):
2// Endpoint: /tracks/{{ carrier }}/{{ trackingNumber }}
3// Method: GET
4// No body needed
5
6// Tracking JSON paths:
7// Status:            $.tracking_status.status
8// Location:          $.tracking_status.location.city
9// Status date:       $.tracking_status.status_date
10// History entries:   $.tracking_history[*].status
11// History locations: $.tracking_history[*].location.city