> ## Documentation Index
> Fetch the complete documentation index at: https://developers.perform.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> How tracking events work in Perform.AI — carrier events, manual events, and the standard event model.

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](/guides/create-events) for steps carriers can't see: warehouse handling, quality checks on returns, refund progress.

## The event model

Each event in responses and webhooks carries:

| Field                 | Meaning                                                                                                                       |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `event`               | The description — Perform.AI's standard English text, or the original carrier text when unmapped.                             |
| `event_key`           | The standard event key the event maps to (e.g. `H10` — Successfully delivered), when mapped.                                  |
| `phase` / `phase_key` | The delivery [phase](/concepts/statuses-and-phases) the event belongs to.                                                     |
| `time` + `timezone`   | When it happened — precision reflects what the source provided; see [timestamps](/essentials/timestamps).                     |
| `location`            | Where — a `place` string (enriched to a full address object with coordinates in v5.2 responses and webhook format 5.2+).      |
| `carrier_name`        | The carrier the event came from — relevant with [linked shipments](/concepts/shipments), whose events merge into one history. |

**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](/guides/create-events).