> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://www.notifuse.com/docs/assets/screenshots/custom_event_timeline.png)

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:

| Type           | Use Case                             | goal_value |
| -------------- | ------------------------------------ | ---------- |
| `purchase`     | E-commerce orders, one-time payments | Required   |
| `subscription` | SaaS subscriptions, memberships      | Required   |
| `lead`         | Contact forms, demo requests         | Optional   |
| `signup`       | Account registrations                | Optional   |
| `booking`      | Appointments, consultations          | Optional   |
| `trial`        | Free trial activations               | Optional   |
| `other`        | Custom conversion events             | Optional   |

## 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](https://www.notifuse.com/docs/assets/screenshots/segment_goals.png)

### 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

| Option  | Description                               |
| ------- | ----------------------------------------- |
| Sum     | Total of all goal values (lifetime spend) |
| Count   | Number of events (order count)            |
| Average | Average goal value (AOV)                  |
| Min     | Smallest goal value                       |
| Max     | Largest goal value                        |

### Timeframe Options

| Option             | Description           |
| ------------------ | --------------------- |
| Anytime            | All historical data   |
| In the last X days | Rolling window        |
| In date range      | Specific period       |
| Before date        | Historical cutoff     |
| After date         | Since a specific date |

## Tracking Events

### Single Event

```bash
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:

```bash
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`

> [!NOTE]
>
> Goals recorded by [Web Analytics](https://www.notifuse.com/docs/web-analytics/goals.md) 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:

```json
{
  "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](https://www.notifuse.com/docs/features/admins-api-keys.md).

## 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](https://www.notifuse.com/docs/api-reference/import-custom-events.md) for complete endpoint documentation
