Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.notifuse.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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 Goals” conditions: 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

​
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
}

​
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)
  • See API Reference for complete endpoint documentation