How to Integrate Bolt.new with Freightos

Getting Freightos WebCargo API access requires working through their enterprise onboarding process rather than self-service signup. The steps differ depending on whether you are an existing Freightos customer or approaching them purely for API access. For businesses already using the Freightos marketplace: log into your Freightos account at app.freightos.com, navigate to Account Settings → API Access or Integrations. If your account plan includes API access, you can generate API credentials from the dashboard. Contact your Freightos account manager if the API option is not visible — they can enable it for your account tier. For new customers approaching Freightos specifically for the API: go to freightos.com and contact their enterprise or developer team. Explain your use case — the freight quote comparison tool, e-commerce integration, or logistics dashboard you are building. Freightos evaluates API applications based on business legitimacy and expected usage volume. Consumer apps or hobbyist projects are unlikely to be approved; legitimate business logistics integrations are the target customer. The WebCargo API uses API key authentication. Once approved, you receive an API key and an API secret (used together as Basic authentication credentials, base64 encoded). Store these as FREIGHTOS_API_KEY and FREIGHTOS_API_SECRET in your Bolt .env file. Never expose these in client-side code. Freightos provides a sandbox environment for approved partners that returns realistic test quotes without creating real bookings. The sandbox API base URL is typically https://sandbox.api.webcargo.co/v2 (verify the exact URL with Freightos at onboarding). The production API base is https://api.webcargo.co/v2. Use sandbox for all development in your Bolt project — only switch to production when you are ready to process real shipments. For simpler parcel shipping use cases (packages under 70kg / 150lbs) that do not require freight-level complexity, consider ShipPo (goshippo.com) or EasyPost (easypost.com) instead. Both have free developer sandboxes with self-service signup and cover major carriers (FedEx, UPS, DHL) for parcel rates and labels. The Freightos API specifically targets freight: full containers (FCL), less-than-container-load (LCL), air cargo (tons), and heavy road freight.

1// lib/freightos/client.ts
2export const FREIGHTOS_API_BASE =
3  process.env.FREIGHTOS_API_ENV === 'production'
4    ? 'https://api.webcargo.co/v2'
5    : 'https://sandbox.api.webcargo.co/v2';
6
7function getAuthHeader(): string {
8  const key = process.env.FREIGHTOS_API_KEY ?? '';
9  const secret = process.env.FREIGHTOS_API_SECRET ?? '';
10  return `Basic ${Buffer.from(`${key}:${secret}`).toString('base64')}`;
11}
12
13export async function freightosRequest<T>(
14  endpoint: string,
15  method: 'GET' | 'POST' | 'PUT' = 'GET',
16  body?: object
17): Promise<T> {
18  const response = await fetch(`${FREIGHTOS_API_BASE}${endpoint}`, {
19    method,
20    headers: {
21      Authorization: getAuthHeader(),
22      'Content-Type': 'application/json',
23      Accept: 'application/json',
24    },
25    body: body ? JSON.stringify(body) : undefined,
26  });
27
28  if (!response.ok) {
29    const error = await response.text().catch(() => response.statusText);
30    throw new Error(`Freightos API ${response.status}: ${error}`);
31  }
32
33  return response.json();
34}
35
36// TypeScript interfaces for Freightos API
37export interface FreightosCargoDetails {
38  weight: { value: number; unit: 'kg' | 'lbs' };
39  volume?: { value: number; unit: 'cbm' | 'cft' };
40  containerType?: 'LCL' | '20GP' | '40GP' | '40HC';
41  commodity?: string;
42}
43
44export interface FreightosQuoteRequest {
45  origin: { port: string; country: string };
46  destination: { port: string; country: string };
47  cargo: FreightosCargoDetails;
48  incoterms: 'EXW' | 'FOB' | 'CIF' | 'DAP' | 'DDP';
49  shipmentDate: string; // YYYY-MM-DD
50}
51
52export interface FreightosQuoteResult {
53  quoteId: string;
54  carrier: string;
55  serviceType: string;
56  price: { total: number; currency: string };
57  transitDays: { min: number; max: number };
58  validUntil: string;
59  serviceLevel: 'standard' | 'express' | 'economy';
60}

The core of the Freightos integration is the rate quote flow: the user enters shipment details (origin, destination, cargo), your Next.js API route calls the Freightos quotes endpoint, and the results are displayed as a comparison table of available freight options sorted by price or transit time. The Freightos quotes API call requires careful input formatting. Origins and destinations are specified as port codes (UNLOCODE format) or city/country pairs depending on the shipment type. FCL (full container load) and LCL (less-than-container-load) ocean freight uses port-to-port UNLOCODE codes. Air freight uses IATA airport codes. The cargo specification includes weight, volume, and for FCL, the container type. The API response returns an array of quote objects, each representing a different carrier or service option. Key fields to display are: carrier name, total price (with currency), transit time range (minimum and maximum days), service type (standard, express, economy), the route (which ports are included), and a quote validity date. The quote ID is critical — you need it to proceed with booking. Sort the results by total price by default, with options to sort by transit time or carrier. Highlight the fastest option and the cheapest option with visual badges. For LCL shipments, show the per-CBM rate alongside the total rate so users can compare across different cargo sizes. The frontend form needs fields for: origin port (UNLOCODE or city), destination port, shipment date, incoterms (dropdown), cargo type (LCL/FCL/Air), weight (kg), and volume (CBM for ocean, kg for air). Add a 'Calculate Rates' button that triggers the API call. Show a loading state while the quote request is processing — Freightos queries multiple carriers in real time, so responses can take 2-5 seconds. Critical note for the Bolt WebContainer context: the API route makes an outbound HTTPS call to Freightos, which works fine in the WebContainer. There are no native module dependencies, no TCP socket requirements. The Freightos API is pure HTTP — a perfect fit for Bolt's architecture. The only limitation is webhook callbacks for booking confirmations, which require a deployed public URL.

1// app/api/freight/rates/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { freightosRequest, type FreightosQuoteRequest, type FreightosQuoteResult } from '@/lib/freightos/client';
4
5export async function POST(request: NextRequest) {
6  try {
7    const body = await request.json() as FreightosQuoteRequest;
8
9    // Validate required fields
10    if (!body.origin?.port || !body.destination?.port) {
11      return NextResponse.json(
12        { error: 'Origin and destination port codes are required' },
13        { status: 400 }
14      );
15    }
16    if (!body.cargo?.weight?.value) {
17      return NextResponse.json(
18        { error: 'Cargo weight is required' },
19        { status: 400 }
20      );
21    }
22
23    const quotes = await freightosRequest<{ quotes: FreightosQuoteResult[] }>(
24      '/quotes',
25      'POST',
26      body
27    );
28
29    // Sort by total price by default
30    const sorted = quotes.quotes.sort(
31      (a, b) => a.price.total - b.price.total
32    );
33
34    // Tag the cheapest and fastest options
35    const cheapestId = sorted[0]?.quoteId;
36    const fastestId = [...sorted].sort(
37      (a, b) => a.transitDays.min - b.transitDays.min
38    )[0]?.quoteId;
39
40    const enriched = sorted.map((q) => ({
41      ...q,
42      isCheapest: q.quoteId === cheapestId,
43      isFastest: q.quoteId === fastestId,
44    }));
45
46    return NextResponse.json({ quotes: enriched, total: enriched.length });
47  } catch (error) {
48    const message = error instanceof Error ? error.message : 'Failed to fetch freight rates';
49    // Check for auth errors
50    if (message.includes('401') || message.includes('403')) {
51      return NextResponse.json(
52        { error: 'Freightos API authentication failed — verify FREIGHTOS_API_KEY and FREIGHTOS_API_SECRET' },
53        { status: 401 }
54      );
55    }
56    return NextResponse.json({ error: message }, { status: 500 });
57  }
58}

After selecting a quote, the user confirms booking through the Freightos API. The booking request references the quote ID from the rate comparison and adds shipper and consignee details (company names, addresses, contact information). The Freightos API validates the information, reserves the slot with the carrier, and returns a booking reference number. The booking flow requires more information than the rate quote: full shipper company name and address, consignee company name and address, commodity description for customs, Harmonized System (HS) code for the goods, total invoice value and currency for customs declaration, and the number of packages with dimensions if not a full container. Store bookings in a Supabase table after each successful booking API call. The minimum fields to store are: the Freightos booking reference, quote ID, carrier name, origin and destination, status, cargo details, and timestamps. This gives you a local record of all freight bookings even if the Freightos API is temporarily unavailable. Freightos sends webhook notifications when booking status changes: booking confirmed by carrier, documents available (bill of lading), in-transit updates, customs clearance, and delivery confirmation. Register your webhook URL in the Freightos dashboard after deploying your app — webhooks cannot be received in Bolt's WebContainer since it has no public URL. The webhook handler at /api/freight/webhooks/freightos receives POST requests from Freightos with event type and booking data. Verify the request authenticity using the signature header Freightos includes (check the exact header name and signature algorithm in your Freightos documentation — it varies by integration type). After verification, update the booking status in your Supabase database and trigger any downstream actions (send shipment update email, notify ops team via Slack, update customer order status). For development testing without webhook functionality, you can poll the Freightos GET /bookings/{id} endpoint to check booking status updates instead of waiting for webhooks. This works in the Bolt WebContainer and is sufficient for validating the booking flow before deploying.

1// app/api/freight/webhooks/freightos/route.ts
2// NOTE: Freightos webhooks only fire after deployment to Netlify or Bolt Cloud.
3// Bolt's WebContainer has no public URL — Freightos cannot deliver events to it.
4// To test booking status during development, poll GET /api/freight/booking/{id} instead.
5import { NextRequest, NextResponse } from 'next/server';
6import crypto from 'crypto';
7import { createClient } from '@/lib/supabase/server';
8
9function verifyFreightosSignature(secret: string, signature: string, body: string): boolean {
10  // Verify using HMAC-SHA256 — confirm exact algorithm with Freightos documentation
11  const expectedSig = crypto
12    .createHmac('sha256', secret)
13    .update(body)
14    .digest('hex');
15  try {
16    return crypto.timingSafeEqual(
17      Buffer.from(signature, 'hex'),
18      Buffer.from(expectedSig, 'hex')
19    );
20  } catch {
21    return false;
22  }
23}
24
25interface FreightosWebhookEvent {
26  eventType: 'booking.confirmed' | 'booking.in_transit' | 'booking.delivered' | 'booking.cancelled';
27  bookingReference: string;
28  updatedAt: string;
29  details?: Record<string, unknown>;
30}
31
32export async function POST(request: NextRequest) {
33  const webhookSecret = process.env.FREIGHTOS_WEBHOOK_SECRET;
34  if (!webhookSecret) {
35    return NextResponse.json({ error: 'Webhook secret not configured' }, { status: 500 });
36  }
37
38  const rawBody = await request.text();
39  const signature = request.headers.get('X-Freightos-Signature') ?? '';
40
41  if (signature && !verifyFreightosSignature(webhookSecret, signature, rawBody)) {
42    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
43  }
44
45  const event: FreightosWebhookEvent = JSON.parse(rawBody);
46  const supabase = await createClient();
47
48  const statusMap: Record<FreightosWebhookEvent['eventType'], string> = {
49    'booking.confirmed': 'confirmed',
50    'booking.in_transit': 'in_transit',
51    'booking.delivered': 'delivered',
52    'booking.cancelled': 'cancelled',
53  };
54
55  const newStatus = statusMap[event.eventType] ?? 'unknown';
56
57  await supabase
58    .from('freight_bookings')
59    .update({ status: newStatus })
60    .eq('freightos_booking_ref', event.bookingReference);
61
62  console.log(`Freightos webhook: ${event.eventType} for booking ${event.bookingReference}`);
63
64  return NextResponse.json({ received: true });
65}

The freight tracking dashboard brings together all booked shipments and their current status. Operations teams use this view to monitor in-progress shipments, identify delays, and get visibility across all active freight lanes. The dashboard queries your Supabase freight_bookings table for all bookings by the current user or organization. Display them in a table showing booking reference, carrier, route (origin → destination), status badge (color-coded: pending = yellow, confirmed = blue, in_transit = orange, delivered = green, cancelled = gray), cargo details, cost, and booking date. Sort by most recent bookings first. For each confirmed or in-transit booking, add a 'Track Shipment' button that calls the Freightos tracking API: GET /shipments/{bookingReference}/tracking. This returns a list of tracking events (departed origin port, arrived transshipment port, customs clearance, arrived destination port, etc.) with timestamps and locations. Display these as a timeline on a shipment detail page. Carrier-level tracking data is available for some carriers through Freightos but varies by carrier and service type. When carrier tracking is available, Freightos returns real vessel position data including ETA updates. When only carrier milestones are available (not real-time position), display the milestone events as the tracking timeline. For the operations manager view, add summary metrics at the top of the dashboard: total active shipments, shipments in-transit, shipments delivered this month, average transit time, and total freight spend this month. Calculate these from your Supabase bookings table using aggregation queries rather than real-time Freightos API calls — the local data is sufficient for summary metrics and does not consume API rate limit quota. For customers who want real-time tracking updates without refreshing the page, use Supabase Realtime to subscribe to changes in the freight_bookings table. When the webhook handler updates a booking's status, Supabase broadcasts the change to all subscribed clients — the dashboard updates automatically without a page refresh.

1// app/api/freight/tracking/[ref]/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { freightosRequest } from '@/lib/freightos/client';
4
5interface TrackingEvent {
6  timestamp: string;
7  location: string;
8  description: string;
9  eventType: string;
10}
11
12interface FreightosTrackingResponse {
13  bookingReference: string;
14  currentStatus: string;
15  estimatedDelivery?: string;
16  events: TrackingEvent[];
17}
18
19export async function GET(
20  _request: NextRequest,
21  { params }: { params: Promise<{ ref: string }> }
22) {
23  const { ref } = await params;
24
25  if (!ref) {
26    return NextResponse.json({ error: 'Booking reference required' }, { status: 400 });
27  }
28
29  try {
30    const tracking = await freightosRequest<FreightosTrackingResponse>(
31      `/shipments/${encodeURIComponent(ref)}/tracking`
32    );
33
34    return NextResponse.json({
35      bookingReference: tracking.bookingReference,
36      currentStatus: tracking.currentStatus,
37      estimatedDelivery: tracking.estimatedDelivery,
38      events: tracking.events.sort(
39        (a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime()
40      ),
41    });
42  } catch (error) {
43    const message = error instanceof Error ? error.message : 'Tracking unavailable';
44    return NextResponse.json({ error: message }, { status: 500 });
45  }
46}