Skip to main content
Events are the heartbeat of a Shipment: every scan, handover, attempt, and delivery. Perform.AI merges events from two sources into one timeline:
  • Carrier events — retrieved automatically from the carrier’s systems once a Shipment has a tracking_number and an assigned carrier. Nothing to do on your side.
  • Manual events — pushed by you via the Create Events API for steps carriers can’t see: warehouse handling, quality checks on returns, refund progress.

​
The event model

Each event in responses and webhooks carries: Event normalization is what makes multi-carrier logic possible: thousands of carrier-specific phrasings map to one standard catalogue of event keys and phases, so event_key: "H10" means “successfully delivered” whoever carried the parcel. Resolve human terms to keys with the event-type tooling, or request the standard key catalogue from your account team.

​
Manual events in one minute

  • Provide a free-text description or a standard_key per event — a standard key slots the event into the normalized taxonomy; if you send both, the key wins.
  • The Shipment must already have a tracking number and carrier.
  • Events are added, never replaced — there is no edit or delete.
  • Three views in responses: latest_event, new_events (the current update cycle — what webhook handlers should act on), and all_events (full history).
Full workflow and validation rules: Create events.