Background
⌘K

Migrate from FirstPromoter to Affonso

Complete guide to migrate your existing FirstPromoter affiliate program to Affonso — import your data automatically and replace the tracking integration.

Silvestro
Written by Silvestro
Updated more than a week ago

Migrate from FirstPromoter

If you're currently using FirstPromoter for your affiliate program and want to switch to Affonso, this guide will walk you through the full migration — from importing your existing data to replacing the tracking integration.

💡 Good news! Affonso has a built-in migration tool that automatically imports your campaigns, commission rules, promoters, referrals, and commissions from FirstPromoter. The entire process takes just a few minutes.

1

Import Your Existing Data

Affonso can automatically import your affiliate data from FirstPromoter — no CSV exports or manual work needed.

What you'll need

  • Your FirstPromoter API Key
  • Your FirstPromoter Account ID

You'll find both in your FirstPromoter dashboard under Settings → Integrations → API integration.

FirstPromoter API integration settings

How to start the migration

  1. Go to Settings → Migration in your Affonso dashboard
  2. Click Migrate next to FirstPromoter
  3. Enter your API Key and Account ID
  4. Click Start Migration

The migration runs in the background — you'll see real-time progress in the dialog and receive an email when it's done.

What data is migrated?

The migration imports five types of data:

  • Campaigns → Groups — Each FirstPromoter campaign is created as an affiliate group in Affonso. The default campaign becomes the default group. Affiliates are automatically assigned to the correct group based on their campaign membership.
  • Rewards → Incentives — Commission rules (percentage or flat amount, duration, type) are imported as incentives and linked to the corresponding groups. Supported types include cash commissions, free months, credits, and points.
  • Promoters — Name, email, and payout details (PayPal, bank). Only accepted promoters with at least one referral are imported — dormant or pending promoters are skipped to keep your program clean. If a promoter has customized rewards that differ from their campaign, individual overrides are created automatically.
  • Referrals — Name, email, customer ID, and status. Linked to the correct affiliate automatically.
  • Commissions — Sale amounts, commission earnings, currency, and their status (pending, approved, paid, etc.).

💡 Safe to re-run. The migration is idempotent — if you run it again, existing records will be skipped. No duplicates will be created.

2

Replace the Tracking Script

Current FirstPromoter Script (Remove This)

<!-- Remove this FirstPromoter script -->
<script
  src="https://cdn.firstpromoter.com/fpr.js"
  async
></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_ID with your program ID from the Affonso dashboard
  • Set YOUR_COOKIE_DURATION to 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 FirstPromoter, 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.

3

Update Referral Data Collection

How FirstPromoter Works (Current)

FirstPromoter provides referral data via a JavaScript callback and stores it in a cookie:

// FirstPromoter approach
window.fpr("referral_id", function(referralId) {
  // use referralId
});

// Or directly from the cookie
const referralId = document.cookie
  .split('; ')
  .find(row => row.startsWith('_fprom_tid='))
  ?.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) - Similar to FirstPromoter
// Client-side approach (similar to FirstPromoter)
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: If you're currently using FirstPromoter's callback or _fprom_tid cookie, you can easily switch to window.affonso_referral or the affonso_referral cookie with minimal changes. We recommend the server-side cookie approach for better security.

4

Update Payment Provider Integration

The core principle is simple: replace fp_uid with affonso_referral in your payment provider's metadata. This works with all supported payment providers.

💡 Connect your payment provider: Connect your payment provider to Affonso before migrating.

Migration Pattern (All Payment Providers)

Before (FirstPromoter):

metadata: {
  fp_uid: referralId, // ❌ Remove this
}

After (Affonso):

metadata: {
  affonso_referral: affonsoReferral, // ✅ Add this line
}

Stripe Example (Detailed)

Current FirstPromoter Integration
// Old FirstPromoter way - REPLACE THIS
const session = await stripe.checkout.sessions.create({
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  metadata: {
    fp_uid: referralId, // ❌ 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',
});

Integration Guides for All Payment Providers

View all payment provider integration guides →

5

Optional - Track User Signups

While FirstPromoter required explicit signup tracking, Affonso can work without it, but we strongly recommend implementing it 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

  1. Visit your site with ?atp=test (Affonso's test affiliate parameter)
  2. Check browser DevTools → Application → Cookies → look for affonso_referral
  3. The cookie should contain a value like cmdhq6ayf...

2. Test Stripe Integration

  1. Trigger your checkout flow locally with the test referral
  2. Check your server logs/terminal - the Stripe session should show: 
    metadata: { affonso_referral: "cmdhq6ayf..." }
  3. 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

  • Import data from FirstPromoter — Use the automatic migration tool in Settings (campaigns, rewards, promoters, referrals, commissions)
  • Replace tracking script — Remove FirstPromoter script, add Affonso script
  • Choose referral data method — Client-side (window.affonso_referral) OR server-side (cookie)
  • Update payment provider metadata — Change fp_uid to affonso_referral
  • Connect payment provider to Affonso dashboard (Stripe, Polar, Creem, or Dodo)
  • Test referral tracking with ?atp=test parameter
  • Test payment integration with server logs or live testing
  • Optional: Add signup tracking for better insights

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 FirstPromoter to Affonso smoothly!

Was this article helpful?

If you still need help, our support team is here for you.

Contact Support
bg

Ready to Scale Your SaaS?

Affonso is the easiest way to launch your own affiliate program. We take care of the technical stuff, so you can focus on growing your business.