# 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.

# 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.

<div
  style={{
    backgroundColor: '#f0f9ff',
    border: '1px solid #0369a1',
    borderRadius: '4px',
    padding: '12px 16px',
    margin: '16px 0',
    fontSize: '14px',
  }}
>
  💡 **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.
</div>

<Steps>

<Step>
### 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](https://files.affonso.io/assets/img/migration/firstpromoter-api-settings.png)

#### How to start the migration

1. Go to **[Settings → Migration](https://affonso.io/app/settings/team/migration)** in your Affonso dashboard
2. Click **Migrate** next to FirstPromoter
4. Enter your API Key and Account ID
5. 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.).

<div
  style={{
    backgroundColor: '#f0f9ff',
    border: '1px solid #0369a1',
    borderRadius: '4px',
    padding: '12px 16px',
    margin: '16px 0',
    fontSize: '14px',
  }}
>
  💡 **Safe to re-run.** The migration is idempotent — if you run it again, existing records will be skipped. No duplicates will be created.
</div>

</Step>

<Step>
### Replace the Tracking Script

#### Current FirstPromoter Script (Remove This)
```html
<!-- Remove this FirstPromoter script -->
<script
  src="https://cdn.firstpromoter.com/fpr.js"
  async
></script>
```

#### New Affonso Script (Add This)
```html
<!-- 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](https://affonso.io/app/affiliate-program)
- 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](/help/installation-guides/overview/gdpr-cookie-consent-integration) 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](/help/getting-started/overview#installation-guides).

</Step>

<Step>
### Update Referral Data Collection

#### How FirstPromoter Works (Current)
FirstPromoter provides referral data via a JavaScript callback and stores it in a cookie:
```javascript
// 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
```javascript
// Client-side approach (similar to FirstPromoter)
const referralId = window.affonso_referral || '';
```

##### Option 2: Server-Side (Cookie) - More Secure
```typescript
// 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'] ?? '';
```

<div
  style={{
    backgroundColor: '#f0f9ff',
    border: '1px solid #0369a1',
    borderRadius: '4px',
    padding: '12px 16px',
    margin: '16px 0',
    fontSize: '14px',
  }}
>
  💡 **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.
</div>

</Step>

<Step>
### 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**.

<div
  style={{
    backgroundColor: '#fdf2f8',
    border: '1px solid #881337',
    borderRadius: '4px',
    padding: '6px 10px',
    margin: '10px 0',
    fontSize: '13px',
  }}
>
  💡 **Connect your payment provider:** [Connect your payment provider](/help/getting-started/connect-payment-provider) to Affonso before migrating.
</div>

#### Migration Pattern (All Payment Providers)

**Before (FirstPromoter):**
```javascript
metadata: {
  fp_uid: referralId, // ❌ Remove this
}
```

**After (Affonso):**
```javascript
metadata: {
  affonso_referral: affonsoReferral, // ✅ Add this line
}
```

#### Stripe Example (Detailed)

##### Current FirstPromoter Integration
```javascript
// 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
```typescript
// 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 →](/help/integrations)

</Step>

<Step>
### 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:

```javascript
// 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


</Step>

</Steps>

---

## 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:
   ```json
   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

<div style={{ fontSize: '14px' }}>

- [ ] **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

</div>

---

## Need Help with Migration?

- **Technical Support**: [hello@affonso.io](mailto: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](mailto:hello@affonso.io) and we'll help you migrate from FirstPromoter to Affonso smoothly!