> ## 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.
# Segment Track Events
> Send Segment track events to Affonso using the dedicated Segment source endpoint
## 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:
```text theme={null}
POST https://api.affonso.io/v1/sources/segment/events
```
Use your Affonso API key in the request headers:
```text theme={null}
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](https://affonso.io/help/integrations/segment/segment-track-events).
## 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:
1. `external_user_id`
2. `referral_id`
3. `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:
1. `properties.revenue`
2. `properties.amount`
3. `properties.value`
4. `properties.total`
Currency is read from:
* `properties.currency`
* `properties.sale_amount_currency`
## Example Request: Conversion
```bash cURL theme={null}
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
```bash cURL theme={null}
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:
```bash cURL theme={null}
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:
```bash cURL theme={null}
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.
## Example Request: Signup tracked as `lead`
```bash cURL theme={null}
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`
```bash cURL theme={null}
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`
```bash cURL theme={null}
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
## Related Docs
Setup walkthrough and troubleshooting checklist
Choose the right backend tracking endpoint
Reference for the core events endpoint