whereparcel

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

Tutorial 10 min read

Integrating a Branded Tracking Page with a Multi-Carrier API (Shopify, WooCommerce, Custom)

How to integrate a branded tracking page on top of an existing e-commerce store using a multi-carrier tracking API. Embedded widget vs dedicated page, platform-specific notes for Shopify and WooCommerce, and a personalization checklist.

WhereParcel Team

A branded tracking page is the post-purchase experience your customer sees instead of the carrier’s website. It keeps them on your domain, lets you control the messaging, and turns a high-intent visit (everyone checks tracking) into a marketing surface.

This guide is about integration, not a from-scratch build. If you already have a Shopify, WooCommerce, or custom store and want to add a branded tracking page on top of a multi-carrier tracking API, this is the playbook.

For a from-scratch tutorial that walks through the page itself, see Building a Branded Tracking Page for Your Store.

The Two Integration Patterns

There are really only two architectures, and they map cleanly to “how invasive do you want to be.”

PatternWhat it isWhen to use
Embedded widgetA small script of your own on an existing page, calling a tracking route on your serverFastest. You keep the page; you add a slot
Dedicated pageA full page on your domain that calls the tracking API server-sideMaximum customization, SEO ownership, full control over upsells and layout

Most teams start with the embedded widget for speed and graduate to a dedicated page once they want analytics, upsells, or A/B testing.

Approach 1 — Embedded Widget (Fastest)

The embedded approach replaces a generic “Click here to track” link with an inline component that renders the timeline directly on your existing page.

<div id="order-tracking" data-number="9400111899223197428490"></div>
<script>
  // Calls YOUR server route (the /api/track route in Approach 2) — never put the WhereParcel key in the browser
  const el = document.getElementById('order-tracking');
  fetch('/api/track?trackingNumber=' + encodeURIComponent(el.dataset.number))
    .then((r) => r.json())
    .then((res) => { el.textContent = res.data?.[0]?.data?.deliveryStatus ?? 'Not found'; });
</script>

WhereParcel keys are server-side only, so the widget calls a small route you host (shown in Approach 2) instead of the API directly. From there it renders status, events, and a delivery ETA in your own markup.

Pros

  • 10-minute integration
  • Lives inside the page you already have — no new URL for customers
  • Works on any HTML page you control, including blog posts and CMS pages

Cons

  • Still needs the small server route from Approach 2
  • Client-side rendering means slightly worse SEO than server-rendered pages
  • A network blip can show a loading spinner

If “branded enough” is “our colors and our logo on the carrier timeline,” this is the right choice.

Approach 2 — Dedicated Branded Tracking Page (Maximum Customization)

For most growing DTC brands, the right long-term answer is a dedicated /track page on your own domain that:

  • Calls the tracking API server-side
  • Renders the same status, events, and ETA — but in your own layout
  • Adds upsell zones, support links, returns flow, and re-order CTAs
  • Owns the URL for SEO and email-link consistency

Architecture

Customer email link
       ↓
yourdomain.com/track/[orderNumber]
       ↓
Server-side API route
       ↓ POST /v2/track
WhereParcel API → 39+ live carriers
       ↓
Server-rendered HTML to customer

Server-Side Code (Node.js / Next.js)

// pages/api/track.js
export default async function handler(req, res) {
  const { trackingNumber } = req.query;
  const headers = {
    'Authorization': `Bearer ${process.env.WP_API_KEY}:${process.env.WP_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).json({ error: 'Unknown tracking number format' });

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

The frontend page (React component, Vue, plain HTML — your choice) consumes this and renders the timeline in your design system.

Platform-Specific Notes

Shopify

Shopify gives you two integration points worth knowing about:

  1. Order Status Page customization — under Settings → Checkout → Order Status, you can add custom HTML/JS. Drop the embedded widget from Approach 1 here (pointing at your own proxy route) to brand the page Shopify already shows after checkout.
  2. Custom page template — create a page like /pages/track, add a custom Liquid template, and call WhereParcel from the theme. For server-side rendering, use a Shopify App or a serverless function (Cloudflare Worker, Vercel route) that proxies to the API.

The Liquid template approach is read-only — for personalized order data, you’ll either hit Shopify’s Order API server-side or use Shopify’s customer login flow to look up the tracking number against the logged-in user.

WooCommerce

WooCommerce is more flexible because it’s PHP and you control the host.

// In your theme's functions.php
add_shortcode('wp_tracking', function ($atts) {
    $atts = shortcode_atts(['number' => '', 'carrier' => ''], $atts);
    $headers = [
        'Authorization' => 'Bearer ' . getenv('WP_API_KEY') . ':' . getenv('WP_SECRET_KEY'),
        'Content-Type' => 'application/json',
    ];
    $carrier = $atts['carrier'];
    if ($carrier === '') { // carrier unknown: ask /v2/detect first (free)
        $det = json_decode(wp_remote_retrieve_body(wp_remote_post('https://api.whereparcel.com/v2/detect', [
            'headers' => $headers,
            'body' => json_encode(['trackingNumber' => $atts['number']]),
        ])), true);
        $cands = $det['data']['candidates'] ?? [];
        usort($cands, fn($a, $b) => $b['specificityScore'] <=> $a['specificityScore']);
        $carrier = $cands[0]['code'] ?? '';
    }
    $body = json_encode([
        'trackingItems' => [
            ['carrier' => $carrier, 'trackingNumber' => $atts['number']]
        ]
    ]);
    $res = wp_remote_post('https://api.whereparcel.com/v2/track', [
        'headers' => $headers,
        'body' => $body,
    ]);
    $data = json_decode(wp_remote_retrieve_body($res), true);
    return render_tracking_html($data); // your function
});

Use [wp_tracking number="..."] in any post or page, or render it inside the WooCommerce order confirmation template.

Custom (React / Next.js / etc.)

Use the dedicated-page architecture above. The only thing platform-specific is the routing — app/track/[number]/page.tsx for Next.js App Router, pages/track/[number].tsx for Pages Router, equivalents for Remix, Nuxt, SvelteKit.

Personalization Checklist

A “branded” page that just shows the carrier’s logo isn’t really branded. Real personalization includes:

  • Your logo and colors in the header
  • Order context (“Your order #1234 — 2 items”) above the timeline
  • Status copy in your voice instead of carrier jargon (“On its way” instead of “Origin sortation acceptance”)
  • Estimated delivery date prominent at the top, not buried in events
  • Support contact link in case something looks wrong
  • Returns flow link for delivered orders
  • Re-order or related products zone for repeat purchase opportunity
  • Mobile-first layout — most tracking checks happen on phones
  • Translated strings if you ship internationally — the tracking API returns events in their original language plus normalized status enums

Multi-Carrier in One Page

The big argument for a multi-carrier API on the branded page is that you don’t have to know in advance which carrier handled the order. With the detect-then-track route above, any number works:

const result = await trackParcel('1Z999AA10123456784'); // UPS
const result2 = await trackParcel('EE123456785US');     // USPS
const result3 = await trackParcel('JJD01234567890');    // DHL

This means one branded page handles every carrier you ship through, including regional carriers like OnTrac and international postal services using the UPU S10 format.

SEO and Performance Notes

A dedicated branded tracking page has SEO upsides — branded “track my order” search queries land on your domain — but only if you handle the basics:

  • Server-render the initial state when possible. Pure client-side rendering means search bots and slow connections see a spinner
  • Cache API responses for 60–300 seconds. Carriers don’t update faster than that anyway
  • Don’t index order-specific URLs (/track/[orderNumber]). Add noindex headers — these pages contain order data
  • Do index the marketing landing version (/track) where customers can paste a number

When to Pick Which

Your situationPick
MVP / pre-launch / one weekend to shipEmbedded widget
Established Shopify store, want polish without a custom buildEmbedded widget on Order Status Page
WooCommerce store, want flexibilityDedicated page via shortcode
Custom store, growth stage, want analytics + upsellsDedicated page, server-rendered
Multiple stores / multi-brandDedicated page with brand parameter

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: #branded-tracking #integration #shopify #woocommerce #ecommerce #personalization #customize