How to Integrate Retool with Freightos

Freightos API access is not self-service for all plan tiers — contact your Freightos account manager or reach out through the Freightos developer portal at dev.freightos.com to request API access for your account. If you have an existing Freightos enterprise account, API credentials may already be available. Once API access is enabled for your account, navigate to the Freightos portal settings or developer documentation to find your API key. The API key is a string token that authenticates all your API requests. Additionally, note your Freightos account/organization identifier, which is required as a parameter in rate request and booking API calls. Freightos also maintains a sandbox environment for testing — request sandbox credentials alongside production credentials so you can test your Retool integration before using it for live freight operations. Sandbox credentials use the same API format but return simulated rate quotes without creating actual bookings or charges.

In Retool, navigate to the Resources tab and click 'Create New'. Select 'REST API' from the resource type list. Set the Base URL to 'https://api.freightos.com' for production, or the sandbox URL provided by your Freightos account team for testing. Under the Headers section, add the authentication header. Freightos uses an 'X-API-Key' header (or 'Authorization' header depending on your API version — check the documentation provided with your credentials) with your API key value. Use '{{ retoolContext.configVars.FREIGHTOS_API_KEY }}' as the header value. Also add 'Content-Type: application/json' as a default header. Before saving, go to Retool Settings → Configuration Variables and create 'FREIGHTOS_API_KEY' with your API key value marked as secret, and 'FREIGHTOS_ORG_ID' with your organization identifier (does not need to be secret). Click 'Save Resource'. Test the connection by creating a simple query to a list or account endpoint — a 200 response confirms the credentials are working.

1{
2  "Base URL": "https://api.freightos.com",
3  "Headers": {
4    "X-API-Key": "{{ retoolContext.configVars.FREIGHTOS_API_KEY }}",
5    "Content-Type": "application/json",
6    "Accept": "application/json"
7  }
8}

Create a rate request query to get freight quotes from Freightos. Set the method to POST and the path to the rate request endpoint (consult Freightos documentation for the exact path, typically '/api/v2/rates' or similar). The request body specifies the shipment parameters: origin location (UN/LOCODE for ports, e.g., 'CNSHA' for Shanghai), destination location (e.g., 'USLAX' for Los Angeles), cargo details including total weight, volume or dimensions, number of units, and cargo type (FCL, LCL, or air). The response returns an array of rate options, each with a carrier name, transit time in days, shipping mode, earliest available departure date, and detailed cost breakdown including origin handling charges, ocean or air freight, and destination charges. Add Retool components for the input fields: Select dropdowns for origin and destination ports (populated from a list of common routes your company uses), number inputs for weight and volume, and a Select for shipping mode. Trigger the rate query when the user clicks a 'Get Rates' button.

1// POST /api/v2/rates (verify path with Freightos docs)
2// Body (JSON):
3{
4  "origin": {
5    "locodePort": "{{ originPort.value }}"
6  },
7  "destination": {
8    "locodePort": "{{ destPort.value }}"
9  },
10  "cargo": {
11    "type": "{{ cargoType.value || 'LCL' }}",
12    "totalWeight": {
13      "amount": {{ weightInput.value || 100 }},
14      "unit": "kg"
15    },
16    "totalVolume": {
17      "amount": {{ volumeInput.value || 1 }},
18      "unit": "cbm"
19    }
20  },
21  "organizationId": "{{ retoolContext.configVars.FREIGHTOS_ORG_ID }}"
22}

Add a JavaScript transformer to the rate request query to reshape the raw API response into a format suitable for Retool's Table component. The Freightos rate response typically contains nested objects for cost components — extract total cost, currency, carrier name, transit days, shipping mode, and earliest departure date into a flat array. Calculate a cost-per-CBM or cost-per-kg metric for comparison across options with different total charges. Sort the results by total price ascending by default. Add a Table component bound to the transformer output with columns for carrier, mode, transit days, departure date, and total price. Include a 'Select' action column that stores the chosen rate option in a Retool state variable for the booking step. Add Stat components above the Table showing the lowest rate, fastest transit, and average market rate for the queried lane.

1// Transformer: format rate options for comparison table
2const rates = data && data.results ? data.results : data || [];
3
4return rates.map((rate, index) => {
5  const totalCharge = rate.totalCharge || rate.price || {};
6  const amount = totalCharge.amount || totalCharge.value || 0;
7  const currency = totalCharge.currency || 'USD';
8
9  const departureDate = rate.schedule && rate.schedule.departureDate
10    ? new Date(rate.schedule.departureDate).toLocaleDateString('en-US', {
11        year: 'numeric', month: 'short', day: 'numeric'
12      })
13    : 'Flexible';
14
15  const transitDays = rate.schedule
16    ? rate.schedule.transitDays || rate.schedule.estimatedTransitDays
17    : null;
18
19  return {
20    option: index + 1,
21    carrier: rate.carrier || rate.provider || 'Unknown',
22    mode: rate.serviceType || rate.mode || 'Unknown',
23    transit_days: transitDays ? `${transitDays} days` : 'Varies',
24    transit_days_raw: transitDays || 999,
25    departure: departureDate,
26    total_price: `${currency} ${parseFloat(amount).toFixed(2)}`,
27    total_price_raw: parseFloat(amount),
28    quote_id: rate.id || rate.quoteId || `option-${index}`
29  };
30}).sort((a, b) => a.total_price_raw - b.total_price_raw);

Create a tracking query to monitor booked shipments. Use GET with the path to the shipment tracking endpoint, typically '/api/v2/shipments/{shipmentId}/tracking' or '/api/v2/bookings/{bookingId}'. The tracking response includes the current shipment status, a list of milestone events (each with timestamp, event description, and location), estimated arrival date, and any exception or delay information. Read booking IDs from your logistics database — store Freightos booking IDs in your database when bookings are created — and create a query that loops through active booking IDs and fetches status for each. For bulk tracking without a loop, query your database for all booking IDs and pass them to a Retool Workflow that fetches tracking data for each and stores results in a staging table. Build a Retool Container with two panels: a summary table showing all active shipments with status, and a detail panel showing the full event timeline for the selected shipment. For complex multi-source integrations combining Freightos data with your order management system, RapidDev's team can help architect and build your Retool solution.

1// GET /api/v2/shipments/{shipment_id}/tracking
2
3// Transformer: format tracking milestones for timeline display
4const shipment = data || {};
5const milestones = shipment.events || shipment.milestones || [];
6
7const statusMap = {
8  'booked': 'Booking Confirmed',
9  'cargo_received': 'Cargo Received at Origin',
10  'departed_origin': 'Departed Origin Port',
11  'in_transit': 'In Transit',
12  'arrived_destination': 'Arrived at Destination Port',
13  'customs_cleared': 'Customs Cleared',
14  'delivered': 'Delivered',
15  'exception': 'Exception — Attention Required'
16};
17
18return {
19  shipment_id: shipment.id,
20  status: statusMap[shipment.status] || shipment.status || 'Unknown',
21  is_exception: shipment.status === 'exception' || shipment.delayed === true,
22  eta: shipment.estimatedArrival
23    ? new Date(shipment.estimatedArrival).toLocaleDateString('en-US', { year: 'numeric', month: 'short', day: 'numeric' })
24    : 'Unknown',
25  milestones: milestones.map(m => ({
26    event: statusMap[m.type] || m.description || m.type,
27    location: m.location || m.port || '',
28    timestamp: m.timestamp || m.date
29      ? new Date(m.timestamp || m.date).toLocaleString('en-US', { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' })
30      : ''
31  }))
32};