event()

Overview

event() records a single behavioral event. Events are the primary signal ChurnKit uses to calculate churn risk — frequent, diverse events indicate healthy engagement, while gaps or negative events (e.g. support tickets) raise risk scores.

Signature

churn.event(
  userId: string,
  event: string,
  properties?: EventProperties,
  options?: CallOptions
): Promise<{ ok: boolean }>

Parameters

string

required

The user who performed the action.

string

required

Event name — use snake_case by convention. Must be non-empty.

EventProperties

Optional key-value metadata. Values must be string | number | boolean | null.

AbortSignal

Cancel the request via an AbortSignal.

What events to track

Track events that signal engagement or disengagement:

// Core feature usage — strongest retention signal
await churn.event('user_123', 'feature_used', { feature: 'analytics_dashboard' })
await churn.event('user_123', 'report_exported')
await churn.event('user_123', 'team_member_invited')
await churn.event('user_123', 'api_called')
await churn.event('user_123', 'integration_connected', { provider: 'slack' })

// These raise risk scores
await churn.event('user_123', 'support_ticket_opened', { severity: 'critical' })
await churn.event('user_123', 'billing_failed')
await churn.event('user_123', 'export_all_data')          // data portability = exit intent
await churn.event('user_123', 'cancellation_page_viewed')
await churn.event('user_123', 'downgrade_initiated')

// Used for recency/frequency scoring
await churn.event('user_123', 'session_started')
await churn.event('user_123', 'session_ended', { duration_seconds: 342 })

Examples

Simple event

await churn.event('user_123', 'dashboard_viewed')

Event with properties

await churn.event('user_123', 'feature_used', {
  feature: 'csv_export',
  rows_exported: 1500,
  format: 'csv',
})

In a Next.js Route Handler

import { churn } from '@/lib/churnkit'

export async function POST(req: Request) {
  const { userId, feature } = await req.json()
  await churn.event(userId, 'feature_used', { feature })
  return Response.json({ ok: true })
}

Fire and forget (non-blocking)

// Don't await if you don't need to block the response
void churn.event(userId, 'page_viewed', { path: '/settings' })

Return value

{ ok: true }

Errors

Code	When
`VALIDATION_ERROR`	`userId` or `event` is empty
`UNAUTHORIZED`	API key is invalid
`RATE_LIMITED`	Too many requests — back off and retry
`TIMEOUT`	Request exceeded timeout

For high-throughput scenarios (e.g. tracking every API call), use the EventBatcher instead of calling event() individually.

ChurnKit

Tracking Events

Churn Risk

Watching Users

Webhooks

Reference

Overview

Signature

Parameters

What events to track

Examples

Simple event

Event with properties

In a Next.js Route Handler

Fire and forget (non-blocking)

Return value

Errors

​Overview

​Signature

​Parameters

​What events to track

​Examples

​Simple event

​Event with properties

​In a Next.js Route Handler

​Fire and forget (non-blocking)

​Return value

​Errors

Overview

Signature

Parameters

What events to track

Examples

Simple event

Event with properties

In a Next.js Route Handler

Fire and forget (non-blocking)

Return value

Errors