External Tracking Ingestion: Admin Overview

How external tracking numbers are ingested, how conflicts and fees are handled, and where admins can manage settings, failures, and alerts.

Overview

Clients can fulfill an order outside your warehouse and push the tracking number back to us through several channels. All of these paths funnel into a single ingestion pipeline that handles idempotency, conflict detection, label cancellation, and inventory/fee side effects.

Inbound channels

External tracking can be submitted via:

  • Public webhook with HMAC v2 signing (timestamp + nonce, replay-protected)
  • REST API: POST /v1/orders/{id}/tracking
  • Marketplace fulfillment polling
  • Shopify today
  • Amazon, eBay, Etsy follow the same pattern
  • Manual entry from the order detail page (admin or client)

All of these call the same internal function: ingest-external-tracking.

---

What happens on ingest

When an external tracking event comes in, the system runs the following steps:

  1. Resolve the order
  • Match by order_id or by external_order_id + client_id.
  1. Cancel any pending warehouse label
  • If the order has a pending label in your shipping software, we attempt to cancel it.
  1. Detect conflicts with printed labels
  • If a label was already purchased / printed, we do not mark the order as shipped.
  • Instead, we:
  • Raise an external_tracking_conflict issue.
  • Notify ops via Slack/email.
  1. Apply external fulfillment side effects (when no conflict)
  • Record the tracking row.
  • Set fulfilled_externally = true.
  • Release inventory reservations.
  • Zero out pick, pack, and postage fees for that order.

Idempotency and duplicate handling (for example, marketplace sending the same tracking again) are owned by this same ingestion function.

---

Where to manage it

Settings → Integrations → External tracking webhook

From this page you can control tenant-wide behavior for external tracking: