Skip to main content
POST
/
v1
/
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": "cust_123",
    "sale_amount": 99.00,
    "sale_amount_currency": "USD",
    "external_event_id": "evt_2026_000145"
  }'

{
  "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 event_type: "conversion", sale_amount, sale_amount_currency, and external_event_id are required.

​
Body Parameters

​
event_name
string
required
Human-readable event name from your system, such as trial_started, invoice_paid, or activation_completed.
​
event_type
string
default:"milestone"
Event type. Valid values: conversion, lead, trial, milestone.
​
referral_id
string
Referral ID to credit directly. Optional if you provide customer_id, external_user_id, or click_id.
​
customer_id
string
Your internal customer identifier. Optional if you provide referral_id, external_user_id, or click_id.
​
external_user_id
string
Your external application user ID. Optional if you provide referral_id, customer_id, or click_id.
​
click_id
string
Click ID returned by POST /clicks. Optional if you provide referral_id, customer_id, or external_user_id.
​
occurred_at
string
Optional ISO 8601 timestamp describing when the event happened upstream.
​
external_event_id
string
Optional idempotency key for non-conversion events. Required for conversion events. Use a stable upstream event identifier.
​
sale_amount
number
Sale amount for conversion events. Required when event_type is conversion.
​
sale_amount_currency
string
Three-letter currency code for the sale amount, such as USD or EUR. Required when event_type is conversion.
​
product_ids
string[]
Optional product identifiers to improve incentive matching on conversion events.
​
price_ids
string[]
Optional price identifiers to improve incentive matching on conversion events.
​
interval
string
Subscription interval for conversion events. Valid values: monthly, yearly.
​
is_subscription
boolean
Whether the conversion comes from a subscription purchase.
​
metadata
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, external_user_id, or click_id is required.
  • 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.
​
success
boolean
Always true for successful responses.
​
data
object
The conversion object, including matched_incentive_id, commission_amount, and sales_status.

​
Milestone Response

When event_type is lead, trial, or milestone, the response describes what Affonso did with the event.
​
success
boolean
Always true for successful responses.
​
data
object
Event processing result.

​
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": "cust_123",
    "sale_amount": 99.00,
    "sale_amount_currency": "USD",
    "external_event_id": "evt_2026_000145"
  }'

​
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",
    "customer_id": "cust_123",
    "external_event_id": "evt_trial_123"
  }'

​
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 Conversions.