Migrate from Dub
If you're currently using Dub for your affiliate program and want to switch to Affonso, this guide will walk you through the migration process step by step. Dub's integration approach is a bit different from other platforms since it uses API-based conversion tracking, but the migration to Affonso is still straightforward.
💡 Good news! If you already have Dub integrated with Stripe, migrating to Affonso simplifies your setup. Instead of Dub's API-based lead and sale tracking, Affonso uses a simple metadata field in your payment provider - no extra API calls needed.
Ready to migrate? Let's get your affiliate program running on Affonso in just a few steps:
Replace the Tracking Script
Current Dub Script (Remove This)
<!-- Remove this Dub script -->
<script
src="https://www.dubcdn.com/analytics/script.js"
defer
></script>New Affonso Script (Add This)
<!-- Add this Affonso script instead -->
<script
async
defer
src="https://cdn.affonso.io/js/pixel.min.js"
data-affonso="YOUR_PUBLIC_PROGRAM_ID"
data-cookie_duration="YOUR_COOKIE_DURATION"
></script>- Replace
YOUR_PUBLIC_PROGRAM_IDwith your program ID from the Affonso dashboard - Set
YOUR_COOKIE_DURATIONto how many days the tracking should persist
🍪 Need GDPR/Cookie Consent compliance? Add
data-requires-consent="true"to the script above and follow our GDPR integration guide for privacy-first tracking.
Where to add it: Just like with Dub, add this script to the <head> tag on every page of your website (or at least your landing pages) to ensure no referrals are missed.
Installation Guides
Need help installing the script on your specific platform? Check out our detailed installation guides.
Update Referral Data Collection
How Dub Works (Current)
Dub stores a dub_id cookie when a visitor clicks an affiliate link and uses API-based tracking for leads and sales:
// Dub approach - reads the dub_id cookie
const dubId = document.cookie
.split('; ')
.find(row => row.startsWith('dub_id='))
?.split('=')[1];How Affonso Works (New)
Affonso provides referral data in two ways - you can choose the approach that fits your existing setup:
Option 1: Client-Side (JavaScript)
// Client-side approach
const referralId = window.affonso_referral || '';Option 2: Server-Side (Cookie) - More Secure
// Server-side approach (recommended for security)
// Next.js 15+ example
import { cookies } from 'next/headers';
const cookieStore = await cookies();
const affonsoReferral = cookieStore.get('affonso_referral')?.value || '';
// Next.js 13-14 example
const cookieStore = cookies();
const affonsoReferral = cookieStore.get('affonso_referral')?.value || '';
// Express.js example
const affonsoReferral = req.cookies.affonso_referral || '';
// PHP example
$affonsoReferral = $_COOKIE['affonso_referral'] ?? '';💡 Migration Tip: With Affonso, you no longer need separate API calls to track leads and sales. Just pass the affonso_referral value in your payment provider's metadata, and Affonso handles the rest automatically via webhooks.
Update Payment Provider Integration
With Dub, you had to pass dubCustomerExternalId and optionally dubClickId in your Stripe metadata. With Affonso, you simply replace these with a single affonso_referral field.
💡 Connect your payment provider: Connect your payment provider to Affonso before migrating.
Migration Pattern (All Payment Providers)
Before (Dub):
metadata: {
dubCustomerExternalId: user.id, // ❌ Remove this
dubClickId: dub_id, // ❌ Remove this
}After (Affonso):
metadata: {
affonso_referral: affonsoReferral, // ✅ Add this line
}Stripe Example (Detailed)
Current Dub Integration
// Old Dub way - REPLACE THIS
const session = await stripe.checkout.sessions.create({
customer_email: user.email,
success_url: 'https://example.com/success',
cancel_url: 'https://example.com/cancel',
metadata: {
dubCustomerExternalId: user.id, // ❌ Remove this
},
line_items: [
{price: 'price_H5vtDq1fbrJ', quantity: 1},
],
mode: 'subscription',
});New Affonso Integration
// New Affonso way - USE THIS
import { cookies } from 'next/headers';
// Get Affonso referral data
const cookieStore = await cookies(); // Next.js 15+
const affonsoReferral = cookieStore.get('affonso_referral')?.value || '';
const session = await stripe.checkout.sessions.create({
success_url: 'https://example.com/success',
cancel_url: 'https://example.com/cancel',
metadata: {
affonso_referral: affonsoReferral, // ✅ Add this line
},
line_items: [
{price: 'price_H5vtDq1fbrJ', quantity: 1},
],
mode: 'subscription',
});💡 Simpler setup! With Dub, you needed to manage dubCustomerExternalId, dubClickId, and sometimes client_reference_id. With Affonso, a single affonso_referral metadata field handles everything.
Remove Dub Lead & Sale Tracking API Calls
If you were using Dub's API to track lead and sale events, you can remove those calls entirely. Affonso tracks conversions automatically through payment provider webhooks - no extra API integration needed.
// ❌ Remove any Dub lead/sale tracking calls like these:
await dub.track.lead({ ... });
await dub.track.sale({ ... });Integration Guides for All Payment Providers
Optional - Track User Signups
With Dub, you had to track lead events via their API. With Affonso, signup tracking is optional but strongly recommended for better insights.
Add this code after your user registration logic:
// Simple: pass the user's email
window.Affonso.signup(userEmail);
// Advanced: pass an options object
window.Affonso.signup({
email: userEmail, // optional
externalUserId: userId, // optional
name: userName // optional
});At least one of email or externalUserId is required when using the object format.
Benefits of signup tracking:
- See which affiliates drive the most registrations
- Calculate conversion rates from clicks to signups
- Optimize your funnel based on affiliate performance
Testing Your Migration
1. Test Referral Tracking
- Visit your site with
?atp=test(Affonso's test affiliate parameter) - Check browser DevTools → Application → Cookies → look for
affonso_referral - The cookie should contain a value like
cmdhq6ayf...
2. Test Stripe Integration
- Trigger your checkout flow locally with the test referral
- Check your server logs/terminal - the Stripe session should show:
metadata: { affonso_referral: "cmdhq6ayf..." } - If the metadata appears correctly, you're all set!
3. Live Testing
Note: Use 100% discount codes for live testing without actual payments, or test locally with server logs - Stripe test mode purchases won't appear in Affonso's dashboard.
Migration Checklist
- Replace tracking script - Remove Dub analytics script, add Affonso script
- Choose referral data method - Client-side (
window.affonso_referral) OR server-side (cookie) - Update payment provider metadata - Replace
dubCustomerExternalId/dubClickIdwithaffonso_referral - Remove Dub API calls - Remove any
dub.track.lead()ordub.track.sale()calls - Connect payment provider to Affonso dashboard (Stripe, Polar, Creem, or Dodo)
- Test referral tracking with
?atp=testparameter - Test payment integration with server logs or live testing
- Optional: Add signup tracking for better insights
- Update affiliate links to use new Affonso format (if needed)
- Migrate affiliate data (contact support if needed)
Import Your Existing Affiliates
Don't forget to bring your existing affiliates with you! You can easily import your affiliate data from Dub (or any other platform) using our self-service CSV import feature.
What you can import:
- Affiliate names and email addresses
- Custom tracking parameters for their links
- PayPal payment information
- Up to 1,000 affiliates per import
📖 Learn how to import affiliate data →
Need Help with Migration?
- Technical Support: hello@affonso.io - We typically respond within 2 hours during business hours
- Migration Assistance: Our team can help you migrate your existing affiliate data and test the integration
- Custom Setup: Need help with a complex migration? We offer personalized migration support
Questions about your specific setup? Contact our support team and we'll help you migrate from Dub to Affonso smoothly!
