Event Reference - RetainPixel Docs

Common Properties

Every event includes these common fields:

Field	Type	Required	Description
event	string	Yes	Event name (e.g., 'feature_used')
anonymous_id	string	Yes	Device-generated anonymous identifier
user_id	string	No	Your application's user ID (set via identify)
timestamp	ISO 8601	Yes	When the event occurred
context	object	No	Contextual metadata (browser, OS, locale)

Event Types

track

A custom event representing a user action.

Field	Type	Required	Description
event	string	Yes	Event name
anonymous_id	string	Yes	Anonymous device ID
user_id	string	No	Identified user ID
properties	object	No	Custom event properties

json

{
  "type": "track",
  "event": "feature_used",
  "anonymous_id": "abc-123",
  "user_id": "user-456",
  "properties": {
    "feature": "export",
    "format": "csv"
  },
  "timestamp": "2026-03-10T12:00:00Z"
}

identify

Associates a user ID with traits like email, plan, or custom attributes.

Field	Type	Required	Description
user_id	string	Yes	Your application user ID
anonymous_id	string	No	Links anonymous to known user
traits	object	No	User traits (email, plan, etc.)

json

{
  "type": "identify",
  "user_id": "user-456",
  "anonymous_id": "abc-123",
  "traits": {
    "email": "user@example.com",
    "plan": "pro"
  },
  "timestamp": "2026-03-10T12:00:00Z"
}

group

Associates a user with a group (company, team, workspace).

Field	Type	Required	Description
user_id	string	Yes	User performing the grouping
group_id	string	Yes	Group identifier
traits	object	No	Group traits (name, industry, etc.)

json

{
  "type": "group",
  "user_id": "user-456",
  "group_id": "company-789",
  "traits": {
    "name": "Acme Corp",
    "plan": "enterprise"
  },
  "timestamp": "2026-03-10T12:00:00Z"
}

page

Tracks a page view with optional page name and properties.

Field	Type	Required	Description
anonymous_id	string	Yes	Anonymous device ID
name	string	No	Page name
properties	object	No	Page properties (url, referrer, title)

json

{
  "type": "page",
  "anonymous_id": "abc-123",
  "name": "Pricing",
  "properties": {
    "url": "https://app.example.com/pricing",
    "referrer": "https://google.com"
  },
  "timestamp": "2026-03-10T12:00:00Z"
}

revenue

Tracks a revenue event for billing and conversion analytics.

Field	Type	Required	Description
user_id	string	Yes	Paying user ID
amount	number	Yes	Revenue amount
currency	string	No	ISO 4217 currency code (default: USD)
properties	object	No	Additional revenue context

json

{
  "type": "revenue",
  "user_id": "user-456",
  "amount": 49.99,
  "currency": "USD",
  "properties": {
    "plan": "pro",
    "interval": "monthly"
  },
  "timestamp": "2026-03-10T12:00:00Z"
}

experiment_exposure

Fired when a user is exposed to an experiment variant.

Field	Type	Required	Description
experiment_id	string	Yes	Experiment identifier
arm_key	string	Yes	The variant the user was assigned to
user_id	string	No	Identified user ID
anonymous_id	string	No	Anonymous device ID

json

{
  "type": "track",
  "event": "experiment_exposure",
  "user_id": "user-456",
  "properties": {
    "experiment_id": "exp-onboard-v2",
    "arm_key": "treatment"
  },
  "timestamp": "2026-03-10T12:00:00Z"
}

paywall_exposure

Fired when a user encounters a paywall or upgrade prompt.

Field	Type	Required	Description
paywall_id	string	Yes	Paywall identifier
feature	string	Yes	Feature being gated
user_id	string	No	Identified user ID
outcome	string	No	User action: dismissed, converted, deferred

json

{
  "type": "track",
  "event": "paywall_exposure",
  "user_id": "user-456",
  "properties": {
    "paywall_id": "export-gate",
    "feature": "csv_export",
    "outcome": "dismissed"
  },
  "timestamp": "2026-03-10T12:00:00Z"
}

intervention_delivery

Fired when RetainPixel delivers an intervention (nudge, reward, etc.) to a user.

Field	Type	Required	Description
intervention_id	string	Yes	Intervention identifier
intervention_type	string	Yes	Type: nudge, reward, prompt
subject_id	string	No	Target subject ID
channel	string	No	Delivery channel: email, in-app

json

{
  "type": "track",
  "event": "intervention_delivery",
  "properties": {
    "intervention_id": "int-welcome-3",
    "intervention_type": "nudge",
    "subject_id": "subj-789",
    "channel": "email"
  },
  "timestamp": "2026-03-10T12:00:00Z"
}

reward_obligation

Fired when a reward obligation is created or fulfilled for a subject.

Field	Type	Required	Description
reward_id	string	Yes	Reward identifier
subject_id	string	Yes	Subject receiving the reward
status	string	Yes	Obligation status: pending, fulfilled, expired
amount	number	No	Reward monetary value if applicable
reward_type	string	No	Type: cash, product, social, progress

json

{
  "type": "track",
  "event": "reward_obligation",
  "properties": {
    "reward_id": "rwd-milestone-5",
    "subject_id": "subj-789",
    "status": "fulfilled",
    "reward_type": "product",
    "amount": 0
  },
  "timestamp": "2026-03-10T12:00:00Z"
}