Segment Track Events

Overview

Use this endpoint if Segment is already your event hub and you want Affonso to process affiliate-relevant track events from it. Send requests to:

POST https://api.affonso.io/v1/sources/segment/events

Use your Affonso API key in the request headers:

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

This page is the technical reference for the Segment endpoint. For a setup walkthrough and troubleshooting checklist, see the Segment Helpcenter guide.

What This Endpoint Accepts

Segment track events only
conversion events
lead events
trial events
milestone events
retry-safe requests using Segment messageId

Unsupported Segment payload types such as identify, group, page, and screen return a validation error.

Required Request Parts

Every request must include:

type: "track"
an event name
a stable messageId
at least one supported identifier

For conversion events, also include:

a revenue value in properties
a currency in properties

Explicit `event_type` Override

If your internal Segment event names should stay unchanged, you can override the derived Affonso event type with either:

properties.affonso_event_type
properties.affonsoEventType

Allowed values are:

conversion
lead
trial
milestone

If a valid override is present, it wins over the built-in name mapping. If an invalid override is present, the request fails with 400 VALIDATION_ERROR.

Supported Identifiers

Affonso can match the request using one of these values:

userId
properties.customer_id
properties.referral_id
properties.affonso_id
properties.external_user_id
context.traits.external_user_id

If you send userId, Affonso treats it as your external_user_id. If you want to send customer_id through the Segment adapter, send it explicitly in properties.customer_id or properties.customerId. Use this for the customer ID from your payment provider or billing system, such as Stripe. external_user_id is for the user ID from your own product, app, or internal system. If you want to resolve a referral directly, use properties.referral_id. If you already use properties.affonso_id in an existing integration, that is also accepted. Older field-name variants continue to work for compatibility, but new integrations should standardize on referral_id. If you send both top-level userId and an explicit external-user field, both values must match. If none of those identifiers is present, the request fails.

How Matching Works

The identifier you send must already match an existing referral in your team. If no referral matches, Affonso rejects the request instead of creating a new attribution automatically. Affonso checks identifiers in this order:

external_user_id
referral_id
customer_id

If you send multiple identifiers, they must all resolve to the same referral or the request fails with a deterministic mismatch error.

Idempotency

Affonso uses Segment messageId to prevent duplicates. Reusing the same messageId for the same event is safe and does not create a duplicate conversion or milestone.

Revenue Fields For Conversions

For conversion events, Affonso looks for the sale amount in this order:

properties.revenue
properties.amount
properties.value
properties.total

Currency is read from:

properties.currency
properties.sale_amount_currency

Example Request: Conversion

cURL

curl -X POST "https://api.affonso.io/v1/sources/segment/events" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "track",
    "event": "Order Completed",
    "messageId": "msg_2026_000145",
    "userId": "user_123",
    "timestamp": "2026-06-23T10:15:00Z",
    "properties": {
      "revenue": 99,
      "currency": "USD"
    }
  }'

Example Request: Milestone

cURL

curl -X POST "https://api.affonso.io/v1/sources/segment/events" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "track",
    "event": "KYC Passed",
    "messageId": "msg_2026_000146",
    "userId": "user_123",
    "timestamp": "2026-06-23T10:20:00Z"
  }'

Example Request: Explicit customer_id

Use this pattern when userId should remain the user ID from your product or app, but you also want to send a separate customer ID from your payment provider:

cURL

curl -X POST "https://api.affonso.io/v1/sources/segment/events" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "track",
    "event": "trial_started",
    "messageId": "msg_2026_000147",
    "userId": "user_123",
    "properties": {
      "customer_id": "cust_123"
    }
  }'

Example Request: Resolve by affonso_id

Use this pattern when you already know the Affonso referral ID you want to credit:

cURL

curl -X POST "https://api.affonso.io/v1/sources/segment/events" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "track",
    "event": "trial_started",
    "messageId": "msg_2026_000148",
    "properties": {
      "affonso_id": "ref_123"
    }
  }'

Tracking Examples

Use these example payloads when you want to trigger different Affonso event types through the Segment adapter.

cURL

curl -X POST "https://api.affonso.io/v1/sources/segment/events" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "track",
    "event": "Signup Completed",
    "messageId": "msg_2026_000150_signup",
    "userId": "usr_104982",
    "properties": {
      "affonso_id": "ref_123",
      "affonso_event_type": "lead",
      "email": "daniel.harper@northstar-health.io"
    }
  }'

Example Request: Downstream step tracked as `trial`

cURL

curl -X POST "https://api.affonso.io/v1/sources/segment/events" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "track",
    "event": "Trial Started",
    "messageId": "msg_2026_000151_trial",
    "userId": "usr_104982",
    "properties": {
      "affonso_id": "ref_123",
      "affonso_event_type": "trial"
    }
  }'

Example Request: Specific product tracked as `conversion`

cURL

curl -X POST "https://api.affonso.io/v1/sources/segment/events" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "track",
    "event": "Downstream Completed",
    "messageId": "msg_2026_000152_conversion",
    "userId": "usr_104982",
    "properties": {
      "affonso_id": "ref_123",
      "affonso_event_type": "conversion",
      "product_ids": ["downstream"],
      "revenue": 2000,
      "currency": "USD"
    }
  }'

Use trial only when the event should behave as a trial milestone. If you want to match a product-specific incentive, send the event as a conversion and include the matching product_ids or price_ids.

Common Errors

Only Segment track payloads are supported
Segment track events require userId for external_user_id mapping, properties.referral_id, or an explicit properties.customer_id field
Segment userId must match the explicit external_user_id value when both are provided
identifier did not resolve to a referral in your team
conversion validation errors when revenue or currency is missing

Segment Helpcenter Guide

Setup walkthrough and troubleshooting checklist

Server-Side Tracking

Choose the right backend tracking endpoint

Events API Reference

Reference for the core events endpoint

Getting Started

Guide

Core Resources

Program Management

Marketplace

Overview

What This Endpoint Accepts

Required Request Parts

Explicit `event_type` Override

Supported Identifiers

How Matching Works

Idempotency

Revenue Fields For Conversions

Example Request: Conversion

Example Request: Milestone

Example Request: Explicit customer_id

Example Request: Resolve by affonso_id

Tracking Examples

Example Request: Downstream step tracked as `trial`

Example Request: Specific product tracked as `conversion`

Common Errors

Segment Helpcenter Guide

Server-Side Tracking

Events API Reference

​Overview

​What This Endpoint Accepts

​Required Request Parts

​Explicit event_type Override

​Supported Identifiers

​How Matching Works

​Idempotency

​Revenue Fields For Conversions

​Example Request: Conversion

​Example Request: Milestone

​Example Request: Explicit customer_id

​Example Request: Resolve by affonso_id

​Tracking Examples

​Example Request: Signup tracked as lead

​Example Request: Downstream step tracked as trial

​Example Request: Specific product tracked as conversion

​Common Errors

​Related Docs

Segment Helpcenter Guide

Server-Side Tracking

Events API Reference

Overview

What This Endpoint Accepts

Required Request Parts

Explicit `event_type` Override

Supported Identifiers

How Matching Works

Idempotency

Revenue Fields For Conversions

Example Request: Conversion

Example Request: Milestone

Example Request: Explicit customer_id

Example Request: Resolve by affonso_id

Tracking Examples

Example Request: Signup tracked as `lead`

Example Request: Downstream step tracked as `trial`

Example Request: Specific product tracked as `conversion`

Common Errors

Related Docs