Freightos

Before opening Bubble's API Connector, confirm that your Freightos account has API access enabled. This is the step that catches most Bubble-Freightos integration attempts before they start: depending on your Freightos plan tier, API credentials may not be automatically available. Contact your Freightos account manager or email the developer support team through dev.freightos.com. Request: 1. Confirmation that API access is enabled on your account 2. Your API key (may be labeled as API token, access key, or similar) 3. Your Freightos organization ID (required in rate request bodies) 4. The exact header name for API authentication — likely `X-API-Key` or `Authorization`, but verify against your specific documentation 5. The base URL for your account — production is typically `https://api.freightos.com` but sandbox/staging URLs are provided separately 6. Any sandbox credentials and test endpoints for development If you have a Freightos enterprise account, your credentials may include a dedicated tenant URL rather than the shared API endpoint. Always use the credentials exactly as provided — do not assume the header name or base URL based on convention. While waiting for credentials, proceed with Step 2 to set up the API Connector structure so you're ready to configure and test as soon as credentials arrive.

In your Bubble editor, click 'Plugins' in the left sidebar → 'Add plugins' → search 'API Connector' (by Bubble) → Install. Click 'API Connector' in your plugins list → 'Add another API.' Name it 'Freightos.' Set the 'API Root URL' to the base URL provided with your credentials (for example, `https://api.freightos.com`). If you received a sandbox URL, start with that. Under 'Shared headers,' click 'Add a shared header.' Use the exact header name from your Freightos documentation — this is likely `X-API-Key` with your API key as the value, or `Authorization` with `Bearer <key>` or just the raw key. The exact format depends on your account configuration — verify with your account rep if unsure. Critically: check the **'Private'** checkbox on the API key header. This keeps the key server-side in Bubble's API Connector and prevents it from appearing in browser network requests. Also add a Content-Type header: key `Content-Type`, value `application/json`. This is needed for POST rate requests. To test the connection before building the full rate request, add a simple GET call. Name it 'Health Check' or 'Get Account Info.' Ask your Freightos rep which endpoint can be used to verify credentials — a simple GET that returns account or carrier information without requiring a rate query. Initialize this call to confirm the connection is working before proceeding.

1{
2  "api_name": "Freightos",
3  "base_url": "https://api.freightos.com",
4  "note": "Verify base_url with your Freightos account rep — may differ by account configuration",
5  "shared_headers": [
6    {
7      "key": "X-API-Key",
8      "value": "<private: your_freightos_api_key>",
9      "private": true,
10      "note": "Verify exact header name with Freightos docs — may be Authorization or another name"
11    },
12    {
13      "key": "Content-Type",
14      "value": "application/json"
15    }
16  ]
17}

Before building the rate request call, set up the port code input UI in your Bubble app. This is critical: Freightos requires exact 5-character UN/LOCODE port codes for origin and destination. A free-text input will result in typos that cause silent failures — empty results with no error message. Create a Bubble Option Set called 'Port Codes.' Add entries for each port in your platform's trade lanes. Each entry should have: a `Display` name ('Shanghai (CNSHA)'), a `Code` field (Text, value: 'CNSHA'), a `Country` field (Text), and a `Mode` field (e.g., 'Ocean', 'Air', 'Truck') indicating which freight modes serve this port. Common high-volume ports to include: - Asia origin: CNSHA (Shanghai), CNNGB (Ningbo), CNSZX (Shenzhen), CNCAN (Guangzhou), KRPUS (Busan) - US destination: USLAX (Los Angeles), USNYC (New York), USLGB (Long Beach), USSEA (Seattle), USHOU (Houston) - Europe: DEHAM (Hamburg), NLRTM (Rotterdam), GBFXT (Felixstowe), BEANR (Antwerp) - Air: your airline cargo gateway airports use the same LOCODE format In your Bubble page, add two Dropdown elements: 'Origin Port' and 'Destination Port.' Set their type to 'Port Codes' (your Option Set). Display as `Code's Display name`. This gives users a searchable dropdown with friendly names while providing the exact 5-character code for the API call. The selected dropdown's `Code` field is what you pass to the Freightos API — this guarantees the format is always correct.

1{
2  "option_set": "Port Codes",
3  "fields": [
4    { "name": "display", "type": "text", "example": "Shanghai (CNSHA)" },
5    { "name": "code", "type": "text", "example": "CNSHA" },
6    { "name": "country", "type": "text", "example": "CN" },
7    { "name": "mode", "type": "text", "example": "Ocean" }
8  ],
9  "sample_entries": [
10    { "display": "Shanghai (CNSHA)", "code": "CNSHA", "country": "CN", "mode": "Ocean" },
11    { "display": "Los Angeles (USLAX)", "code": "USLAX", "country": "US", "mode": "Ocean" },
12    { "display": "Hamburg (DEHAM)", "code": "DEHAM", "country": "DE", "mode": "Ocean" },
13    { "display": "Ningbo (CNNGB)", "code": "CNNGB", "country": "CN", "mode": "Ocean" },
14    { "display": "New York (USNYC)", "code": "USNYC", "country": "US", "mode": "Ocean" }
15  ]
16}

Add the rate request call to your API Connector. Click 'Add a call,' name it 'Get Freight Rates,' set method to POST, and set the path to the rate endpoint from your Freightos documentation (typically `/rates`, `/quote`, or `/shipments/rates` — verify with your account rep). Set the body type to 'JSON body.' The rate request body structure specifies origin, destination, cargo details, and your organization. Verify the exact field names against your Freightos API documentation — the structure below is a common pattern but field names may vary by account configuration: Set 'Use as' to 'Action.' Click 'Initialize call.' You'll need to provide: - A valid origin UN/LOCODE (e.g., `CNSHA`) - A valid destination UN/LOCODE (e.g., `USLAX`) - Realistic cargo dimensions (weight in kg, volume in CBM for ocean; weight in kg for air) - Your organization ID from your Freightos credentials A successful response returns an array of carrier rate objects. Each object typically includes: carrier name, transport mode (ocean/air/truck), transit days, origin charges, freight charges, destination charges, and total cost. Bubble auto-detects these fields after a successful Initialize call. Note Bubble's 30-second workflow timeout: freight rate queries can take 10–25 seconds for multi-carrier LCL or air searches. Add a loading state (show a spinner, disable the 'Get Rates' button) when the workflow starts, and clear it when results are returned.

1{
2  "call_name": "Get Freight Rates",
3  "method": "POST",
4  "path": "/rates",
5  "note": "Verify exact path with Freightos account documentation",
6  "body": {
7    "origin": {
8      "locationCode": "<dynamic: origin port code — e.g., CNSHA>"
9    },
10    "destination": {
11      "locationCode": "<dynamic: destination port code — e.g., USLAX>"
12    },
13    "cargo": {
14      "type": "<dynamic: FCL | LCL | AIR>",
15      "totalWeight": {
16        "value": "<dynamic: weight in kg>",
17        "unit": "KG"
18      },
19      "totalVolume": {
20        "value": "<dynamic: volume in CBM>",
21        "unit": "CBM"
22      }
23    },
24    "organizationId": "<your_freightos_org_id>"
25  },
26  "note_verify_fields": "Field names and structure vary by Freightos account configuration — verify against your API documentation"
27}

Now build the rate display UI. Add a Repeating Group to your page. Set its data source to the result of the 'Get Freight Rates' API call (run as a data source, or save results to a 'Freight Rate' data type in Bubble's database after the workflow runs). If saving to database: create a 'Freight Rate' data type with fields: `carrier_name` (Text), `transport_mode` (Text), `transit_days` (Number), `origin_charges` (Number), `freight_charges` (Number), `destination_charges` (Number), `total_cost` (Number), `currency` (Text), `rate_id` (Text), `quote_id` (Text), `expires_at` (Date). After the 'Get Freight Rates' call, run a workflow step that creates Freight Rate records from the response array. Sort the repeating group by `total_cost ascending`. Inside the Repeating Group cell, add text elements showing: - Carrier name and logo (if available in the response) - Transport mode badge (Ocean / Air / Truck) - Total cost formatted as currency - Breakdown: origin + freight + destination charges - Estimated transit days - A 'Select' or 'Book' button Add a Privacy rule on Freight Rate: restrict visibility to the user who initiated the quote query. Freight pricing is commercially sensitive — don't expose one customer's rate quotes to another. For booking: add a POST call named 'Book Shipment' using the selected rate's quote or rate ID. The booking endpoint and body structure are specific to your Freightos configuration — request this from your account rep along with the rate request documentation. Add the booking call with the rate ID as a dynamic parameter, triggered by the 'Book' button on the selected rate row. RapidDev's team has built freight procurement tools on Bubble integrating with carrier APIs and freight marketplaces. If your platform requires complex multi-leg or multi-mode booking flows, a free scoping call at rapidevelopers.com/contact can help plan the architecture.

Freight rate queries — particularly for LCL (Less than Container Load) or multi-carrier air searches — can take 10–25 seconds as Freightos polls multiple carrier systems for live rates. Bubble's workflow timeout is 30 seconds. If the Freightos API takes longer than 30 seconds to respond, the Bubble workflow fails without returning results. To handle this gracefully, implement a loading state pattern: 1. Add a custom state to your page: `is_loading_rates` (boolean), initially false. 2. When the 'Get Rates' button is clicked: first set `is_loading_rates` to true. This state controls the visibility of a loading spinner group and disables the 'Get Rates' button. 3. Run the API call as the next workflow step. 4. After the API call (whether success or failure): set `is_loading_rates` to false. If Freightos offers an asynchronous rate request pattern (submit a quote request, receive a quote ID, poll for results), this is more resilient than synchronous calls in Bubble. A Backend Workflow (paid Bubble plan) can poll for rate results every 3–5 seconds and update Bubble's database when complete — removing the 30-second constraint. Ask your Freightos account rep whether the rate API is synchronous (waits for all carrier responses before returning) or asynchronous (returns a quote ID for polling). If asynchronous, implement a Backend Workflow polling loop using Bubble's 'Schedule API Workflow' action to check for rate results every few seconds. For faster response times, narrow the carrier selection (if Freightos allows filtering by specific carriers or modes) to reduce the number of rate sources queried per request.

1{
2  "loading_state_pattern": {
3    "custom_state": "is_loading_rates (boolean)",
4    "on_button_click": [
5      "Set state is_loading_rates = true",
6      "Run API: Get Freight Rates (with params)",
7      "Create Freight Rate records from response",
8      "Set state is_loading_rates = false"
9    ],
10    "ui_conditions": [
11      "Loading spinner: visible when is_loading_rates is true",
12      "Get Rates button: disabled when is_loading_rates is true",
13      "Rates repeating group: visible when is_loading_rates is false"
14    ]
15  },
16  "timeout_note": "Bubble's workflow timeout is 30 seconds. If Freightos takes longer, consider async rate request pattern with Backend Workflow polling (paid plan required)."
17}