Conversion Tracking

Conversion tracking connects completed purchases to affiliate referrals, enabling accurate commission calculation. This guide explains how conversions are tracked and attributed.

How Conversions Work

Automatic Tracking (Stripe)

For Stripe payments, conversions are tracked automatically:

1. Customer completes purchase
2. Stripe sends invoice.paid webhook
3. AffiliateBase matches client_reference_id to referral
4. Conversion recorded, commission created

The Conversion Flow

Customer clicks affiliate link
        ↓
Referral ID stored (cookie + window)
        ↓
Customer adds to cart, starts checkout
        ↓
Your code passes referral ID to Stripe
        ↓
Customer completes payment
        ↓
Stripe webhook fires
        ↓
AffiliateBase creates conversion + commission

Stripe Integration Details

What Gets Tracked

• Checkout Sessions: One-time and subscription payments
• Subscriptions: Initial and recurring payments
• Invoices: Any paid invoice

Required: client_reference_id

For attribution to work, include the referral ID:

const session = await stripe.checkout.sessions.create({
  // ... other options
  client_reference_id: window.affiliatebase_referral,
});

Webhook Events

AffiliateBase listens for:

• invoice.paid - Primary conversion event
• checkout.session.completed - Session data capture

Conversion Types

One-Time Purchases

Single payment products:

• Commission created immediately
• One-time commission amount
• Status: pending → due → paid

Subscriptions

Recurring payment products:

• Initial conversion when first payment succeeds
• Recurring commissions on each renewal (if enabled)
• Tied to subscription lifetime

Promo Code Conversions

When customer uses an affiliate’s promo code:

• Code matched to affiliate
• Commission created
• Takes priority over cookie attribution

Conversion States

State	Description
New	Just created from webhook
Confirmed	Verified and processed
Disputed	Under review

Commission Creation

When a conversion is recorded:

1. Match referral: Find the affiliate from referral ID or promo code
2. Calculate amount: Apply commission rate to order total
3. Create commission: Record with pending status
4. Notify (optional): Email affiliate about new earning

Commission Calculation

Order total: $100
Commission rate: 20%
Commission amount: $20

For subscriptions:
Monthly price: $50
Commission rate: 20%
Initial commission: $10
Recurring (each month): $10 (if recurring enabled)

Manual Conversion Tracking

When to Use

• Non-Stripe payment processors
• Offline conversions
• Custom attribution scenarios

API Method

// Server-side: Create conversion via API
await fetch('https://api.affiliatebase.com/v1/conversions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    referral_id: 'referral-uuid',
    amount: 10000, // cents
    currency: 'usd',
    order_id: 'your-order-id',
  }),
});

Client-Side Method

// Track conversion from browser
window.affiliatebase('convert', {
  email: 'customer@example.com',
  amount: 100.00,
  orderId: 'order-123',
});

Conversion Attribution Rules

Priority Order

1. Promo code: Highest priority
2. Referral ID: From client_reference_id
3. Cookie: Fallback if no explicit ID

Matching Logic

If promo_code exists → Find affiliate by code
Else if client_reference_id exists → Find referral by ID
Else if customer email matches referral → Use that referral
Else → No attribution

Testing Conversions

Stripe Test Mode

1. Use Stripe test API keys
2. Make test purchases with card 4242 4242 4242 4242
3. Conversions appear in AffiliateBase immediately
4. No real money involved

Verification Steps

1. Click affiliate link (set referral)
2. Start checkout, verify client_reference_id passed
3. Complete purchase
4. Check AffiliateBase dashboard for conversion
5. Verify correct affiliate credited

Viewing Conversions

In Dashboard

Navigate to Dashboard or Referrals to see:

• Recent conversions
• Conversion details
• Attributed affiliate
• Commission amount

Conversion Details

Each conversion shows:

• Order ID
• Amount
• Customer (email)
• Affiliate credited
• Commission created
• Timestamp

Handling Issues

Duplicate Conversions

AffiliateBase prevents duplicates:

• Same order ID only creates one conversion
• Webhook retries are handled
• Idempotency built-in

Missing Conversions

If a conversion didn’t track:

1. Check Stripe webhook logs
2. Verify client_reference_id was included
3. Confirm referral existed before purchase
4. Review attribution window timing

Wrong Attribution

If wrong affiliate was credited:

1. Check client_reference_id value
2. Review promo code usage
3. Check cookie state at purchase
4. May require manual adjustment

Refunds and Cancellations

Automatic Handling

When a refund occurs:

• Stripe sends refund webhook
• Commission is voided
• No payout for voided commissions

Partial Refunds

Behavior options:

• Void entire commission
• Recalculate commission
• Configurable per program

Subscription Cancellations

When subscription cancels:

• No more recurring commissions
• Past commissions unaffected
• Handled automatically

Best Practices

For Reliable Tracking

1. Always pass referral ID to Stripe
2. Test webhook delivery regularly
3. Monitor for failed webhooks in Stripe
4. Use promo codes as backup attribution

For Accuracy

1. Reconcile regularly between Stripe and AffiliateBase
2. Review suspicious patterns for fraud
3. Handle refunds promptly to avoid payout issues

Next Steps

• Configure attribution windows
• Learn about handling refunds
• Set up payout schedules