How to Track Affiliate Conversions with Paddle

Paddle is one of the most popular payment platforms for SaaS companies, handling everything from checkout to tax compliance as a merchant of record. But when it comes to running an affiliate program on top of Paddle, you need a conversion tracking system that understands Paddle's unique architecture — its notification system, trial-to-paid flows, and how it handles upgrades and downgrades.

This guide walks you through setting up affiliate conversion tracking with Paddle using Refgrow. We'll cover the integration step by step, explain Paddle-specific scenarios you need to handle, and show you how to verify that every conversion is accurately tracked and attributed.

Understanding Paddle's Notification System

Unlike Stripe and LemonSqueezy which use traditional webhooks, Paddle uses a notification system (formerly called webhooks in Paddle Classic, now called Events/Notifications in Paddle Billing). The concept is the same — HTTP POST requests sent to your endpoint — but there are important differences in payload structure and event types.

Paddle Billing vs. Paddle Classic

Paddle has two versions of their API:

• Paddle Billing (the current version): Uses a RESTful API with structured JSON payloads and event-driven notifications. This is what new Paddle accounts use.
• Paddle Classic: The legacy system with a different event format. If you've been on Paddle for years, you might still be on Classic.

Refgrow supports both versions. During setup, you'll select which Paddle version you're using, and Refgrow will parse the notification payloads accordingly.

Key Notification Events for Affiliate Tracking

For affiliate conversion tracking, these Paddle Billing events are critical:

1. transaction.completed: Fired when a payment is successfully processed. This is your primary conversion trigger for one-time purchases and initial subscription payments.
2. subscription.created: Fired when a new subscription is created. Contains the subscription ID, plan details, and customer information.
3. subscription.updated: Fired on plan changes — upgrades, downgrades, quantity changes, and pause/resume actions.
4. subscription.canceled: Fired when a subscription is cancelled. Important for tracking churn and adjusting future commission calculations.
5. transaction.refunded: Fired when a refund is issued. Refgrow uses this to automatically reverse or adjust affiliate commissions.
6. subscription.activated: Fired when a subscription moves from trialing to active (the first payment succeeds after a trial period). This is a Paddle-specific event that's crucial for trial-based SaaS products.

Paddle as Merchant of Record: What This Means for Tracking

Paddle acts as the merchant of record, meaning Paddle is technically the seller — they handle tax collection, invoicing, and payment processing. Your customers pay Paddle, and Paddle pays you (minus their fees). This has an important implication for affiliate tracking:

• The checkout happens on Paddle's domain (or in a Paddle overlay), not your domain.
• You need to pass referral attribution data through Paddle's custom data or passthrough fields so it survives the checkout redirect.
• Refgrow handles this seamlessly — the tracking script attaches the referral code to the Paddle checkout session before the customer is redirected.

Step-by-Step: Setting Up Paddle Conversion Tracking

Prerequisites

Before starting the integration, ensure you have:

• An active Refgrow account (start a free 14-day trial if you don't have one).
• A Paddle account with at least one product or subscription plan configured.
• Refgrow's tracking script installed on your website.
• Access to your Paddle dashboard with admin permissions.

Step 1: Connect Your Paddle API Credentials

Generate API credentials in Paddle:

1. Log into your Paddle dashboard and navigate to Developer Tools → Authentication.
2. Click Generate API Key. Select the permissions needed: read access to transactions, subscriptions, and customers.
3. Copy the API Key.
4. Also note your Seller ID (visible in your Paddle account settings) and your Client-Side Token (used for checkout integration).

Now connect these to Refgrow:

1. In your Refgrow dashboard, go to Project Settings → Integrations.
2. Select Paddle from the payment provider list.
3. Choose your Paddle version: Paddle Billing or Paddle Classic.
4. Enter your API Key, Seller ID, and Client-Side Token.
5. If you're using Paddle's sandbox environment for testing, check the Sandbox Mode toggle.
6. Click Save & Verify. Refgrow validates the credentials by making a test API call to Paddle.

Step 2: Configure the Webhook Notification URL

With credentials connected, set up the notification destination in Paddle:

1. In your Refgrow project settings, copy the Paddle Webhook URL. It follows this format: https://app.refgrow.com/webhook/paddle/YOUR_PROJECT_ID
2. Copy the Webhook Secret Key that Refgrow generates.
3. In your Paddle dashboard, go to Developer Tools → Notifications.
4. Click New Destination.
5. Set the Type to "Webhook."
6. Paste the Refgrow webhook URL as the Endpoint URL.
7. Subscribe to the following events:
   • transaction.completed
   • transaction.refunded
   • subscription.created
   • subscription.updated
   • subscription.activated
   • subscription.canceled
8. Enter a description like "Refgrow Affiliate Tracking" and click Save.

Security note: Refgrow verifies every incoming Paddle notification using the webhook signature. Paddle signs each notification with your secret key using HMAC, and Refgrow validates this signature before processing. Tampered or spoofed requests are rejected immediately.

Step 3: Set Up Checkout Attribution

For Refgrow to know which affiliate referred a customer, the referral code must travel from your website to the Paddle checkout. There are two approaches depending on your checkout setup.

Paddle.js Overlay Checkout

If you're using Paddle's JavaScript checkout overlay (the most common approach), Refgrow's tracking script automatically injects the referral code into the checkout's customData field:

Paddle.Checkout.open({
  items: [{ priceId: 'pri_abc123', quantity: 1 }],
  customData: {
    referral_code: 'AFFILIATE_CODE' // Injected by Refgrow automatically
  }
});

You don't need to write this code yourself — Refgrow's tracking script intercepts the Paddle.Checkout.open() call and appends the referral data. Just make sure the tracking script is loaded before your checkout code runs.

Hosted Checkout (Redirect)

If you redirect customers to Paddle's hosted checkout page, Refgrow appends the referral code as a URL parameter. The parameter is passed through to the notification payload as custom data, ensuring attribution survives the redirect.

Step 4: Test with a Purchase

Paddle offers a sandbox environment that's perfect for testing your integration without processing real payments.

1. Make sure both Paddle and Refgrow are set to Sandbox/Test mode.
2. In Refgrow, create a test affiliate (or use your own affiliate account) and copy their referral link.
3. Open the referral link in a private/incognito browser window to simulate a new visitor.
4. Navigate to your product page and initiate a Paddle checkout.
5. Use Paddle's test card number: 4242 4242 4242 4242 with any future expiry date and any CVC.
6. Complete the purchase.

Within a few seconds, check your Refgrow dashboard under Conversions. You should see the new conversion with:

• The correct affiliate attribution.
• The transaction amount and calculated commission.
• The Paddle transaction ID for cross-referencing.
• The notification event type that triggered the conversion.

Handling Paddle-Specific Scenarios

Paddle has several unique behaviors that your affiliate tracking needs to handle correctly. Refgrow accounts for all of these automatically, but it's important to understand what's happening behind the scenes.

Trials That Convert to Paid

Many SaaS products offer free trials through Paddle. Here's how the conversion flow works:

1. A referred customer signs up for a trial. Paddle fires subscription.created with a trialing status.
2. Refgrow records the referral attribution at this point but does not create a commission — no money has changed hands yet.
3. When the trial ends and the first payment succeeds, Paddle fires subscription.activated.
4. Now Refgrow creates the conversion and calculates the commission based on the actual payment amount.

This approach prevents a common problem: paying affiliates for trial signups that never convert to paid. Refgrow only generates commissions when real revenue is collected.

Upgrades and Downgrades

When a customer changes their subscription plan, Paddle fires a subscription.updated event followed by a transaction.completed for the prorated charge (upgrade) or credit (downgrade). Refgrow handles both:

• Upgrades: The affiliate earns a commission on the additional revenue. If a customer upgrades from $49/mo to $99/mo, the affiliate earns their commission rate on the $50 difference (prorated for the billing period).
• Downgrades: The affiliate's future recurring commissions adjust to the new, lower plan price. No clawback is applied to past commissions — the affiliate was paid correctly at the time.

Paddle's Revenue Share Model

Because Paddle is the merchant of record, the amount you receive is net of Paddle's fees and taxes. Refgrow calculates affiliate commissions based on the net revenue you receive, not the gross amount the customer pays. This ensures you're not paying commissions on money that goes to Paddle's fees or to tax authorities.

You can configure this in Refgrow under Project Settings → Commission Settings → Commission Base. Options include:

• Net revenue (recommended): Commission calculated on the amount after Paddle's fees and taxes.
• Gross revenue: Commission calculated on the full customer payment amount (more generous to affiliates but reduces your margins).

Multi-Currency Handling

Paddle supports localized pricing in multiple currencies. When a customer pays in EUR but your payout currency is USD, Refgrow uses the converted amount from Paddle's notification payload (which reflects the actual amount settled to you) for commission calculation. This eliminates currency conversion discrepancies between what the customer paid and what the affiliate earns.

Subscription Pausing and Resuming

Paddle allows customers to pause their subscriptions. When a subscription is paused:

• Paddle fires a subscription.updated event with a paused status.
• Refgrow stops generating recurring commissions for that subscription during the pause period.
• When the customer resumes (another subscription.updated event), recurring commission tracking resumes automatically.

Troubleshooting Common Issues

Notifications Not Reaching Refgrow

If conversions aren't appearing after a purchase, follow this checklist:

1. Check Paddle's notification logs: In your Paddle dashboard under Developer Tools → Notifications, click on your Refgrow destination. You'll see a log of all sent notifications with their delivery status (success, failed, retrying).
2. Verify the endpoint URL: Make sure the URL matches exactly: https://app.refgrow.com/webhook/paddle/YOUR_PROJECT_ID. A missing trailing slash or wrong project ID will cause delivery failures.
3. Check Refgrow's webhook logs: In your Refgrow dashboard under Webhooks → Logs, look for any received notifications with error status. Common errors include signature validation failures and unrecognized event types.
4. Sandbox vs. Live mismatch: If you're testing in Paddle's sandbox but your Refgrow integration is configured for live mode (or vice versa), notifications will fail. Make sure both are in the same mode.

Conversions Tracked but No Attribution

If conversions appear in Refgrow but aren't attributed to any affiliate (showing as "organic"), the referral code didn't make it through the checkout:

• Check the tracking script: Verify Refgrow's tracking script is loaded on your website by checking the browser console for the Refgrow initialization message.
• Inspect checkout custom data: Use browser developer tools to intercept the Paddle checkout request and verify that the customData field contains the referral code.
• Cookie status: Check that the referral cookie exists in the browser's cookie storage. If your site uses aggressive cookie policies or the customer is using Safari's ITP restrictions, the cookie might have been cleared.

Commission Amounts Don't Match Expected Values

If the commission amount seems wrong, check these settings:

• Commission base: Are you calculating on net or gross revenue? The Paddle fee (typically 5% + $0.50) can make a noticeable difference.
• Product-specific overrides: If you have product-specific commission rates configured, make sure the correct Paddle price ID is mapped.
• Affiliate-specific overrides: Check if the specific affiliate has a custom commission rate that differs from the project default.
• Currency conversion: For multi-currency transactions, the commission is based on the settled amount in your payout currency, which may differ from the customer's payment currency.

Comparing Manual Tracking vs. Automated Paddle Integration

Some teams attempt to track Paddle affiliate conversions manually — downloading CSV exports, matching customer emails to affiliate referrals in spreadsheets, and calculating commissions by hand. This approach has severe limitations:

Aspect	Manual Tracking	Automated (Refgrow + Paddle)
Conversion speed	Daily or weekly batch updates	Real-time (seconds)
Trial-to-paid tracking	Requires manual follow-up	Automatic on subscription.activated
Upgrade/downgrade handling	Complex proration calculations	Automatic with correct proration
Refund clawbacks	Manual identification and adjustment	Automatic commission reversal
Multi-currency	Manual exchange rate lookups	Uses Paddle's settled amounts
Affiliate dashboard	Periodic email reports	Real-time self-service dashboard
Audit trail	Scattered across spreadsheets	Complete notification log

With Paddle's complexity — trials, prorations, multi-currency, merchant-of-record accounting — manual tracking isn't just tedious, it's error-prone. Automated integration removes these risks entirely.

What Happens After Tracking

Once a Paddle conversion is tracked in Refgrow, the automation pipeline continues:

1. Commission calculation: Applied using your configured rates — project default, product-specific, or affiliate-specific overrides.
2. Affiliate notification: The affiliate sees the conversion in their real-time dashboard widget. Email notifications are sent if enabled.
3. Balance accumulation: The commission adds to the affiliate's pending balance.
4. Payout processing: When the payout threshold is reached, Refgrow processes payments via PayPal, Wise, or manual bank transfer. Each payout includes a detailed breakdown of the conversions it covers.
5. Recurring tracking: For subscriptions, every renewal payment triggers a new commission entry. The affiliate earns as long as their referred customer stays subscribed.

Start Tracking Paddle Conversions Today

Paddle's merchant-of-record model simplifies your tax and compliance burden, but it adds complexity to affiliate tracking. Refgrow bridges that gap — handling Paddle's notification system, trial-to-paid flows, prorated upgrades, multi-currency settlements, and refund clawbacks automatically.

The entire setup takes under 15 minutes: connect your Paddle credentials, configure the notification destination, and verify with a test purchase. From that point forward, every referred conversion is tracked, attributed, and ready for payout — without you lifting a finger.

Start your free 14-day trial and connect your Paddle account today. No credit card required, and your affiliate tracking can be live before lunch.