SapaganDocs sapagan.com

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:

FieldNotes
nameRequired, 1 to 200 characters.
profileId or anonymousIdOne of them is required. An event may name a profile created later in the same batch.
timestampWhen it happened, ISO 8601 with an offset. Without it, the time the API received it.
propertiesA JSON object. Templates and conditions can read it.
dedupeIdOptional. A second event with the same dedupe id is counted as a duplicate and not stored again.
scopeIdMarketplaces 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.