How to Build a Shipping Integration with Lovable

1Create a shipping integration schema in Supabase:
2
31. Create a private Storage bucket named 'shipping-labels' with public: false, file size limit 5MB, allowed MIME types: application/pdf
4
52. Database tables:
6   - addresses: id, user_id, label (text, e.g. 'Warehouse A'), name, company, street1, street2, city, state, zip, country (default 'US'), phone, is_verified (bool default false), created_at
7   - shipments: id, user_id, origin_address_id, destination_address_id, carrier (text), service (text), tracking_number (text, unique), status (pre_transit|in_transit|out_for_delivery|delivered|failure|cancelled), label_url (text, storage path), rate_amount (numeric), currency (text default 'USD'), easypost_shipment_id (text), easypost_tracker_id (text), estimated_delivery_date (date), created_at, updated_at
8   - tracking_events: id, shipment_id, status (text), description (text), location (text), carrier_timestamp (timestamptz), received_at
9   - rates_cache: id, cache_key (text, unique), rates_json (jsonb), origin_zip, destination_zip, weight_oz, cached_at, expires_at
10   - parcels: id, user_id, label (text), length_in (numeric), width_in (numeric), height_in (numeric), weight_oz (numeric), is_default (bool default false)
11
123. RLS:
13   - addresses: users own their rows
14   - shipments: users own their rows
15   - tracking_events: users can SELECT where shipment_id is in their shipments. Service role for INSERT.
16   - rates_cache: service role only
17   - parcels: users own their rows
18
194. Storage RLS for shipping-labels:
20   - SELECT: auth.uid()::text = (storage.foldername(name))[1]
21   - INSERT: auth.uid()::text = (storage.foldername(name))[1]
22
23Add indexes:
24- CREATE INDEX idx_shipments_tracking ON shipments(tracking_number);
25- CREATE INDEX idx_shipments_status ON shipments(user_id, status, created_at DESC);
26- CREATE INDEX idx_rates_cache_key ON rates_cache(cache_key, expires_at);

1// supabase/functions/get-shipping-rates/index.ts
2import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
3import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
4
5const corsHeaders = {
6  'Access-Control-Allow-Origin': '*',
7  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
8  'Content-Type': 'application/json',
9}
10
11serve(async (req: Request) => {
12  if (req.method === 'OPTIONS') return new Response('ok', { headers: corsHeaders })
13
14  const { from_address, to_address, parcel } = await req.json()
15
16  // Generate cache key from normalized inputs
17  const cacheKey = btoa(JSON.stringify([
18    from_address.zip, to_address.zip,
19    parcel.weight, parcel.length, parcel.width, parcel.height
20  ]))
21
22  const supabase = createClient(
23    Deno.env.get('SUPABASE_URL') ?? '',
24    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY') ?? ''
25  )
26
27  // Check cache
28  const { data: cached } = await supabase
29    .from('rates_cache')
30    .select('rates_json')
31    .eq('cache_key', cacheKey)
32    .gt('expires_at', new Date().toISOString())
33    .single()
34
35  if (cached) {
36    return new Response(JSON.stringify({ rates: cached.rates_json, cached: true }), { headers: corsHeaders })
37  }
38
39  // Call EasyPost API
40  const easypostRes = await fetch('https://api.easypost.com/v2/shipments', {
41    method: 'POST',
42    headers: {
43      Authorization: `Basic ${btoa(Deno.env.get('EASYPOST_API_KEY') + ':')}`,
44      'Content-Type': 'application/json',
45    },
46    body: JSON.stringify({
47      shipment: {
48        to_address,
49        from_address,
50        parcel: {
51          weight: parcel.weight,
52          length: parcel.length,
53          width: parcel.width,
54          height: parcel.height,
55        },
56      },
57    }),
58  })
59
60  const shipmentData = await easypostRes.json()
61
62  const rates = (shipmentData.rates ?? []).map((r: any) => ({
63    id: r.id,
64    carrier: r.carrier,
65    service: r.service,
66    rate: parseFloat(r.rate),
67    currency: r.currency,
68    delivery_days: r.delivery_days,
69    delivery_date: r.delivery_date,
70    easypost_shipment_id: shipmentData.id,
71  }))
72
73  // Cache for 30 minutes
74  const expiresAt = new Date(Date.now() + 30 * 60 * 1000).toISOString()
75  await supabase.from('rates_cache').upsert({
76    cache_key: cacheKey,
77    rates_json: rates,
78    origin_zip: from_address.zip,
79    destination_zip: to_address.zip,
80    weight_oz: parcel.weight,
81    cached_at: new Date().toISOString(),
82    expires_at: expiresAt,
83  }, { onConflict: 'cache_key' })
84
85  return new Response(JSON.stringify({ rates, cached: false }), { headers: corsHeaders })
86})

1Create a Supabase Edge Function at supabase/functions/buy-label/index.ts.
2
3Accept POST body: { rate_id: string, easypost_shipment_id: string, origin_address_id: string, destination_address_id: string }
4
5Logic:
61. Authenticate the user via the Authorization header (user-scoped Supabase client)
72. Call EasyPost buy endpoint: POST https://api.easypost.com/v2/shipments/{easypost_shipment_id}/buy with body { rate: { id: rate_id } }
83. From the response, extract: tracking_code, selected_rate (carrier, service, rate, currency), postage_label.label_url (PDF URL), tracker.id
94. Fetch the PDF from label_url: const pdfRes = await fetch(label_url); const pdfBuffer = await pdfRes.arrayBuffer()
105. Store the PDF in Supabase Storage at path: {user_id}/{tracking_code}.pdf using service role client
116. Create a shipments row with: user_id, origin_address_id, destination_address_id, carrier, service, tracking_number, status='pre_transit', label_url (storage path), rate_amount, easypost_shipment_id, easypost_tracker_id
127. Return { shipment_id, tracking_number, label_storage_path, carrier, rate_amount }
13
14Handle errors: if EasyPost returns an error (e.g. rate expired), return 422 with the EasyPost error message so the frontend can prompt the user to refresh rates.

1// supabase/functions/tracking-webhook/index.ts
2import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
3import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
4
5const STATUS_MAP: Record<string, string> = {
6  pre_transit: 'pre_transit',
7  in_transit: 'in_transit',
8  out_for_delivery: 'out_for_delivery',
9  delivered: 'delivered',
10  failure: 'failure',
11  return_to_sender: 'cancelled',
12  cancelled: 'cancelled',
13  error: 'failure',
14  unknown: 'in_transit',
15}
16
17serve(async (req: Request) => {
18  if (req.method !== 'POST') {
19    return new Response('Method not allowed', { status: 405 })
20  }
21
22  const body = await req.text()
23  let event: any
24  try {
25    event = JSON.parse(body)
26  } catch {
27    return new Response('Invalid JSON', { status: 400 })
28  }
29
30  // Only process tracker.updated events
31  if (event.description !== 'tracker.updated') {
32    return new Response('OK', { status: 200 })
33  }
34
35  const tracker = event.result
36  const trackingNumber = tracker?.tracking_code
37  const easypostStatus = tracker?.status
38
39  if (!trackingNumber) return new Response('OK', { status: 200 })
40
41  const supabase = createClient(
42    Deno.env.get('SUPABASE_URL') ?? '',
43    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY') ?? ''
44  )
45
46  const { data: shipment } = await supabase
47    .from('shipments')
48    .select('id')
49    .eq('tracking_number', trackingNumber)
50    .single()
51
52  if (!shipment) return new Response('OK', { status: 200 })
53
54  const normalizedStatus = STATUS_MAP[easypostStatus] ?? 'in_transit'
55
56  // Update shipment status
57  await supabase
58    .from('shipments')
59    .update({ status: normalizedStatus, updated_at: new Date().toISOString() })
60    .eq('id', shipment.id)
61
62  // Insert tracking events
63  const events = (tracker.tracking_details ?? []).slice(-5)
64  if (events.length > 0) {
65    await supabase.from('tracking_events').insert(
66      events.map((e: any) => ({
67        shipment_id: shipment.id,
68        status: e.status,
69        description: e.message,
70        location: [e.tracking_location?.city, e.tracking_location?.state].filter(Boolean).join(', '),
71        carrier_timestamp: e.datetime,
72        received_at: new Date().toISOString(),
73      }))
74    )
75  }
76
77  return new Response('OK', { status: 200 })
78})

1Build the shipping dashboard at src/pages/ShippingDashboard.tsx and a rate comparison flow.
2
31. Dashboard page:
4- Stats row: total shipments today, in transit count, delivered today count, and average shipping cost
5- Shipments DataTable: columns = origin (from address name), destination (to address name + city), carrier+service Badge, tracking number (monospace, copyable), status Badge (color-coded), cost, created date, Actions
6- Status Badge colors: pre_transit=gray, in_transit=blue, out_for_delivery=yellow, delivered=green, failure=red, cancelled=muted
7- Actions DropdownMenu: View Tracking (opens Sheet), Download Label (calls Supabase storage.createSignedUrl for 5 min and triggers download)
8- Filter row: status Select filter, carrier Select filter, date range Popover
9
102. New Shipment flow (multi-step Dialog or separate page):
11- Step 1: address form (from/to). Show saved addresses as Select options. Allow new address entry.
12- Step 2: parcel dimensions form (length, width, height in inches, weight in oz)
13- Step 3: rate comparison - call get-shipping-rates Edge Function, show results as Cards sorted by price. Each card shows carrier logo text, service name, price, delivery days. 'Select' Button highlights the chosen rate.
14- Step 4: confirm and buy - show summary, 'Buy Label' Button calls buy-label Edge Function. Show loading state.
15
163. Tracking Sheet (ShipmentTracking.tsx):
17- Shows shipment header: tracking number, carrier, destination, current status Badge
18- Vertical timeline of tracking_events ordered by carrier_timestamp DESC
19- Each event: colored dot (green for delivered, yellow for in transit, red for failure), status label, description, location, timestamp
20- 'Refresh' Button that re-fetches tracking_events