Overview

Refgrow integrates with Paddle to automatically track payments and calculate commissions for your affiliates.

Automatic tracking of one-time payments and subscriptions
Support for product-specific commission rates
Support for affiliate-specific commission overrides
Secure webhook implementation for real-time tracking
Works with Paddle Checkout and payment links

Setting Up Paddle Integration

Note: You will need a Paddle account to track payments. If you do not have one, sign up here.

Step 1: Create an API Key With the Right Permissions

In Paddle, go to Developer Tools, then Authentication, and create an API key. Paddle grants a key only the permissions you tick, so all four of these must be enabled:

Notifications (Read and Write) — lets us create and maintain the notification destination that delivers your events
Transactions (Read) — reads the purchase itself
Subscriptions (Read) — reads renewals so recurring commissions keep paying
Customers (Read) — reads the buyer's email

Customers (Read) is the one people miss. Paddle does not put the buyer's email in the webhook it sends us, only a customer id, so we ask Paddle who that is. Without this permission the key still saves, the connection still reports as healthy and events still arrive, but that lookup is refused. Sales that carry a referral code or an affiliate coupon are still attributed. A sale where the buyer simply clicked an affiliate link days earlier cannot be, because matching it needs the email. If this permission is missing, your Refgrow dashboard will tell you.

Sandbox and live keys are both supported and we detect which one you pasted. The key must come from the same Paddle environment as the product you are selling.

Step 2: Configure Webhook

Go to your project's "Integration" tab
Select "Paddle Webhooks" as your tracking method
Copy the provided webhook URL
In your Paddle dashboard, create a new webhook with the copied URL
Enable these events: transaction.completed, subscription.created, subscription.updated
Copy the webhook signing secret from Paddle
Paste the signing secret in Refgrow and click "Save Secret"

Step 3: Choose Your User Flow

Select the appropriate user conversion flow for your business:

Click → Signup → Purchase: Users create an account before making a purchase
Click → Purchase: Users can purchase directly without signing up first
Both: Your platform supports both flows

Passing Referral Codes to Paddle

Important: If you have a direct purchase flow (Click → Purchase), passing the referral code to Paddle is essential for correct attribution.

A referral code in Paddle custom data can identify the affiliate without a buyer email. The webhook handler still looks up the Paddle customer email when the event has a customer ID but no email. There is currently no setting to disable that lookup.

For Paddle Checkout

When creating a checkout on your server, pass the referral code in the custom data:

javascript

// Example (Node.js Server-Side)
const refCode = req.cookies['refgrow_ref_code_YOUR_PROJECT_ID']
  || req.cookies.refgrow_ref_code; // legacy Refgrow.setReferral cookie

const checkout = await paddle.checkouts.create({
  // ... other checkout parameters
  custom_data: {
    referral_code: refCode || null // Pass the code here
  }
});

For Paddle Payment Links

For payment links, use the automatic processing with JavaScript:

Automatic Processing with JavaScript

1. Add a special class to your payment links:

html

<a href="https://buy.paddle.com/product/xyz..." class="refgrow-paddle-link">Buy Now</a>

2. Call the helper function after the page loads:

javascript

// Call this once after the page loads
if (window.Refgrow) {
  Refgrow.processPaddleLinks();
  // Or use a custom selector: Refgrow.processPaddleLinks('.your-paddle-class');
}

Note: Refgrow will automatically append the referral code via custom data to the Paddle link if a referral cookie exists.

Commission Configuration

Default Commission Settings

Configure your default commission structure in your project settings:

Commission Type: Percentage or Fixed Amount
Commission Value: The percentage or fixed amount
Commission Duration: Lifetime, First Purchase, or Limited Period

Percentage commissions use Paddle's payout-currency subtotal after discounts and before tax. Paddle's processing fee is not deducted from this commission base.

Product-Specific Commissions

Override commission rates for specific products:

Go to your project's "Integration" tab
Scroll to "Product-Specific Commissions"
Click "Add Product Commission"
Select a Paddle product and set its unique commission rate

Note: Product-specific rates take priority over your default commission settings.

Affiliate-Specific Overrides

Set custom commission rates for individual affiliates:

Go to your "Affiliates" tab
Find the affiliate you want to customize
Click "Manage Override"
Set a custom commission type and value

Priority: Affiliate-specific overrides take highest priority, followed by product-specific commissions, with default settings as the fallback.

How It Works

1. Referral Click

User clicks an affiliate link and the refgrow_ref_code_YOUR_PROJECT_ID cookie is set.

2. Paddle Payment

The referral code is passed to Paddle, and the user completes payment.

3. Webhook Processing

Refgrow receives the webhook, attributes the sale, and calculates the commission.

Supported Webhook Events

Refgrow automatically listens for these webhook events:

transaction.completed - When a purchase is completed
subscription.created - When a new subscription is created
subscription.updated - When a subscription is updated

Troubleshooting

Webhooks Not Working

Verify your webhook signing secret is correctly set in your project settings
Check that the webhook endpoint was created with the correct URL: https://refgrow.com/webhook/paddle/{your-project-id}
Confirm all required events are enabled for the webhook
Check your Paddle dashboard for webhook delivery logs
Ensure the webhook is active and not paused

"You aren't permitted to perform this request"

This is Paddle refusing the key, and it always means a permission is missing rather than the key being wrong. Open the key under Developer Tools, then Authentication, and confirm all four permissions listed in Step 1 are enabled: Notifications (Read and Write), Transactions (Read), Subscriptions (Read) and Customers (Read). You can edit an existing key; there is no need to create a new one. Then paste it into Integration again.

Sales Are Arriving but Nobody Is Credited

If your dashboard shows the Paddle connection as working and purchases are being recorded with no affiliate against them, the usual cause is the Customers (Read) permission being absent from the key. Every sale then has to carry a referral code or an affiliate coupon to be attributed, because the buyer's email cannot be read. Add the permission and reconnect; sales after that point attribute normally.

Commissions Not Being Calculated

Verify that the customer email is included in the Paddle webhook data
Check that referral codes are being passed correctly via custom data
Ensure the affiliate exists in your Refgrow project
Verify that trial orders with $0 amount are not triggering commissions (this is expected behavior)
Check your commission settings and affiliate overrides

Attribution Issues

Verify that tracking.js is loaded on all pages
Check that the referral code cookie is being set correctly
For direct purchase flows, ensure you are using Refgrow.processPaddleLinks()
Verify that custom data is being passed to Paddle correctly
Check that the customer's email matches between the referral and the purchase

Next Steps

Once your Paddle integration is set up:

Set up payout methods for your affiliates