Concepts
Events
What people do, recorded with a name, a time and properties.
An event is something a person did: order_placed, Screen Viewed, cart_abandoned. Events feed segments, journeys and reports.
An event item in POST /v1/batch has these fields:
| Field | Notes |
|---|---|
name | Required, 1 to 200 characters. |
profileId or anonymousId | One of them is required. An event may name a profile created later in the same batch. |
timestamp | When it happened, ISO 8601 with an offset. Without it, the time the API received it. |
properties | A JSON object. Templates and conditions can read it. |
dedupeId | Optional. A second event with the same dedupe id is counted as a duplicate and not stored again. |
scopeId | Marketplaces only: tags the event with a store. A store sees only events tagged with its own id. |
{
"type": "event",
"profileId": "user-42",
"name": "order_placed",
"timestamp": "2026-11-17T09:30:00+07:00",
"properties": { "total": 150000, "items": 3 },
"dedupeId": "order-1042"
}The batch response has summary.events with received, inserted, duplicates, clamped and backfilled counts. Duplicates show only in the summary, because one insert cannot say which row was skipped.
Screens and sessions#
The SDKs send screen(name) as the event Screen Viewed with the property screen. In-app messages use screens and events as triggers. See Flutter.
Using events#
- A journey can start when an event arrives.
- A segment can match people who did or did not do an event.
- A transactional send can be skipped when the person had any event in the last N seconds (
skipIfActiveWithinSeconds). See Transactional messages.
Events are erased with the person. Old events are dropped by retention.