17TRACK
Test Connection
Validate a 17TRACK API key WITHOUT persisting an instance — powers the connect-modal `Test Connection` button.
Create 17TRACK Instance
Persist the singleton 17TRACK instance for this tenant. The `WebhookRoutable` trait mints a unique `wh_*` token as part of the create flow — the resulting webhook URL is returned in the response so it can be copied into the tenant's 17TRACK dashboard.
Get 17TRACK Instance
Return the 17TRACK instance enriched with the LIVE dashboard summary — quota, per-status counts, the webhook URL, and the most recent webhook + event timestamps. This is the payload that powers the connect dashboard.
Update 17TRACK Instance
Patch any combination of `name`, `api_key`, per-entity `auto_track` toggles, or the `is_automatic_sync_enabled` flag on the singleton instance. All fields are optional; only the keys present in the request body are applied.
Disconnect 17TRACK Instance
Disconnect 17TRACK. Per the PRD edge-case spec:
Get Trackable Channels
List every connected sales channel together with its sub-channels. 17TRACK auto-tracking is scoped per (sales channel, sub-channel) pair — fulfillment type (e.g. Amazon FBA vs merchant-fulfilled, or Shopify Web vs POS) is represented as a sub-channel. Channels with no sub-channels are tracked at the channel level and return an empty `sub_channels` array.
Pull Tracking Updates from 17TRACK
Queue an immediate sync from 17TRACK — the same run as the scheduled poll that happens every 6 hours. It re-fetches the latest status for every active tracking that has been registered with 17TRACK, is not yet in a final state and whose last carrier event is older than 12 hours (or that has no event yet), in batches of 40, updates those trackings, and stamps the instance's last poll time.
Push Pending Tracking Numbers to 17TRACK
Register every pending tracking number with 17TRACK in one run — the manual recovery path when trackings are waiting to be registered. Pending means not yet registered and not stopped: newly created trackings the automatic (debounced) registration has not sent yet, trackings whose earlier registration failed (for example because the 17TRACK quota was used up), and trackings left behind by a temporary 17TRACK error. The background job re-reads the pending set when it runs, so trackings created in the meantime are included.
List Instance Trackings
Paginated list of shipment tracking rows belonging to one 17TRACK integration instance.
List Instance Webhook Events
Paginated audit log of every 17TRACK webhook received for this integration instance — one row per inbound webhook, stored before it is processed. Each row records the event type, tracking number, result, the status transition (`status_from` → `status_to`), processing time and any error message, plus a precomputed `summary` string like 'In Transit → Delivered'.
List Instance Activity Log
Paginated activity log entries for one 17TRACK integration instance: entries about the instance itself (connect, settings update, disconnect) and entries recorded for it by background work (registration, polling, webhooks, backfill, quota alerts). Entries from background work have a null `causer`; actions a user triggered carry that user.
List Shipment Trackings
Paginated cross-entity listing of shipment tracking rows. Powers the Delivery Exceptions view, the global Trackings table, and per-entity filtered subsets.
Get Shipment Tracking
Single tracking row with the FULL event timeline + integration instance descriptor. Powers the per-row timeline detail view in the Delivery Exceptions view and on entity detail pages.
Refresh Shipment Tracking
On-demand refresh — hits 17TRACK's `/gettrackinfo` synchronously and re-hydrates the local row (events, status, sub_status, estimated_delivery_at, etc.). Returns the same shape as `GET /shipment-trackings/{id}` so the timeline detail view can swap the payload in-place.
Register Shipment Tracking
Manual `Track this shipment` trigger from an entity detail page. Resolves the entity, creates a pending `shipment_trackings` row via the manager, and kicks off a background job so the row gets pushed to 17TRACK promptly.
Backfill Shipment Trackings
Kick off a background job that scans recent rows of the selected entity types and registers any that have a `tracking_number` but no `shipment_trackings` row yet.
Re-track Shipment Tracking
Re-activate tracking for an expired or stopped number via 17TRACK's `/retrack` endpoint. 17TRACK auto-stops tracking ~30 idle days after the last event; this asks it to resume pushing updates.
Change Shipment Tracking Carrier
Correct a mis-detected carrier via 17TRACK's `/changecarrier` endpoint and re-hydrate the row under the new carrier. 17TRACK auto-detects the carrier from the number format when registering and sometimes picks wrong — this fixes it without stopping/re-registering.
Register Parcel Trackings (Multi-Parcel)
Register additional parcel tracking numbers against ONE entity — the multi-parcel path for shipments split across several cartons (each with its own carrier number). The entity's primary `tracking_number` is registered by the save observer; this endpoint covers the remaining boxes so every carton tracks independently.
7TRACK Webhook (TRACKING_UPDATED)
**This endpoint is INCOMING — it is called by 17TRACK, not by SKU.io clients. Documented here for reference only.**