How to Integrate Shippo with V0

Start by prompting V0 to generate the frontend components for your shipping workflow. Depending on your use case, this could be a rate comparison table for checkout, a label generation form for internal fulfillment, or a tracking status display for customer-facing pages. V0 excels at creating structured data displays like rate comparison tables, and it can wire up the fetch calls to your API routes with the right request format. When writing your V0 prompt, specify the exact API endpoint paths the components should call. This ensures V0 generates the correct fetch() calls without you having to edit the component code manually afterward. For a rate comparison component, the key input fields are: sender address (city, state, ZIP, country), recipient address, and parcel details (weight in ounces, and dimensions in inches). These map directly to Shippo's API request format. After V0 generates the component, check that it handles both the loading state and the error state. Shipping rate API calls typically take 2-4 seconds because Shippo queries multiple carriers in parallel, so a loading skeleton or spinner is important for user experience. Also verify the component passes all required address and parcel fields in the POST body — missing fields are the most common cause of Shippo API errors in V0-generated code. One V0-specific consideration: V0 may generate the rate display with hardcoded mock data initially. If so, ask V0 to replace the mock data with a real fetch call to your API route. V0 sometimes defaults to static data when building UI components before the API layer exists.

Create the server-side API route that fetches shipping rates from Shippo. In your V0 project, create the file app/api/shippo/route.ts. This route accepts a POST request with the shipment details, calls the Shippo REST API to get rates, and returns the carrier options to the frontend. Shippo's API uses a simple REST structure. You first create a Shipment object (sender address, recipient address, parcel) and Shippo returns available rates from all configured carriers. The API uses your Shippo API token in an Authorization header with the format: Shippo <your_token>. Note the capital S and the space — this is different from the more common Bearer token format. The key decision in this route is whether to use Shippo's npm package (shippo) or call the REST API directly with fetch(). The npm package adds a dependency but provides TypeScript types and simpler method calls. For straightforward rate fetching, calling the REST API directly with fetch() keeps your bundle lean and avoids package version conflicts. The route shown below uses the direct REST approach. Important: Shippo rate requests are asynchronous. When you create a Shipment, you get back an object with a rates array. If the rates array is empty, it may mean the carriers have not finished responding yet — Shippo recommends checking the status field. For real-time use cases, you can use Shippo's synchronous mode by adding async: false to the request, which waits for all carriers to respond before returning. This increases latency but simplifies your code significantly. For most V0 apps, the synchronous approach is recommended.

1import { NextRequest, NextResponse } from 'next/server';
2
3interface ShippoRate {
4  object_id: string;
5  provider: string;
6  servicelevel: { name: string; token: string };
7  amount: string;
8  currency: string;
9  estimated_days: number;
10  duration_terms: string;
11}
12
13interface ShippoShipmentResponse {
14  rates: ShippoRate[];
15  status: string;
16  messages: Array<{ code: string; text: string }>;
17}
18
19export async function POST(request: NextRequest) {
20  try {
21    const { fromZip, toZip, weightOz, lengthIn, widthIn, heightIn } =
22      await request.json();
23
24    if (!fromZip || !toZip || !weightOz) {
25      return NextResponse.json(
26        { error: 'fromZip, toZip, and weightOz are required' },
27        { status: 400 }
28      );
29    }
30
31    const shippoResponse = await fetch('https://api.goshippo.com/shipments/', {
32      method: 'POST',
33      headers: {
34        Authorization: `Shippo ${process.env.SHIPPO_API_TOKEN}`,
35        'Content-Type': 'application/json',
36      },
37      body: JSON.stringify({
38        address_from: {
39          zip: fromZip,
40          country: 'US',
41        },
42        address_to: {
43          zip: toZip,
44          country: 'US',
45        },
46        parcels: [
47          {
48            length: String(lengthIn || 10),
49            width: String(widthIn || 8),
50            height: String(heightIn || 4),
51            distance_unit: 'in',
52            weight: String(weightOz),
53            mass_unit: 'oz',
54          },
55        ],
56        async: false,
57      }),
58    });
59
60    if (!shippoResponse.ok) {
61      const errorData = await shippoResponse.text();
62      console.error('Shippo API error:', errorData);
63      return NextResponse.json(
64        { error: 'Failed to fetch shipping rates' },
65        { status: shippoResponse.status }
66      );
67    }
68
69    const data: ShippoShipmentResponse = await shippoResponse.json();
70
71    // Sort rates by price ascending
72    const sortedRates = data.rates
73      .filter((rate) => rate.amount)
74      .sort((a, b) => parseFloat(a.amount) - parseFloat(b.amount));
75
76    return NextResponse.json({ rates: sortedRates });
77  } catch (error) {
78    console.error('Shippo route error:', error);
79    return NextResponse.json(
80      { error: 'Internal server error' },
81      { status: 500 }
82    );
83  }
84}

If your app needs to purchase actual shipping labels (not just display rates), create a separate route at app/api/shippo/label/route.ts. This route accepts the rate object ID from the rates endpoint and calls Shippo's transactions endpoint to purchase the label. Purchasing a label in Shippo's API is called creating a Transaction. You pass the rate's object_id (the unique ID of the specific carrier/service/price combination you want to purchase) and Shippo charges your Shippo account or your connected carrier account for the label cost. The response includes a label_url (a PDF link) and a tracking_number. Label purchases are real charges in production (using your live Shippo token). In test mode (using shippo_test_ tokens), label creation returns realistic-looking but non-functional label URLs and tracking numbers — this is perfect for testing your UI flow without incurring costs. The test/production switch is entirely controlled by which API token you use. An important operational consideration for label purchase in V0 apps: you should record the transaction ID and label URL in your database immediately after creation. Labels cannot be easily re-fetched later without storing the transaction ID. If the database write fails after the label is purchased, you will have charged the carrier account but lost the label URL. Consider wrapping the label purchase and database write in a try-catch that logs failures for manual recovery. For refunds: carriers have different windows for label refund eligibility (USPS: 28 days if never scanned, UPS/FedEx: 15-30 days). Shippo's API has a refund endpoint at /transactions/{id}/refund, but you will need to build that flow separately if your app needs it.

1import { NextRequest, NextResponse } from 'next/server';
2
3interface ShippoTransaction {
4  object_id: string;
5  status: string;
6  label_url: string;
7  tracking_number: string;
8  tracking_url_provider: string;
9  messages: Array<{ code: string; text: string; source: string }>;
10}
11
12export async function POST(request: NextRequest) {
13  try {
14    const { rateObjectId } = await request.json();
15
16    if (!rateObjectId) {
17      return NextResponse.json(
18        { error: 'rateObjectId is required' },
19        { status: 400 }
20      );
21    }
22
23    const shippoResponse = await fetch('https://api.goshippo.com/transactions/', {
24      method: 'POST',
25      headers: {
26        Authorization: `Shippo ${process.env.SHIPPO_API_TOKEN}`,
27        'Content-Type': 'application/json',
28      },
29      body: JSON.stringify({
30        rate: rateObjectId,
31        label_file_type: 'PDF',
32        async: false,
33      }),
34    });
35
36    if (!shippoResponse.ok) {
37      const errorData = await shippoResponse.text();
38      console.error('Shippo label error:', errorData);
39      return NextResponse.json(
40        { error: 'Failed to purchase label' },
41        { status: shippoResponse.status }
42      );
43    }
44
45    const transaction: ShippoTransaction = await shippoResponse.json();
46
47    if (transaction.status !== 'SUCCESS') {
48      const errorMessages = transaction.messages
49        .map((m) => m.text)
50        .join(', ');
51      return NextResponse.json(
52        { error: `Label creation failed: ${errorMessages}` },
53        { status: 422 }
54      );
55    }
56
57    return NextResponse.json({
58      labelUrl: transaction.label_url,
59      trackingNumber: transaction.tracking_number,
60      trackingUrl: transaction.tracking_url_provider,
61      transactionId: transaction.object_id,
62    });
63  } catch (error) {
64    console.error('Shippo label route error:', error);
65    return NextResponse.json(
66      { error: 'Internal server error' },
67      { status: 500 }
68    );
69  }
70}

Your API routes read SHIPPO_API_TOKEN from environment variables. You need to add this to Vercel so the serverless functions can authenticate with Shippo's API. Go to your Vercel Dashboard and open your project. Click the Settings tab at the top, then click Environment Variables in the left sidebar. In the form, enter the key name as SHIPPO_API_TOKEN and paste your Shippo API token as the value. Your test token starts with shippo_test_ and your live token starts with shippo_live_ — they are found in goshippo.com → API → API Keys. Do not add a NEXT_PUBLIC_ prefix to this variable. The Shippo API token is a server-side secret that should never be exposed in the browser's JavaScript bundle. Only your Next.js API routes running on Vercel's serverless infrastructure will access this variable. Set the environment scope to Production, Preview, and Development so the variable is available across all deployment contexts. After adding the variable, click Save. You need to trigger a redeployment — push any commit to your GitHub repository — for the environment variable to become available in your functions. For local development, create a .env.local file in your project root and add SHIPPO_API_TOKEN=shippo_test_your_token_here. This file should already be in your .gitignore in V0-generated projects. The .env.local file is never sent to Vercel — it exists only on your local machine for development. Shippo has two completely separate token environments: test mode and live mode. Test tokens simulate all API calls without real carrier communication or charges. When you are ready to go live, update the SHIPPO_API_TOKEN in Vercel to your live token and redeploy.

With your environment variable configured and your V0 app deployed to Vercel, test the complete shipping flow end-to-end. Navigate to the page with your V0-generated shipping rate component, enter a real origin ZIP code, a destination ZIP code, and a package weight, then click Get Rates. In test mode, Shippo returns realistic rates from USPS, UPS, and FedEx. The rates reflect real pricing logic but no actual carrier accounts are needed or charged. A typical rate request returns 5-15 service options across carriers, ranging from inexpensive ground services to expedited overnight options. Verify the response structure by checking your Vercel function logs. Go to your Vercel Dashboard, click your project, then Functions, then the log for your /api/shippo/route. You should see the incoming request body and the Shippo API response. If the rates array is empty, check that your Authorization header is formatted as Shippo <token> (with a capital S and a space, not Bearer). For production readiness, you will need a Shippo account with carrier accounts connected. For USPS, Shippo provides a shared USPS account that works automatically — you get Shippo's negotiated USPS rates without needing your own USPS business account. For UPS and FedEx, you need to connect your own carrier accounts in goshippo.com → Carriers → Connect Carrier. This is a one-time setup step. For complex shipping workflows — including international shipments with customs forms, multi-package shipments, or return label flows — RapidDev's team can help configure the full integration with your V0 app.