How to Integrate Bolt.new with Shippo

Go to goshippo.com and create a free account. After signing in, navigate to the API section in your dashboard — usually found under Settings → API Keys or directly at app.goshippo.com/api. Shippo provides two tokens: a test token (prefixed with 'shippo_test_') and a live token (prefixed with 'shippo_live_'). Use the test token during development — it generates real rate quotes from carriers but creates dummy labels rather than actual billable shipments. This means you can build and test the entire integration without incurring any label costs. The test token's rate quotes are real carrier rates, so your pricing UI will look exactly like production. Switch to the live token only when you are ready to create real, purchasable labels. Add SHIPPO_API_TOKEN to your .env file using the test token. Also add VITE_SHIPPO_API_TOKEN if you need to reference it in client-side code for display purposes (such as showing the API environment in a dev indicator) — but never use this for actual API calls. Create a lib/shippo.ts helper that wraps fetch calls to Shippo's API with the Authorization header, base URL, and error handling. Shippo's base URL is https://api.goshippo.com and all endpoints are lowercase REST paths. The API version is specified via the Shippo-API-Version header (use '2018-02-08' for the stable version). Shippo's error responses include an array-style error message — handle these in your wrapper function.

1// lib/shippo.ts
2export async function shippoRequest<T>(
3  endpoint: string,
4  options: RequestInit = {}
5): Promise<T> {
6  const token = process.env.SHIPPO_API_TOKEN;
7
8  const response = await fetch(`https://api.goshippo.com${endpoint}`, {
9    ...options,
10    headers: {
11      'Authorization': `ShippoToken ${token}`,
12      'Shippo-API-Version': '2018-02-08',
13      'Content-Type': 'application/json',
14      ...(options.headers || {}),
15    },
16  });
17
18  if (!response.ok) {
19    const errorText = await response.text();
20    throw new Error(`Shippo API error ${response.status}: ${errorText}`);
21  }
22
23  return response.json() as Promise<T>;
24}

Shippo's rate comparison requires creating a Shipment object — the core resource in Shippo's API. A Shipment object contains the address_from (sender), address_to (recipient), parcels (dimensions and weight), and optionally carrier_accounts to restrict which carriers return rates. When you create a Shipment, Shippo automatically contacts all enabled carriers and returns an array of Rate objects. Each Rate includes: provider (e.g., 'USPS'), servicelevel.name (e.g., 'Priority Mail'), amount (price as a string), currency, estimated_days, and object_id (the rate ID you use to purchase a label). The shipment creation endpoint is POST /shipments. Addresses can be inline objects in the shipment creation request, or you can pre-create Address objects and reference them by ID for reuse. For the rate calculator, use inline addresses for simplicity. Parcel dimensions use the Parcel object: length, width, height (in inches by default), and weight (in ounces or pounds depending on your setting). Shippo returns asynchronously for some carriers — if the status field of the Shipment is 'QUEUED' rather than 'SUCCESS', poll the GET /shipments/:object_id endpoint until status becomes 'SUCCESS' and rates are populated. In practice, most modern carrier connections return synchronously. During development in Bolt's WebContainer, all outbound API calls to Shippo work correctly. You can test rate comparison with real addresses and real carrier rates without leaving the Bolt preview.

1// app/api/shipping/rates/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { shippoRequest } from '@/lib/shippo';
4
5interface ShippoRate {
6  object_id: string;
7  provider: string;
8  servicelevel: { name: string };
9  amount: string;
10  currency: string;
11  estimated_days: number;
12}
13
14interface ShippoShipment {
15  object_id: string;
16  status: string;
17  rates: ShippoRate[];
18}
19
20export async function POST(request: NextRequest) {
21  const { recipientName, addressLine1, city, state, zip, country, weightLbs, lengthIn, widthIn, heightIn } =
22    await request.json();
23
24  const shipment = await shippoRequest<ShippoShipment>('/shipments', {
25    method: 'POST',
26    body: JSON.stringify({
27      address_from: {
28        name: 'Your Business Name',
29        street1: '123 Main St', // Replace with your sender address
30        city: 'San Francisco',
31        state: 'CA',
32        zip: '94105',
33        country: 'US',
34      },
35      address_to: {
36        name: recipientName,
37        street1: addressLine1,
38        city,
39        state,
40        zip,
41        country: country || 'US',
42      },
43      parcels: [
44        {
45          length: String(lengthIn),
46          width: String(widthIn),
47          height: String(heightIn),
48          distance_unit: 'in',
49          weight: String(weightLbs),
50          mass_unit: 'lb',
51        },
52      ],
53      async: false, // Wait for all rates synchronously
54    }),
55  });
56
57  const rates = (shipment.rates || []).map((rate) => ({
58    objectId: rate.object_id,
59    provider: rate.provider,
60    serviceName: rate.servicelevel.name,
61    amount: parseFloat(rate.amount),
62    currency: rate.currency,
63    estimatedDays: rate.estimated_days,
64  }));
65
66  // Sort by price ascending
67  rates.sort((a, b) => a.amount - b.amount);
68
69  return NextResponse.json({ rates, shipmentId: shipment.object_id });
70}

Once a rate is selected (either by the customer or automatically), purchase the label by POSTing the rate's object_id to Shippo's /transactions endpoint. A Transaction in Shippo represents a purchased label. The response includes the label_url (a direct URL to download the label as PDF or PNG), tracking_number, tracking_url_provider (the carrier's tracking page), and status. Label status transitions are: QUEUED → WAITING → SUCCESS (or ERROR if something went wrong). For most carriers, the label is generated synchronously when async: false is passed. Store the tracking_number and label_url in your Supabase order record for future reference. For tracking status updates after deployment, Shippo supports webhooks that POST to your app when a package's tracking status changes. Register your webhook URL in the Shippo dashboard under API → Webhooks. During development in Bolt's WebContainer, incoming tracking webhooks cannot reach the browser-based runtime because the WebContainer has no public URL — this is a fundamental limitation of Bolt's development environment. Use the tracking poll API (GET /tracks/:carrier/:tracking_number) during development, and set up proper webhooks after deploying to Netlify or Vercel. When you do deploy, webhooks will fire to your production URL when packages are scanned at carrier facilities, updating order status in real time.

1// app/api/shipping/label/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { shippoRequest } from '@/lib/shippo';
4import { createClient } from '@supabase/supabase-js';
5
6interface ShippoTransaction {
7  status: string;
8  tracking_number: string;
9  label_url: string;
10  tracking_url_provider: string;
11  messages: Array<{ text: string }>;
12}
13
14export async function POST(request: NextRequest) {
15  const { rateObjectId, orderId } = await request.json();
16
17  const transaction = await shippoRequest<ShippoTransaction>('/transactions', {
18    method: 'POST',
19    body: JSON.stringify({
20      rate: rateObjectId,
21      label_file_type: 'PDF',
22      async: false,
23    }),
24  });
25
26  if (transaction.status !== 'SUCCESS') {
27    const messages = transaction.messages?.map((m) => m.text).join('; ');
28    return NextResponse.json({ error: `Label creation failed: ${messages}` }, { status: 400 });
29  }
30
31  // Update Supabase order with tracking info
32  if (orderId) {
33    const supabase = createClient(
34      process.env.NEXT_PUBLIC_SUPABASE_URL!,
35      process.env.SUPABASE_SERVICE_ROLE_KEY!
36    );
37    await supabase
38      .from('orders')
39      .update({
40        tracking_number: transaction.tracking_number,
41        label_url: transaction.label_url,
42        carrier_tracking_url: transaction.tracking_url_provider,
43        status: 'label_created',
44      })
45      .eq('id', orderId);
46  }
47
48  return NextResponse.json({
49    trackingNumber: transaction.tracking_number,
50    labelUrl: transaction.label_url,
51    trackingUrl: transaction.tracking_url_provider,
52  });
53}

Your Bolt.new app's shipping rate comparison and label creation features work completely in the WebContainer preview — Shippo's API calls are all outbound HTTP, which Bolt's WebContainer handles without issues. The one feature that requires deployment first is Shippo's tracking webhooks. Webhooks are HTTP POST requests that Shippo sends to your app when a package's tracking status changes — for example, when USPS scans the package at a sorting facility. These incoming webhooks cannot reach Bolt's WebContainer during development because the browser-based runtime has no public URL accessible from the internet. To set up tracking webhooks: first deploy your app to Netlify via Bolt's Settings → Applications. After deployment, copy your Netlify URL. In the Shippo dashboard (app.goshippo.com), go to API → Webhooks and click 'Add a Webhook'. Enter your webhook URL (e.g., https://your-app.netlify.app/api/shipping/webhook), select the event type 'track_updated', and save. Create the webhook handler route in Bolt before deploying. The webhook payload from Shippo includes the tracking number, carrier, status, substatus, and an events array. Use Supabase's service role key (not the anon key) in your webhook handler to update order records without requiring user authentication. After deployment, set SHIPPO_API_TOKEN and SUPABASE_SERVICE_ROLE_KEY as environment variables in Netlify's Site Configuration → Environment Variables and redeploy.

1// app/api/shipping/webhook/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { createClient } from '@supabase/supabase-js';
4
5const supabase = createClient(
6  process.env.NEXT_PUBLIC_SUPABASE_URL!,
7  process.env.SUPABASE_SERVICE_ROLE_KEY!
8);
9
10export async function POST(request: NextRequest) {
11  const payload = await request.json();
12
13  // Shippo tracking webhook payload structure
14  const trackingNumber = payload.data?.tracking_number;
15  const carrier = payload.data?.carrier;
16  const status = payload.data?.tracking_status?.status; // PRE_TRANSIT, TRANSIT, DELIVERED, RETURNED, FAILURE, UNKNOWN
17  const statusDetails = payload.data?.tracking_status?.status_details;
18  const estimatedDelivery = payload.data?.eta;
19
20  if (!trackingNumber) {
21    return NextResponse.json({ received: true });
22  }
23
24  // Update the order in Supabase
25  await supabase
26    .from('orders')
27    .update({
28      shipping_status: status,
29      shipping_status_details: statusDetails,
30      estimated_delivery: estimatedDelivery,
31      last_tracking_update: new Date().toISOString(),
32    })
33    .eq('tracking_number', trackingNumber);
34
35  return NextResponse.json({ received: true });
36}