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

# Affonso Integration

> Sync affiliates and trigger email automations on referrals, commissions, and payouts

Connect your Affonso affiliate program to sync affiliates into Sequenzy as subscribers and trigger email automations across the whole affiliate lifecycle: signups, referrals, commissions, coupons, and payouts.

## What is Affonso?

[Affonso](https://affonso.io) is an affiliate marketing platform for SaaS companies. It tracks referral links, conversions, commissions, and payouts for your affiliate program.

## Connecting Affonso

### Step 1: Get Your Webhook URL

1. Go to **Settings → Integrations** in Sequenzy
2. Find **Affonso** under Affiliate Marketing
3. Click **Connect**
4. Copy the **Webhook URL** shown

### Step 2: Create a Webhook Endpoint in Affonso

1. Go to your Affonso dashboard
2. Navigate to **Settings → Webhooks**
3. Click **Add Endpoint** and paste your Sequenzy webhook URL
4. Select **All events** (recommended), or pick the affiliate, referral, transaction, coupon, and payout events you need
5. Copy the **Signing Secret** (it is shown only once)

### Step 3: Complete the Connection in Sequenzy

1. Return to Sequenzy's Affonso connection modal
2. Paste the **Signing Secret**
3. Click **Connect Affonso**

That's it! Affonso events will now flow into Sequenzy. Every webhook is verified against the signing secret before it is processed.

## What Gets Synced

When an affiliate signs up (or is updated) in Affonso, Sequenzy creates or updates a subscriber with the affiliate's email, name, and these attributes. Attribute names are provider-agnostic (`affiliate*`, not `affonso*`), so your segments and automations keep working if you ever switch affiliate platforms:

| Attribute                 | Source                                                |
| ------------------------- | ----------------------------------------------------- |
| `affiliateId`             | Affonso affiliate id (used to match later events)     |
| `affiliateTrackingId`     | The affiliate's referral/tracking code                |
| `affiliateStatus`         | `PENDING`, `ACTIVE`, `INACTIVE`, or `DELETED`         |
| `affiliateProgramId`      | The affiliate program id                              |
| `affiliateGroupId`        | Group association (when set)                          |
| `affiliateCouponCode`     | The affiliate's coupon code (from coupon events)      |
| `affiliateCouponProvider` | Payment provider of the coupon (stripe, paddle, etc.) |
| Custom metadata           | Primitive values from the affiliate's metadata        |

As referrals, transactions, and payouts come in, Sequenzy also maintains running totals on the affiliate:

| Attribute                        | Updated on            | Meaning                                    |
| -------------------------------- | --------------------- | ------------------------------------------ |
| `affiliateLeadCount`             | `referral.lead`       | Signups the affiliate has referred         |
| `affiliateConversionCount`       | `referral.converted`  | Referred signups that became customers     |
| `affiliateTotalReferredRevenue`  | `transaction.created` | Lifetime sale value the affiliate referred |
| `affiliateTotalCommissionEarned` | `transaction.created` | Lifetime commission the affiliate earned   |
| `affiliateTotalPaidOut`          | `payout.paid`         | Total commission actually paid out         |
| `affiliateLastPayoutAt`          | `payout.paid`         | Timestamp of the most recent payout        |

Failed and refunded sales are not counted, and the universal `transaction.updated` event never double counts totals.

<Note>
  Referral, transaction, coupon, and payout events identify the affiliate by
  their Affonso affiliate id. The affiliate must already be synced (via an
  `affiliate.created`, `affiliate.confirmed`, or `affiliate.updated` webhook)
  before these events can be matched; unmatched events are acknowledged and
  skipped.
</Note>

## Event Naming

Events live in the provider-agnostic `affiliate.*` namespace and target the affiliate's subscriber profile. Affiliate lifecycle events keep Affonso's names; referral, transaction, coupon, and payout events are folded into the same namespace:

| Affonso Event          | Sequenzy Event                   |
| ---------------------- | -------------------------------- |
| `affiliate.created`    | `affiliate.created`              |
| `affiliate.confirmed`  | `affiliate.confirmed`            |
| `affiliate.updated`    | `affiliate.updated`              |
| `affiliate.deleted`    | `affiliate.deleted`              |
| `referral.lead`        | `affiliate.referral_lead`        |
| `referral.converted`   | `affiliate.referral_converted`   |
| `referral.updated`     | `affiliate.referral_updated`     |
| `referral.deleted`     | `affiliate.referral_deleted`     |
| `transaction.created`  | `affiliate.transaction_created`  |
| `transaction.approved` | `affiliate.transaction_approved` |
| `transaction.paid`     | `affiliate.transaction_paid`     |
| `transaction.rejected` | `affiliate.transaction_rejected` |
| `coupon.created`       | `affiliate.coupon_created`       |
| `coupon.deleted`       | `affiliate.coupon_deleted`       |
| `payout.created`       | `affiliate.payout_created`       |
| `payout.paid`          | `affiliate.payout_paid`          |
| `payout.failed`        | `affiliate.payout_failed`        |

## Using with Automations

### Affiliate Welcome Sequence

1. Go to **Automations** → **Create New**
2. Set trigger to **Event Received** → `affiliate.created`
3. Send a welcome email with their tracking link: `Your referral code is {{affiliateTrackingId}}`

### Celebrate Conversions

Send affiliates a congratulations email whenever they refer a paying customer:

```text theme={null}
Trigger: affiliate.referral_converted
└── Send "You just earned a commission!" email
    with {{event.referredEmail}} and {{event.trackingId}}
```

### Payout Notifications

Trigger on `affiliate.payout_paid` to confirm payouts, using `{{event.amount}}` and `{{event.invoiceNumber}}` in the email body.

### Reward Top Affiliates

Create a segment where `affiliateTotalReferredRevenue` is greater than 1000 and send them an upgraded commission offer or exclusive coupon.

## Event Properties as Variables

Each event exposes its details as `{{event.*}}` variables in automation emails:

* Referrals: `referralId`, `trackingId`, `referralStatus`, `referredEmail`, `customerId`, `referrer`
* Transactions: `transactionId`, `saleAmount`, `saleCurrency`, `saleStatus`, `commissionAmount`, `commissionStatus`, `incentiveType`
* Payouts: `payoutId`, `amount`, `status`, `invoiceNumber`, `paidAt`
* Coupons: `couponId`, `code`, `paymentProvider`

## Troubleshooting

### Events Not Appearing

1. Verify the webhook URL in Affonso matches the URL shown in Sequenzy
2. Check that the signing secret you pasted matches the endpoint's secret in Affonso
3. Use the **Activity** button on the Affonso integration row to inspect recent webhook deliveries and errors

### Referral or Payout Events Being Skipped

These events are matched through the `affiliateId` attribute. If the affiliate was created in Affonso before you connected the integration, edit and save the affiliate in Affonso (or wait for their next `affiliate.updated` event) so the sync creates their subscriber first.

### Signature Verification Failing

Affonso signs each webhook with a timestamped HMAC that expires after 5 minutes. If your endpoint secret was rotated in Affonso, reconnect the integration in Sequenzy with the new signing secret.

## FAQ

<AccordionGroup>
  <Accordion title="Do affiliates count toward my subscriber limit?">
    Yes. Affiliates are synced as regular subscribers so you can email them,
    segment them, and enroll them in sequences.
  </Accordion>

  <Accordion title="Are referred customers added as subscribers?">
    No. Referral events carry the referred customer's email as an event property
    (`{{event.referredEmail}}`), but only the affiliate is created or updated as
    a subscriber. Referred customers usually enter Sequenzy through your normal
    signup or payment integrations.
  </Accordion>

  <Accordion title="What happens when an affiliate is removed from my program?">
    Their `affiliateStatus` attribute is set to `DELETED` and an
    `affiliate.deleted` event fires. The subscriber stays active so you
    keep history; build an automation on that event if you want to tag or
    unsubscribe them.
  </Accordion>

  <Accordion title="Do refunds reduce the revenue totals?">
    No. `affiliateTotalReferredRevenue` and `affiliateTotalCommissionEarned` are
    lifetime gross totals. Refunds emit `affiliate.transaction_rejected` events you
    can automate on, but totals are not decremented.
  </Accordion>

  <Accordion title="Is this included in my plan?">
    Yes, the Affonso integration is included at no extra cost.
  </Accordion>
</AccordionGroup>