Skip to main content
Events are the language Refairn uses to stay in sync with your SaaS product. Every time a customer signs up, subscribes, upgrades, or cancels, your system (or your payment provider) fires an event that Refairn uses to update attribution records and trigger commission logic. Understanding how these events flow—and what data each one carries—is essential for a reliable integration.

​
How events flow

There are two directions of event traffic in a Refairn integration:
  • Inbound events (you → Refairn): Your SaaS backend or payment provider sends events to Refairn when customer and payment state changes. These drive referral attribution and commission calculation.
  • Outbound events (Refairn → you): In a future release, Refairn will send webhook notifications to your system when commissions are approved, held, or disbursed. This direction is not yet available—see the note below.
Outbound webhooks from Refairn to your system (for example, commission.approved or payout.released notifications) are planned for a future release. This page documents the inbound events your integration should send to Refairn today.

​
Authentication

All inbound event requests must include your API key as a Bearer token in the Authorization header. API keys are generated per business in Settings → Integrations in your business dashboard. 
Authorization: Bearer YOUR_API_KEY
For payment provider webhooks (Stripe, Paystack, etc.), authentication is handled by Refairn verifying the provider’s webhook signature automatically. You do not need to pass an API key for those—just configure the correct webhook URL for your business.

​
Error handling and retries

Refairn returns standard HTTP status codes:
CodeMeaning
200Event received and processed successfully
400Bad request — check your payload fields
401Unauthorized — check your API key
409Conflict — duplicate event (use idempotency keys)
5xxServer error — safe to retry
For 5xx errors, implement exponential backoff with at least three retry attempts. Events are idempotent: sending the same event twice with the same customer email and payment date will not generate duplicate commissions. However, if your system does not have natural idempotency, include a unique eventId field in your payload to let Refairn deduplicate explicitly.

​
Inbound event types

These are the events your SaaS backend should send to Refairn as customers move through their lifecycle.
Fired when a new customer creates an account through a referral link. Send this event from your signup flow immediately after account creation succeeds. Refairn uses it to record the lead, link it to the referring agent, and start the attribution window.Endpoint: POST /api/events/customer-created
{
  "businessId": "business_123",
  "productId": "product_123",
  "customerEmail": "jane@example.com",
  "customerName": "Jane Smith",
  "referralCode": "AGENT123"
}
Response:
{
  "success": true,
  "leadId": "lead_abc123",
  "agentId": "agent_xyz456",
  "attribution": "first_touch",
  "message": "Customer recorded and attributed to agent."
}
Notes:
  • referralCode is the agent’s unique code, captured from the referral link click cookie. If the customer did not arrive via a referral link, omit this field.
  • Attribution is assigned at the first_touch point—the first referral link click recorded for this email address.
Fired when a customer moves from a free or trial state to an active paid subscription. This event, combined with the corresponding payment.succeeded event, is what triggers the initial referral commission for the attributing agent.Endpoint: POST /api/events/payment-succeeded
{
  "businessId": "business_123",
  "productId": "product_123",
  "customerEmail": "jane@example.com",
  "amount": 99,
  "currency": "USD",
  "subscriptionStatus": "active",
  "paymentDate": "2026-06-14"
}
Response:
{
  "success": true,
  "commissionId": "comm_abc123",
  "agentId": "agent_xyz456",
  "commissionAmount": 19.80,
  "commissionStatus": "pending",
  "holdUntil": "2026-06-28"
}
Fired when a customer upgrades their subscription to a plan with a higher monthly or annual value. Refairn recalculates the recurring commission amount based on the new plan value. The delta in plan value may generate an incremental commission depending on your program’s commission rules.
{
  "businessId": "business_123",
  "productId": "product_123",
  "customerEmail": "jane@example.com",
  "amount": 199,
  "currency": "USD",
  "subscriptionStatus": "active",
  "paymentDate": "2026-07-01",
  "previousAmount": 99,
  "eventType": "upgrade"
}
Fired when a customer downgrades their subscription. Refairn adjusts future recurring commission calculations to reflect the new lower plan value. Commissions already approved for prior periods are not clawed back.
{
  "businessId": "business_123",
  "productId": "product_123",
  "customerEmail": "jane@example.com",
  "amount": 49,
  "currency": "USD",
  "subscriptionStatus": "active",
  "paymentDate": "2026-07-01",
  "previousAmount": 99,
  "eventType": "downgrade"
}
Fired when a customer cancels their subscription. Refairn stops generating future recurring commissions for this customer from the cancellation date. Commissions already approved for prior billing periods are unaffected.
{
  "businessId": "business_123",
  "productId": "product_123",
  "customerEmail": "jane@example.com",
  "subscriptionStatus": "cancelled",
  "cancellationDate": "2026-07-15"
}
Notes:
  • Send this event on the effective cancellation date, not on the end-of-access date if your product offers access until the end of a billing cycle.
  • If the cancellation is reversed before it takes effect, send a customer.reactivated event.
The primary event that triggers commission calculation. Fired every time a qualifying payment is confirmed—whether it is an initial subscription, a renewal, or a one-time charge. Refairn looks up the referring agent for the customer’s email and queues the corresponding commission.Endpoint: POST /api/events/payment-succeeded
{
  "businessId": "business_123",
  "productId": "product_123",
  "customerEmail": "jane@example.com",
  "amount": 99,
  "currency": "USD",
  "subscriptionStatus": "active",
  "paymentDate": "2026-06-14"
}
Response:
{
  "success": true,
  "commissionId": "comm_abc123",
  "agentId": "agent_xyz456",
  "commissionAmount": 19.80,
  "commissionStatus": "pending",
  "holdUntil": "2026-06-28"
}
Notes:
  • Commission is held for a configurable period (default: 14 days) before it moves to approved status, to allow for refund and dispute windows.
  • If no agent attribution exists for this customer email, Refairn records the payment but does not create a commission.
Fired when a payment attempt is declined or fails. No commission is generated for failed payments. If your program tracks customer health signals for agent performance ratings, Refairn may record the failure as a risk event.
{
  "businessId": "business_123",
  "productId": "product_123",
  "customerEmail": "jane@example.com",
  "amount": 99,
  "currency": "USD",
  "subscriptionStatus": "past_due",
  "paymentDate": "2026-07-01",
  "failureReason": "card_declined"
}
Fired when a previously cancelled customer reactivates their subscription. Refairn applies the original agent’s attribution if the reactivation falls within your program’s attribution window. If the window has expired, the reactivation is treated as a new customer event with no agent attribution.
{
  "businessId": "business_123",
  "productId": "product_123",
  "customerEmail": "jane@example.com",
  "amount": 99,
  "currency": "USD",
  "subscriptionStatus": "active",
  "paymentDate": "2026-09-01",
  "eventType": "reactivation"
}
Notes:
  • The attribution window is configured per program in your commission settings.
  • If the same customer was referred by a different agent during the gap period, a conflict resolution rule applies. Contact support if you need to configure custom reactivation attribution logic.