How to Integrate Lovable with AfterShip

Log in to your AfterShip account at app.aftership.com. In the left navigation, go to Settings → API. You'll see an API Keys section with your organization's API keys listed. Click Create API Key, give it a name (e.g., 'Lovable App'), and click Create. The new API key is displayed once — copy it immediately, as AfterShip doesn't show the full key again after this screen. AfterShip's API uses API key authentication via the 'as-api-key' request header. The current API version is v4 with base URL https://api.aftership.com/v4. AfterShip's API includes endpoints for: POST /trackings (add a new shipment to track), GET /trackings/{slug}/{tracking_number} (get tracking details for a specific shipment), GET /trackings (list all trackings with filtering), DELETE /trackings (remove a tracking), and POST /notifications/.../{tracking_number} (manage customer notifications). AfterShip also provides a Webhook feature where AfterShip sends POST requests to your Edge Function URL whenever a tracking status changes — this is the preferred approach for real-time updates instead of polling. You'll configure the webhook URL in a later step after deploying your Edge Function.

In your Lovable project, click the '+' icon next to the Preview panel to open the Cloud tab. Click Secrets in the left sidebar. Click Add Secret. Set the name to AFTERSHIP_API_KEY and paste your AfterShip API key as the value. Click Save. The key is now encrypted and stored, accessible only from Edge Functions via Deno.env.get('AFTERSHIP_API_KEY'). AfterShip API keys grant full access to your AfterShip account — they can create, read, update, and delete all your trackings. Never expose this key in frontend React code, and never paste it into Lovable's chat prompt. On Lovable's free tier, chat history is publicly visible and API keys pasted there are recoverable from Git commit history. The Cloud Secrets panel is the only secure location for credentials in a Lovable project. Lovable's security system blocks approximately 1,200 hardcoded API keys daily across all projects — the Secrets panel is how you stay protected. If you accidentally expose your API key, rotate it immediately in AfterShip's Settings → API by deleting the old key and creating a new one.

Create the Edge Function that proxies AfterShip API calls and receives AfterShip webhooks. Type the prompt below into Lovable's chat. Lovable will generate the TypeScript at supabase/functions/aftership-proxy/index.ts and deploy it to Cloud. The Edge Function handles four operations based on the 'action' query parameter: 'create' (POST to AfterShip to register a new tracking), 'get' (GET a specific tracking by slug and tracking number), 'list' (GET all trackings with optional filters), and 'webhook' (receive AfterShip webhook POST events and update Supabase). The webhook handler verifies the request is from AfterShip using the webhook secret and updates the relevant order's delivery status in the database. AfterShip sends webhook events as POST requests with a JSON body containing the updated tracking object, including the new tag (Delivered, InTransit, etc.), last event message, and estimated delivery date. The webhook handler extracts these values and updates the corresponding order record in Supabase using the tracking number as the lookup key.

1import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
2import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
3
4const AFTERSHIP_BASE = 'https://api.aftership.com/v4'
5
6const corsHeaders = {
7  'Access-Control-Allow-Origin': '*',
8  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
9}
10
11serve(async (req) => {
12  if (req.method === 'OPTIONS') {
13    return new Response('ok', { headers: corsHeaders })
14  }
15
16  const url = new URL(req.url)
17  const action = url.searchParams.get('action')
18
19  const apiKey = Deno.env.get('AFTERSHIP_API_KEY')
20  if (!apiKey) {
21    return new Response(
22      JSON.stringify({ error: 'AFTERSHIP_API_KEY not configured' }),
23      { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
24    )
25  }
26
27  const aftershipHeaders = {
28    'as-api-key': apiKey,
29    'Content-Type': 'application/json',
30  }
31
32  try {
33    if (action === 'webhook') {
34      const supabase = createClient(
35        Deno.env.get('SUPABASE_URL') ?? '',
36        Deno.env.get('SUPABASE_SERVICE_ROLE_KEY') ?? ''
37      )
38      const body = await req.json()
39      const tracking = body?.msg
40
41      if (tracking?.tracking_number) {
42        await supabase
43          .from('orders')
44          .update({
45            delivery_status: tracking.tag,
46            last_tracking_event: tracking.last_event_time_at,
47            estimated_delivery: tracking.estimated_delivery,
48          })
49          .eq('tracking_number', tracking.tracking_number)
50      }
51
52      return new Response(JSON.stringify({ ok: true }), {
53        headers: { ...corsHeaders, 'Content-Type': 'application/json' },
54      })
55    }
56
57    if (action === 'create') {
58      const body = await req.text()
59      const res = await fetch(`${AFTERSHIP_BASE}/trackings`, {
60        method: 'POST',
61        headers: aftershipHeaders,
62        body,
63      })
64      const data = await res.json()
65      return new Response(JSON.stringify(data), {
66        status: res.status,
67        headers: { ...corsHeaders, 'Content-Type': 'application/json' },
68      })
69    }
70
71    if (action === 'get') {
72      const slug = url.searchParams.get('slug')
73      const trackingNumber = url.searchParams.get('trackingNumber')
74      const res = await fetch(`${AFTERSHIP_BASE}/trackings/${slug}/${trackingNumber}`, {
75        headers: aftershipHeaders,
76      })
77      const data = await res.json()
78      return new Response(JSON.stringify(data), {
79        status: res.status,
80        headers: { ...corsHeaders, 'Content-Type': 'application/json' },
81      })
82    }
83
84    if (action === 'list') {
85      const tag = url.searchParams.get('tag') || ''
86      const page = url.searchParams.get('page') || '1'
87      const limit = url.searchParams.get('limit') || '25'
88      const queryStr = new URLSearchParams({ tag, page, limit }).toString()
89      const res = await fetch(`${AFTERSHIP_BASE}/trackings?${queryStr}`, {
90        headers: aftershipHeaders,
91      })
92      const data = await res.json()
93      return new Response(JSON.stringify(data), {
94        status: res.status,
95        headers: { ...corsHeaders, 'Content-Type': 'application/json' },
96      })
97    }
98
99    return new Response(
100      JSON.stringify({ error: 'Invalid action. Use: create, get, list, or webhook' }),
101      { status: 400, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
102    )
103  } catch (error) {
104    return new Response(
105      JSON.stringify({ error: error.message }),
106      { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
107    )
108  }
109})

With the Edge Function deployed, copy its URL from Cloud → Edge Functions in your Lovable project. Navigate to your AfterShip dashboard at app.aftership.com → Integrations → Webhooks. Click Add Webhook URL and paste your Edge Function URL with '?action=webhook' appended, then click Save. AfterShip will now send POST requests to your Edge Function whenever any tracking status changes. Next, ask Lovable to build the order status dashboard. The tracking timeline displays AfterShip's checkpoints array from the tracking object — each checkpoint has a tag, message, city, state, country, zip, created_at, and subtag_message. The most recent checkpoint is at the top. AfterShip's tag system maps to user-friendly status labels: 'InTransit' → 'In Transit', 'OutForDelivery' → 'Out for Delivery', 'Delivered' → 'Delivered', 'Exception' → 'Delivery Issue'. Color-code these tags for quick visual scanning — green for Delivered, blue for InTransit, orange for OutForDelivery, red for Exception. Test the webhook by creating a tracking for a real shipment and confirming that when AfterShip sends an update, your orders table in Supabase updates accordingly. For complex setups involving multi-carrier workflows or large tracking volumes, RapidDev's team can help design the right database schema and webhook architecture.