Features

Custom Events & Goals

Track user behavior and conversion goals to build RFM segments and enrich contact timelines.

Overview

Custom events track user actions from external systems (e-commerce, CRM, analytics). They appear in the contact timeline and enable goal-based segmentation for building RFM (Recency, Frequency, Monetary) segments.

Contact Timeline

Every custom event creates an entry in the contact timeline, giving you a complete history of user interactions:

Contact timeline with custom events

Events display with their event_name as the timeline entry type (e.g., “order.completed”, “subscription.started”). The properties field stores additional context visible in the timeline details.

Goal Types

Goals are the key to building powerful segments. Each event can optionally track a goal:

TypeUse Casegoal_value
purchaseE-commerce orders, one-time paymentsRequired
subscriptionSaaS subscriptions, membershipsRequired
leadContact forms, demo requestsOptional
signupAccount registrationsOptional
bookingAppointments, consultationsOptional
trialFree trial activationsOptional
otherCustom conversion eventsOptional

Building RFM Segments

RFM (Recency, Frequency, Monetary) analysis identifies your best customers. Use the segment builder with Custom Events Goal conditions (shown as Goal once added):

Segment builder with custom events goal

Monetary: Total Spend

Select goal type “purchase”, aggregate “sum”, and set a minimum value to find high-spending customers.

Frequency: Purchase Count

Select goal type “purchase”, aggregate “count”, and set a minimum number to find repeat buyers.

Recency: Recent Activity

Use the timeframe filter “in the last X days” to find customers with recent purchases.

Example RFM Segments

  • VIP Customers: Spent $1000+ AND 5+ orders AND purchased in last 60 days
  • At-Risk High-Value: Spent $500+ AND no purchase in 90 days
  • New High-Potential: First purchase over $200 in last 30 days

Aggregate Options

OptionDescription
SumTotal of all goal values (lifetime spend)
CountNumber of events (order count)
AverageAverage goal value (AOV)
MinSmallest goal value
MaxLargest goal value

Timeframe Options

OptionDescription
AnytimeAll historical data
In the last X daysRolling window
In date rangeSpecific period
Before dateHistorical cutoff
After dateSince a specific date

Tracking Events

Single Event

curl -X POST "https://your-instance.com/api/customEvents.upsert" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "your_workspace",
    "email": "customer@example.com",
    "event_name": "order.completed",
    "external_id": "order_12345",
    "properties": {
      "items": ["Product A", "Product B"],
      "currency": "USD"
    },
    "goal_type": "purchase",
    "goal_value": 149.99
  }'

Batch Import

Import up to 50 events at once:

curl -X POST "https://your-instance.com/api/customEvents.import" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "your_workspace",
    "events": [
      {
        "email": "user1@example.com",
        "event_name": "order.completed",
        "external_id": "order_001",
        "goal_type": "purchase",
        "goal_value": 99.99
      },
      {
        "email": "user2@example.com",
        "event_name": "order.completed",
        "external_id": "order_002",
        "goal_type": "purchase",
        "goal_value": 249.99
      }
    ]
  }'

Event Name Format

Event names must be lowercase using letters, numbers, dots, underscores, hyphens, or slashes:

  • order.completed
  • subscription/started
  • form_submit
  • user-signup

Goals recorded by Web Analytics reach the contact timeline through a narrower rule: ASCII letters, numbers, dots and slashes only, with everything else — hyphens and accented characters included — replaced by an underscore. A web goal named user-signup arrives as user_signup. If you send the same event through both paths, pick a name that survives each.

Handling Refunds

Use negative goal_value for refunds to keep accurate LTV calculations:

{
  "email": "customer@example.com",
  "event_name": "order.refunded",
  "external_id": "refund_12345",
  "goal_type": "purchase",
  "goal_value": -50.00
}

Permissions

Custom events have no permission of their own: they answer to Contacts. Recording or importing an event needs Contacts write, and reading one needs Contacts read — so granting Contacts read also opens the events recorded against your contacts, and the contact timeline they feed. See Admins & API Keys.

Notes

  • Contacts are auto-created if they don’t exist
  • Events update only if occurred_at is newer than existing
  • Soft-delete by setting deleted_at (set to null to restore)
  • Only a new event (a new external_id) starts the automations triggered by its name; since 44.0 an update, a soft delete or a restore does not
  • See API Reference for complete endpoint documentation