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

# Create Event

> Send a normalized server-side event for a conversion, lead, trial, or milestone

<Info>
  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.
</Info>

<Info>
  For a guide on when to choose `/events` versus `/conversions`, and for common
  backend tracking flows, see
  [Server-Side Tracking](/api/server-side-tracking).
</Info>

<Warning>
  For `event_type: "conversion"`, `sale_amount`, `sale_amount_currency`, and
  `external_event_id` are required.
</Warning>

## Body Parameters

<ParamField body="event_name" type="string" required>
  Human-readable event name from your system, such as `trial_started`,
  `invoice_paid`, or `activation_completed`.
</ParamField>

<ParamField body="event_type" type="string" default="milestone">
  Event type. Valid values: `conversion`, `lead`, `trial`, `milestone`.
</ParamField>

<ParamField body="referral_id" type="string">
  Affonso referral ID to credit directly. Optional if you provide
  `customer_id` or `external_user_id`.
</ParamField>

<ParamField body="customer_id" type="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`.
</ParamField>

<ParamField body="external_user_id" type="string">
  The user ID from your own product, app, or internal system. Optional if you
  provide `referral_id` or `customer_id`.
</ParamField>

<ParamField body="affonso_id" type="string">
  Compatibility alias for `referral_id`.
</ParamField>

<ParamField body="occurred_at" type="string">
  Optional ISO 8601 timestamp describing when the event happened upstream.
</ParamField>

<ParamField body="external_event_id" type="string">
  Optional idempotency key for non-conversion events. Required for conversion
  events. Use a stable upstream event identifier.
</ParamField>

<ParamField body="sale_amount" type="number">
  Sale amount for conversion events. Required when `event_type` is
  `conversion`.
</ParamField>

<ParamField body="sale_amount_currency" type="string">
  Three-letter currency code for the sale amount, such as `USD` or `EUR`.
  Required when `event_type` is `conversion`.
</ParamField>

<ParamField body="product_ids" type="string[]">
  Optional product identifiers to improve incentive matching on conversion
  events.
</ParamField>

<ParamField body="price_ids" type="string[]">
  Optional price identifiers to improve incentive matching on conversion
  events.
</ParamField>

<ParamField body="interval" type="string">
  Subscription interval for conversion events. Valid values: `monthly`,
  `yearly`.
</ParamField>

<ParamField body="is_subscription" type="boolean">
  Whether the conversion comes from a subscription purchase.
</ParamField>

<ParamField body="metadata" type="object">
  Optional metadata stored with the resulting event log and, when applicable,
  the affiliate earning.
</ParamField>

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

<ResponseField name="success" type="boolean">
  Always `true` for successful responses.
</ResponseField>

<ResponseField name="data" type="object">
  The conversion object, including `matched_incentive_id`,
  `commission_amount`, `sales_status`, `commission_created`, and
  `activity_outcome`. See [Create Conversion](/api/endpoint/conversions/create)
  for the complete response schema.
</ResponseField>

### Milestone Response

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

<ResponseField name="success" type="boolean">
  Always `true` for successful responses.
</ResponseField>

<ResponseField name="data" type="object">
  Event processing result.

  <Expandable title="Data Object Properties">
    <ResponseField name="referral_id" type="string">
      Referral that was matched and updated.
    </ResponseField>

    <ResponseField name="transaction_id" type="string | null">
      Created transaction ID when the event generated a lead incentive commission.
    </ResponseField>

    <ResponseField name="event_name" type="string">
      Event name that was processed.
    </ResponseField>

    <ResponseField name="event_type" type="string">
      Event type that was processed.
    </ResponseField>

    <ResponseField name="external_event_id" type="string | null">
      The idempotency key used for this event, if supplied.
    </ResponseField>

    <ResponseField name="action" type="string">
      Processing outcome: `logged`, `referral_updated`, or `commission_created`.
    </ResponseField>

    <ResponseField name="referral_status" type="string">
      Referral status after processing, such as `lead`, `trialing`, or `customer`.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Request: Conversion Event

<RequestExample>
  ```bash cURL theme={null}
  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
    }'
  ```
</RequestExample>

## Example Request: Lead Event

<RequestExample>
  ```bash cURL theme={null}
  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"
      }
    }'
  ```
</RequestExample>

## Example Request: Trial Event

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```
</RequestExample>

## Example Request: Milestone Event

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```
</RequestExample>

## Example Response: Milestone Event

<ResponseExample>
  ```json Response theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

<Info>
  If request signing is enabled for your environment, include
  `X-Affonso-Timestamp` and `X-Affonso-Signature` headers as described in
  [Server-Side Tracking](/api/server-side-tracking).
</Info>