Audience: Business Systems Analysts/Engineers, operations leaders, internal support users.

Status: Dev/sandbox implementation, verified end-to-end. Not production.

Owner: Operations Team

Business purpose

When a support agent puts a carrier tracking number on a Zendesk ticket, this system automatically creates a shipment record in Zendesk, keeps its status and scan history current by polling FedEx and UPS on a schedule, and surfaces failures to operations — so agents see live delivery status inside Zendesk without manual lookups or copy-paste from carrier websites.

The system of record is Zendesk Custom Objects (not a separate database). Orchestration runs on local n8n (four workflows), deployed from version-controlled workflow definitions. All carrier calls run against carrier sandboxes; all Zendesk work targets a dev instance.

Scope

In scope

• Ticket-driven ingestion: a tracking number on a ticket creates and links a carrier_shipment.
• Scheduled refresh of active shipments from FedEx + UPS, with normalized status and append-only scan events.
• Idempotent writes (no duplicate shipments or events on re-run).
• Terminal-state handling (delivered/returned stop being polled) and 90-day retention pruning.
• Failure surfacing via a shared error workflow and per-shipment error flagging.

Out of scope

• Production Zendesk and production carrier endpoints (explicitly excluded by policy).
• Carriers other than FedEx and UPS.
• Customer-facing notifications or branded tracking pages.
• Carrier push/webhook updates (polling only in this iteration).

Functional behavior

Context