How do I track leads, trials, and product conversions with the Events API?

Use POST /v1/events when your backend wants one endpoint for both revenue and non-revenue affiliate events.

Common patterns:

lead for signup or qualified lead events
trial for non-revenue trial starts
milestone for lifecycle steps such as onboarding, KYC, or activation
conversion for paid purchases and product-specific incentive matching

Lead example

{
  "event_name": "signup_completed",
  "event_type": "lead",
  "referral_id": "ref_123",
  "external_user_id": "usr_104982",
  "external_event_id": "evt_signup_001"
}

Trial example

{
  "event_name": "trial_started",
  "event_type": "trial",
  "external_user_id": "usr_104982",
  "external_event_id": "evt_trial_001"
}

Product-specific conversion example

{
  "event_name": "invoice_paid",
  "event_type": "conversion",
  "customer_id": "cus_R8d92kLm3pQx71",
  "external_event_id": "evt_conversion_001",
  "sale_amount": 2000,
  "sale_amount_currency": "USD",
  "product_ids": ["downstream"]
}

Milestone example

{
  "event_name": "kyc_passed",
  "event_type": "milestone",
  "external_user_id": "usr_104982",
  "external_event_id": "evt_kyc_001"
}

Use trial only for non-revenue trial starts. If revenue happened, or if you need product-specific incentive matching, send the event as conversion and include product_ids or price_ids.

For the full setup guide, see Server-Side Event Tracking.

For the exact request schema, see Create Event API docs.

How do I track leads, trials, and product conversions with the Events API?

Lead example

Trial example

Product-specific conversion example

Milestone example

Was this article helpful?

On this page

Ready to Scale Your SaaS?