Segment Integration

Use this guide if Segment is already your event hub and you want to send affiliate-relevant backend events to Affonso without building a custom event mapper.

This article is the setup guide. If you need the full request contract, field mapping rules, response behavior, or exact validation details, see the Segment API docs.

Before You Start

Make sure you have:

1. An Affonso API key with write:commissions permission
2. Segment already sending backend track events for the actions you want to attribute
3. Your website and affiliate tracking already set up in Affonso

What This Integration Is For

Use Segment when:

• Segment is already your event hub
• you already rely on backend track events
• you want Affonso to ingest those events without a separate custom mapping service

This setup currently supports Segment track events only.

Integration Overview

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

Authorization: Bearer sk_live_your_key_here
Content-Type: application/json

{
  "type": "track",
  "event": "Order Completed",
  "messageId": "msg_123",
  "userId": "user_123",
  "properties": {
    "revenue": 99,
    "currency": "USD"
  }
}

Troubleshooting Checklist

1. Confirm Segment sends track payloads, not identify, group, page, or screen
2. Confirm the destination uses POST /v1/sources/segment/events
3. Confirm the API key has write:commissions
4. Confirm the event includes a stable identifier that already matches a referral in Affonso
5. If you send both userId and an explicit external-user field, confirm the values are identical
6. Confirm messageId stays the same when Segment retries delivery
7. If the event should create a conversion, confirm you send revenue and currency

Tracking Examples

Use these example payloads when you want to trigger different kinds of Affonso events through Segment.

Example: track a signup as lead

{
  "type": "track",
  "event": "Signup Completed",
  "messageId": "msg_signup_001",
  "userId": "usr_104982",
  "properties": {
    "affonso_id": "ref_123",
    "affonso_event_type": "lead",
    "email": "daniel.harper@northstar-health.io"
  }
}

Example: track a downstream step as trial

{
  "type": "track",
  "event": "Trial Started",
  "messageId": "msg_trial_001",
  "userId": "usr_104982",
  "properties": {
    "affonso_id": "ref_123",
    "affonso_event_type": "trial"
  }
}

Example: track a specific product conversion

{
  "type": "track",
  "event": "Downstream Completed",
  "messageId": "msg_conversion_001",
  "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.

Need The Exact API Contract?

Use the Segment API docs for:

• supported identifier fields
• mapping behavior
• event type normalization
• response behavior
• validation and error details

If you need a fully custom server-side integration without Segment, see Custom Payment Provider API.