How to Integrate Aftership with V0

Open your V0 project and use the chat panel to generate the shipment tracking interface. Be specific about what data you want to display — AfterShip returns a rich tracking object including the current status tag, estimated delivery date, a list of checkpoints with timestamps and locations, carrier name, origin and destination countries, and any exception messages. Describe the layout you want: a search input at the top, a status banner showing the normalized tag (InTransit, Delivered, Exception), and a vertical timeline of checkpoint events. V0 will generate a React component that expects tracking data as props or fetches it from an API endpoint. Make sure to specify /api/aftership/track as the endpoint so the generated code already wires up to the route you will create in the next step. If you want real-time updates, ask V0 to add polling with a 30-second interval using useEffect and setInterval. After V0 generates the component, review it in the preview panel. The UI will use placeholder/mock data since the API route does not exist yet — that is expected. Focus on whether the layout matches your requirements before moving to the backend setup.

Create a new file at app/api/aftership/route.ts in your project. This server-side route receives tracking requests from your frontend, adds your AfterShip API key from the environment, and calls the AfterShip Tracking API. Using a server-side proxy instead of calling AfterShip directly from the browser is essential — it keeps your API key secret and avoids CORS errors since AfterShip's API does not allow direct browser requests. The AfterShip Tracking API v2 endpoint for fetching a single tracking is GET https://api.aftership.com/v4/trackings/{slug}/{tracking_number} where slug is the carrier slug (e.g., fedex, ups, dhl). The API requires an as-api-key header with your secret key. You can also use the newer v2 endpoint at https://api.aftership.com/tracking/2024-10/trackings/{id} — check the AfterShip developer docs for the latest version. The route handler reads the tracking number and carrier from query parameters, constructs the AfterShip API URL, makes an authenticated fetch call, and returns the normalized tracking data to the frontend. Always include error handling for cases where the tracking number is not found (404 from AfterShip) or the API key is invalid (401).

1import { NextRequest, NextResponse } from 'next/server';
2
3export async function GET(request: NextRequest) {
4  const { searchParams } = new URL(request.url);
5  const trackingNumber = searchParams.get('trackingNumber');
6  const carrier = searchParams.get('carrier');
7
8  if (!trackingNumber || !carrier) {
9    return NextResponse.json(
10      { error: 'trackingNumber and carrier are required' },
11      { status: 400 }
12    );
13  }
14
15  const apiKey = process.env.AFTERSHIP_API_KEY;
16  if (!apiKey) {
17    return NextResponse.json(
18      { error: 'AfterShip API key not configured' },
19      { status: 500 }
20    );
21  }
22
23  try {
24    const response = await fetch(
25      `https://api.aftership.com/v4/trackings/${encodeURIComponent(carrier)}/${encodeURIComponent(trackingNumber)}`,
26      {
27        headers: {
28          'as-api-key': apiKey,
29          'Content-Type': 'application/json',
30        },
31      }
32    );
33
34    if (!response.ok) {
35      const error = await response.json();
36      return NextResponse.json(
37        { error: error.meta?.message || 'AfterShip API error' },
38        { status: response.status }
39      );
40    }
41
42    const data = await response.json();
43    return NextResponse.json(data.data.tracking);
44  } catch (error) {
45    console.error('AfterShip API error:', error);
46    return NextResponse.json(
47      { error: 'Failed to fetch tracking data' },
48      { status: 500 }
49    );
50  }
51}

Your AfterShip API key must be stored in Vercel's environment variable system — never hardcoded in your source code or committed to GitHub. To add it, go to your Vercel Dashboard, select your project, navigate to Settings → Environment Variables, and add a new variable. Set the name to AFTERSHIP_API_KEY and paste your AfterShip API key as the value. In the Environment selector, choose All Environments (Production, Preview, Development) so the key works across all deployment contexts. If you want to use different AfterShip accounts for testing versus production, you can set separate values per environment — for example, a test account key for Preview and your main account key for Production. To find your AfterShip API key: log in to the AfterShip Dashboard at app.aftership.com, go to Settings → API Keys (or the API section in the left sidebar), and copy your existing key or generate a new one. AfterShip API keys on the free tier support up to 50 trackings and 100 API calls per month, which is enough for testing. After adding the variable, you must redeploy your Vercel project for the new environment variable to take effect. In V0, click the Deploy button or push a commit to trigger a redeployment.

AfterShip can push tracking status updates to your app via webhooks instead of requiring your app to poll the API. This is useful for triggering shipping notification emails, updating order status in your database, or refreshing a cached tracking page. To receive webhooks, you need a POST endpoint in your Next.js app. Create a webhook route at app/api/aftership/webhook/route.ts. AfterShip sends a POST request to your URL whenever a tracking status changes. The request body is a JSON object containing the tracking details, the new status tag, and the checkpoint event that triggered the update. AfterShip also sends a Hmac-Sha256 signature header (aftership-hmac-sha256) that you should verify to confirm the webhook originated from AfterShip and not from a third party. To configure the webhook in AfterShip: go to the AfterShip Dashboard → Notifications → Webhooks, click Add Webhook, enter your Vercel deployment URL plus /api/aftership/webhook (e.g., https://your-app.vercel.app/api/aftership/webhook), and select which status events to trigger on. AfterShip will send a test payload when you save — check your Vercel Function logs to confirm receipt. For complex webhook processing logic or integrating AfterShip webhooks with downstream systems like email providers or databases, RapidDev's team can help design the full notification pipeline.

1import { NextRequest, NextResponse } from 'next/server';
2import crypto from 'crypto';
3
4export async function POST(request: NextRequest) {
5  const body = await request.text();
6  const signature = request.headers.get('aftership-hmac-sha256');
7  const secret = process.env.AFTERSHIP_WEBHOOK_SECRET;
8
9  // Verify webhook signature if secret is configured
10  if (secret && signature) {
11    const expectedSig = crypto
12      .createHmac('sha256', secret)
13      .update(body)
14      .digest('hex');
15    if (expectedSig !== signature) {
16      return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
17    }
18  }
19
20  const payload = JSON.parse(body);
21  const tracking = payload.msg;
22
23  console.log('AfterShip webhook received:', {
24    trackingNumber: tracking.tracking_number,
25    carrier: tracking.slug,
26    tag: tracking.tag,
27    estimatedDelivery: tracking.expected_delivery,
28  });
29
30  // Add your business logic here:
31  // - Update order status in database
32  // - Send email notification
33  // - Trigger other workflows
34
35  return NextResponse.json({ received: true });
36}

With the UI component, API route, and environment variable all in place, deploy your app to Vercel. In V0, click the Deploy button in the top-right corner of the interface. V0 pushes the code to GitHub and Vercel triggers an automatic build and deployment. The process typically completes in 60-90 seconds. Once deployed, open your live app URL and test the tracking flow with a real tracking number. Use a recent shipment you have the tracking number for — enter the tracking number, select the carrier, and submit the form. The frontend calls /api/aftership/track, which calls the AfterShip API and returns the tracking timeline. You should see the shipment's checkpoint history displayed in the timeline component. If tracking data does not appear, check the Vercel Function Logs: go to your Vercel project → Functions tab → select the aftership route → view recent invocations. Look for error messages about the API key, network errors, or AfterShip API error responses. Common issues include using the wrong carrier slug or an API key from the wrong AfterShip account. AfterShip's free plan allows 50 trackings per month. Each time you call the API with a new tracking number, AfterShip creates a tracking record that counts toward this limit. For production e-commerce apps, you will likely need a paid AfterShip plan.