Signup & Lead Tracking

Signup tracking lets you attribute user registrations to affiliates. When a referred visitor signs up, the system creates a referral with status "LEAD" — visible in both your and your affiliate's dashboard.

Why Track Signups?

• Attribution — See which affiliates drive the most registrations
• Conversion rates — Calculate click-to-signup and signup-to-customer ratios
• Pay Per Lead — Reward affiliates per signup, not just per sale (learn more)
• Funnel insights — Optimize your funnel based on affiliate performance

Basic Usage

Call Affonso.signup() after a successful user registration:

// Pass the user's email
window.Affonso.signup('user@email.com');

That's it. The system checks for an existing affonso_referral cookie and creates the lead if the visitor came through an affiliate link. If there's no cookie, the call is silently ignored — so you can safely call it for every signup.

Advanced Usage: Options Object

Instead of a plain email string, you can pass an options object for more control:

window.Affonso.signup({
  email: 'user@email.com',       // optional
  externalUserId: 'user_123',    // optional
  name: 'John Doe'               // optional
});

Parameters

When to Use externalUserId

Use externalUserId when you want to:

• Track without email — Privacy-first setups where you don't want to share email addresses with the affiliate system
• Match users across systems — Pass your internal user ID so webhook events from your payment provider can be matched back to referrals via metadata.userId
• Use both — Pass email and externalUserId for maximum flexibility

// Privacy-first: track by internal ID only
window.Affonso.signup({
  externalUserId: 'usr_abc123'
});

// Full tracking: email + internal ID + name
window.Affonso.signup({
  email: user.email,
  externalUserId: user.id,
  name: user.name
});

Payment Provider Metadata

When using externalUserId, pass the same ID in your payment provider's metadata as userId so Affonso can match webhook events to referrals:

// Example: Stripe Checkout
const session = await stripe.checkout.sessions.create({
  // ... your config
  metadata: {
    userId: 'usr_abc123'  // same value as externalUserId
  }
});

This works with all supported payment providers (Stripe, Polar, Creem, Dodo, Paddle). Pass userId in the customer or subscription metadata field.

Privacy Controls

Program owners can control what data is stored via the affiliate program settings:

• Email tracking — Toggle whether email addresses are stored on referrals
• Name tracking — Toggle whether customer names are stored on referrals

When email tracking is disabled, referrals are matched and tracked using externalUserId instead. This is ideal for privacy-conscious setups or compliance with strict data protection requirements.

Configure these settings in your Affiliate Program settings under "Privacy Controls".

Best Practices

• Call for every signup — The system only creates a lead when a valid referral cookie exists
• Place after registration — Call after the user has successfully registered, not before
• Use double opt-in timing — If you require email verification, call signup() after verification for higher-quality leads
• Non-blocking — The function is asynchronous and won't affect your site's performance
• Deduplication — Duplicate calls are handled automatically

How It Works

1. Visitor clicks an affiliate link → tracking script stores affonso_referral cookie
2. Visitor signs up → you call window.Affonso.signup()
3. The function sends the signup data along with the cookie value to Affonso
4. Affonso creates a referral with status "LEAD"
5. The referral appears in both your and your affiliate's dashboard
6. When the user makes a purchase later, the referral status updates to "CUSTOMER"

Testing

1. Visit your site with ?atp=test to simulate an affiliate click
2. Complete your registration flow
3. Check your Affonso dashboard for the new lead
4. Verify the referral shows the correct data (email, name, or external ID)

Troubleshooting

Signup Not Tracking

• Verify the tracking script is installed on the signup page
• Ensure the visitor came through an affiliate link (check for affonso_referral cookie)
• Check the browser console for errors
• Confirm you're passing at least an email or externalUserId

Referral Shows No Email

• If you're using externalUserId only, this is expected behavior
• Check your Privacy Controls — email tracking may be disabled in your program settings

Need help? Contact our support team - we typically respond within 2 hours during business hours.