whereparcel

Stuck on integration? Have a question? The developer is standing by.

Tutorial 12 min read

How to Build E-Commerce Shipping Notifications

A step-by-step tutorial for adding automatic package tracking notifications to your e-commerce platform using WhereParcel API and webhooks.

WhereParcel Team

Customers expect to know exactly where their package is at all times. In fact, 93% of online shoppers say shipping tracking is important to their overall shopping experience. In this tutorial, we’ll build a complete shipping notification system using WhereParcel’s API.

What We’ll Build

By the end of this tutorial, you’ll have:

  • Automatic tracking registration when orders ship
  • Automatic status updates via webhooks
  • Email and SMS notifications at key delivery milestones
  • A customer-facing tracking page

Architecture Overview

Order Shipped → Register Tracking → WhereParcel API
                                        ↓
                                    Webhook Events
                                        ↓
                               Your Notification Service
                                   ↓           ↓
                                Email          SMS

Step 1: Register Tracking When Orders Ship

When your fulfillment system marks an order as shipped, register the tracking number with WhereParcel:

async function registerTracking(order) {
  const response = await fetch('https://api.whereparcel.com/v2/track', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.WHEREPARCEL_API_KEY}:${process.env.WHEREPARCEL_SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      trackingItems: [{ carrier: order.carrier, trackingNumber: order.trackingNumber }],
      webhook: {
        url: 'https://yourapp.com/webhooks/tracking',
        events: ['status_changed', 'delivered', 'exception'],
      },
    }),
  });

  return response.json();
}

Step 2: Set Up the Webhook Endpoint

Create an endpoint to receive tracking updates:

app.post('/webhooks/tracking', async (req, res) => {
  // Verify webhook signature
  const signature = req.headers['x-webhook-signature'];
  if (!verifySignature(req.body, signature)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Respond immediately
  res.status(200).json({ received: true });

  // Process the event
  const { event, data } = req.body;
  await handleTrackingEvent(event, data);
});

Step 3: Handle Different Event Types

Map tracking events to customer notifications:

async function handleTrackingEvent(event, data) {
  const order = await findOrderByTracking(data.trackingNumber);
  if (!order) return;

  switch (data.status) {
    case 'picked_up':
      await sendNotification(order.customer, {
        title: 'Your order has been picked up!',
        body: `Your package is on its way from ${data.location}.`,
      });
      break;

    case 'in_transit':
      await sendNotification(order.customer, {
        title: 'Your package is in transit',
        body: `Last seen at ${data.location}.`,
      });
      break;

    case 'out_for_delivery':
      await sendNotification(order.customer, {
        title: 'Out for delivery!',
        body: 'Your package will arrive today.',
      });
      break;

    case 'delivered':
      await sendNotification(order.customer, {
        title: 'Package delivered!',
        body: `Delivered at ${data.location}.`,
      });
      break;

    case 'exception':
      await sendNotification(order.customer, {
        title: 'Delivery update',
        body: `There's an update on your package: ${data.description}`,
      });
      break;
  }
}

Step 4: Build a Tracking Page

Create a customer-facing tracking page that fetches the latest status:

app.get('/track/:trackingNumber', async (req, res) => {
  const { trackingNumber } = req.params;
  const headers = {
    'Authorization': `Bearer ${process.env.WHEREPARCEL_API_KEY}:${process.env.WHEREPARCEL_SECRET_KEY}`,
    'Content-Type': 'application/json',
  };

  // Find the carrier first — /v2/detect is free (format matching, no lookup)
  const detect = await fetch('https://api.whereparcel.com/v2/detect', {
    method: 'POST', headers, body: JSON.stringify({ trackingNumber }),
  }).then((r) => r.json());
  const [best] = detect.data.candidates.sort((a, b) => b.specificityScore - a.specificityScore);
  if (!best) return res.status(404).render('tracking-not-found');

  const tracking = await fetch('https://api.whereparcel.com/v2/track', {
    method: 'POST',
    headers,
    body: JSON.stringify({
      trackingItems: [{ carrier: best.code, trackingNumber }],
    }),
  });

  const result = await tracking.json();
  res.render('tracking', { tracking: result.data[0] });
});

Step 5: Add Notification Preferences

Let customers choose how they want to be notified:

const notificationPreferences = {
  email: true,      // Always on by default
  sms: false,       // Opt-in
  push: false,      // Opt-in
  milestones: [     // Which events to notify
    'picked_up',
    'out_for_delivery',
    'delivered',
    'exception',
  ],
};

Best Practices

  1. Don’t over-notify — Customers don’t need an update for every sorting facility. Focus on key milestones: picked up, out for delivery, delivered, and exceptions.

  2. Include tracking links — Every notification should link to your tracking page where customers can see the full timeline.

  3. Handle carrier delays — If a package hasn’t moved in 48+ hours, proactively notify the customer rather than leaving them wondering.

  4. Time zone awareness — Send notifications during the recipient’s business hours when possible.

  5. Batch international updates — International shipments can have many events. Batch them into daily summaries rather than sending individual notifications.

Next Steps

Can't find your carrier? We add new carriers on request — just let us know.

Request a carrier →

Got a question? Just ask. Drop by our Discord — the developer behind WhereParcel reads every message and replies personally. No bots, no tickets, just a real conversation.

Join Discord → Join Slack →

Tags: #ecommerce #notifications #webhooks #tutorial