Migrate from Tolt
If you're currently using Tolt 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 partners, customers, and commissions from Tolt. The entire process takes just a few minutes.
Import Your Existing Data
Affonso can automatically import your affiliate data from Tolt — no CSV exports or manual work needed.
What you'll need
-
Your Tolt API Key — find it in your Tolt dashboard under Settings → Integrations
-
Your Tolt Program ID — find it in your Tolt dashboard under Program Settings → General
How to start the migration
- Go to Settings → Migration in your Affonso dashboard
- Click Migrate next to Tolt
- Enter your API Key and Program ID
- 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 three types of data:
- Partners — Name, email, and payout details (PayPal, bank). Only active partners with at least one customer are imported.
- Customers — Name, email, customer ID, and status. Linked to the correct affiliate automatically.
- Commissions — Sale amounts, commission earnings, 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.
Replace the Tracking Script
Current Tolt Script (Remove This)
<!-- Remove this Tolt script -->
<script
async
src="https://cdn.tolt.io/tolt.js"
data-tolt="YOUR-TOLT-PUBLIC-ID"
></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 Tolt, 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 Tolt Works (Current)
Tolt provides referral data via a global JavaScript variable:
// Tolt approach
const referralId = window.tolt_referral;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 Tolt
// Client-side approach (similar to Tolt)
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 window.tolt_referral client-side, you can easily switch to window.affonso_referral with minimal changes. However, we recommend the server-side cookie approach for better security.
Update Payment Provider Integration
The core principle is simple: replace tolt_referral 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 (Tolt):
metadata: {
tolt_referral: req.body.referral, // ❌ Remove this
}After (Affonso):
metadata: {
affonso_referral: affonsoReferral, // ✅ Add this line
}Stripe Example (Detailed)
Current Tolt Integration
// Old Tolt way - REPLACE THIS
const session = await stripe.checkout.sessions.create({
success_url: 'https://example.com/success',
cancel_url: 'https://example.com/cancel',
metadata: {
tolt_referral: req.body.referral, // ❌ 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
Optional - Track User Signups
While Tolt 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
- 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
- Import data from Tolt — Use the automatic migration tool in Settings
- Replace tracking script — Remove Tolt script, add Affonso script
- Choose referral data method — Client-side (
window.affonso_referral) OR server-side (cookie) - Update payment provider metadata — Change
tolt_referraltoaffonso_referral - 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
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 Tolt to Affonso smoothly!
