Create Event

curl -X POST "https://api.affonso.io/v1/events" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "invoice_paid",
    "event_type": "conversion",
    "customer_id": "cus_R8d92kLm3pQx71",
    "sale_amount": 2000.00,
    "sale_amount_currency": "USD",
    "external_event_id": "evt_conversion_001",
    "product_ids": ["downstream"],
    "is_subscription": false
  }'

{
  "success": true,
  "data": {
    "referral_id": "ref_456def",
    "transaction_id": null,
    "event_name": "trial_started",
    "event_type": "trial",
    "external_event_id": "evt_trial_123",
    "action": "referral_updated",
    "referral_status": "trialing"
  }
}

POST

events

curl -X POST "https://api.affonso.io/v1/events" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "invoice_paid",
    "event_type": "conversion",
    "customer_id": "cus_R8d92kLm3pQx71",
    "sale_amount": 2000.00,
    "sale_amount_currency": "USD",
    "external_event_id": "evt_conversion_001",
    "product_ids": ["downstream"],
    "is_subscription": false
  }'

{
  "success": true,
  "data": {
    "referral_id": "ref_456def",
    "transaction_id": null,
    "event_name": "trial_started",
    "event_type": "trial",
    "external_event_id": "evt_trial_123",
    "action": "referral_updated",
    "referral_status": "trialing"
  }
}

Use this endpoint when your backend wants one event ingestion surface for both revenue and non-revenue events. Conversion events return a conversion object. Lead, trial, and milestone events return an event-processing result.

For a guide on when to choose /events versus /conversions, and for common backend tracking flows, see Server-Side Tracking.

For event_type: "conversion", sale_amount, sale_amount_currency, and external_event_id are required.

Body Parameters

string

required

Human-readable event name from your system, such as trial_started, invoice_paid, or activation_completed.

string

default:"milestone"

Event type. Valid values: conversion, lead, trial, milestone.

string

Affonso referral ID to credit directly. Optional if you provide customer_id or external_user_id.

string

The customer ID from your payment provider or billing system, such as a Stripe customer ID. Optional if you provide referral_id or external_user_id.

string

The user ID from your own product, app, or internal system. Optional if you provide referral_id or customer_id.

string

Compatibility alias for referral_id.

string

Optional ISO 8601 timestamp describing when the event happened upstream.

string

Optional idempotency key for non-conversion events. Required for conversion events. Use a stable upstream event identifier.

number

Sale amount for conversion events. Required when event_type is conversion.

string

Three-letter currency code for the sale amount, such as USD or EUR. Required when event_type is conversion.

string[]

Optional product identifiers to improve incentive matching on conversion events.

string[]

Optional price identifiers to improve incentive matching on conversion events.

string

Subscription interval for conversion events. Valid values: monthly, yearly.

boolean

Whether the conversion comes from a subscription purchase.

object

Optional metadata stored with the resulting event log and, when applicable, the affiliate earning.

Validation Rules

At least one of referral_id, customer_id, or external_user_id is required.
affonso_id is also accepted instead of referral_id for compatibility.
Older field-name variants continue to work for compatibility, but new integrations should standardize on referral_id.
If you send more than one identifier, Affonso checks external_user_id first, then referral_id, then customer_id.
Conversion events require sale_amount, sale_amount_currency, and external_event_id.
Reusing the same external_event_id returns the prior processed result instead of creating a duplicate.

Response

Conversion Response

When event_type is conversion, the response matches POST /conversions.

boolean

Always true for successful responses.

object

The conversion object, including matched_incentive_id, commission_amount, sales_status, commission_created, and activity_outcome. See Create Conversion for the complete response schema.

Milestone Response

When event_type is lead, trial, or milestone, the response describes what Affonso did with the event.

boolean

Always true for successful responses.

object

Event processing result.

Show Data Object Properties

string

Referral that was matched and updated.

string | null

Created transaction ID when the event generated a lead incentive commission.

string

Event name that was processed.

string

Event type that was processed.

string | null

The idempotency key used for this event, if supplied.

string

Processing outcome: logged, referral_updated, or commission_created.

string

Referral status after processing, such as lead, trialing, or customer.

Example Request: Conversion Event

curl -X POST "https://api.affonso.io/v1/events" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "invoice_paid",
    "event_type": "conversion",
    "customer_id": "cus_R8d92kLm3pQx71",
    "sale_amount": 2000.00,
    "sale_amount_currency": "USD",
    "external_event_id": "evt_conversion_001",
    "product_ids": ["downstream"],
    "is_subscription": false
  }'

Example Request: Lead Event

curl -X POST "https://api.affonso.io/v1/events" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "signup_completed",
    "event_type": "lead",
    "referral_id": "ref_123",
    "external_user_id": "usr_104982",
    "external_event_id": "evt_signup_001",
    "metadata": {
      "email": "daniel.harper@northstar-health.io"
    }
  }'

Example Request: Trial Event

curl -X POST "https://api.affonso.io/v1/events" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "trial_started",
    "event_type": "trial",
    "external_user_id": "usr_104982",
    "external_event_id": "evt_trial_001"
  }'

Example Request: Milestone Event

curl -X POST "https://api.affonso.io/v1/events" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "kyc_passed",
    "event_type": "milestone",
    "external_user_id": "usr_104982",
    "external_event_id": "evt_kyc_001"
  }'

Example Response: Milestone Event

{
  "success": true,
  "data": {
    "referral_id": "ref_456def",
    "transaction_id": null,
    "event_name": "trial_started",
    "event_type": "trial",
    "external_event_id": "evt_trial_123",
    "action": "referral_updated",
    "referral_status": "trialing"
  }
}

If request signing is enabled for your environment, include X-Affonso-Timestamp and X-Affonso-Signature headers as described in Server-Side Tracking.

Getting Started

Guide

Core Resources

Program Management

Marketplace

Body Parameters

Validation Rules

Response

Conversion Response

Milestone Response

Example Request: Conversion Event

Example Request: Lead Event

Example Request: Trial Event

Example Request: Milestone Event

Example Response: Milestone Event

​Body Parameters

​Validation Rules

​Response

​Conversion Response

​Milestone Response

​Example Request: Conversion Event

​Example Request: Lead Event

​Example Request: Trial Event

​Example Request: Milestone Event

​Example Response: Milestone Event

Body Parameters

Validation Rules

Response

Conversion Response

Milestone Response

Example Request: Conversion Event

Example Request: Lead Event

Example Request: Trial Event

Example Request: Milestone Event

Example Response: Milestone Event