Package tracking API for Shopify stores

Keep orders, fulfillments and parcels separate

A Shopify order can contain several fulfillments, and a fulfillment can have more than one tracking number. A single order-level status loses that distinction. Store the Shopify order and fulfillment identifiers in your application, then create one Trace shipment record for each parcel cycle.

Use order_id to group those records and reference for the merchant-facing label. Namespaced identifiers such as shop-a:order-1042 avoid accidental collisions when several shops share a Trace account. A new parcel or replacement should receive a new Idempotency-Key, even if a carrier later recycles a number.

Connect Shopify to a server-side tracking workflow

Read tracking information from authenticated Shopify fulfillment data or your shipping integration. Normalize the known carrier to a Trace catalog code; automatic detection recognizes selected formats, rather than every carrier. Keep the Trace key in your server environment. Never place it in a Liquid template, browser script or public theme setting.

Shopify’s supported order-status extension surfaces depend on its customer-account and checkout extension APIs. Choose a supported extension or your own authenticated tracking page rather than assuming a legacy order-status template is editable. The official Shopify reference linked below describes the available target.

• Verify the Shopify event or application request before accepting order data.
• Queue shipment creation from your backend and save the returned Trace shipment ID against the fulfillment.
• Expose only the authorized buyer’s parcels through your own backend; a Trace API key represents your account, not an individual shopper.
• Use shipment.updated, shipment.delivered and shipment.alert events to update a local projection. Verify signatures and deduplicate event IDs.

Example: create an order-linked shipment

This Node.js example belongs in a trusted server job after the tracking number has been obtained from Shopify. Set TRACKING_NUMBER to a real parcel you are authorized to track. The request creates a record; it does not prove delivery or wait for a verified scan.

const number = process.env.TRACKING_NUMBER;
if (!number) throw new Error('Set TRACKING_NUMBER');
const response = await fetch('https://api.traceapi.dev/v1/shipments', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TRACE_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'shop-a-order-1042-fulfillment-1-parcel-1'
  },
  body: JSON.stringify({ tracking_number: number, carrier: 'ups',
    order_id: 'shop-a:order-1042', reference: 'Order #1042',
    metadata: { channel: 'shopify', fulfillment: 'fulfillment-1' } }),
  signal: AbortSignal.timeout(15000)
});
const body = await response.json();
if (!response.ok) throw new Error(body.error?.message || 'Create failed');
console.log(body.shipment.id, body.shipment.last_checked_at);

Make the tracking page answer the buyer’s next question

Show the latest verified status, the carrier’s scan wording, the check time and the relevant parcel. A customer deciding whether to stay home needs a different explanation for out_for_delivery than for customs. When an estimate is absent, omit the promised arrival date instead of calculating one from a generic transit average.

When a lookup fails, explain that tracking is temporarily unavailable. If your backend explicitly requests allow_stale, mark the returned snapshot as older information and retain its original check time. Unknown-timezone events should display their source-local time with a clear label, rather than being silently shifted into the buyer’s timezone.

For example, a support page might show ‘The carrier reports a delivery attempt; check its redelivery instructions’ beside the source scan. It should not automatically refund an order or assert that a parcel is lost based only on a delayed update.

Measure usefulness before expanding the rollout

Compare a small cohort with your existing order-tracking experience. Measure support contacts per shipped order, tracking-page usage, missing carrier results and the age of successful observations. These are evaluation measures, not a promise that installing Trace will reduce tickets by a particular percentage.

Monitoring is best effort, runs for up to 30 days, and uses your lookup quota. Successful cached and explicitly allowed stale lookups also count. A 200-lookup free plan is a development starting point, not 1,000 indefinitely monitored shipments.

• Test multiple real shipments per carrier, including multi-parcel orders, delivery attempts and shipments with no scans.
• Use the sandbox endpoint to test UI states without making carrier requests or consuming monthly lookup quota.
• Handle 429 and 503 separately, bound retries, and inspect webhook delivery history when your receiver fails.
• Keep Shopify fulfillment and payment state separate from inferred shipment alerts.

Common questions

References & next steps

Implementation details were checked against Trace’s current API. External product details may change; verify the linked documentation before deciding.

• Shopify: order-status extension targets
• Trace shipment records and monitoring contract