A referral link can generate plenty of clicks and still produce zero attributable revenue. Reliable Paddle referral tracking depends on one value reaching checkout, surviving the payment handoff, and returning through the right webhook events.
Rewardful’s documented Paddle connection is built for Paddle Classic, not Paddle Billing. Build one testable flow before you recruit affiliates or promise commission terms.
Confirm the Platform Before You Build
Start with the payment product, not the affiliate campaign. Rewardful currently documents its Paddle integration for Paddle Classic only. If your account uses Paddle Billing, don’t assume this setup will work.
Read Rewardful’s Paddle Classic integration guide before adding scripts or webhooks. The naming looks similar, but the checkout methods and account configuration are different.
Paddle Classic Is Not Paddle Billing
Check the Paddle dashboard and your current checkout code. A Paddle Classic checkout normally uses Paddle.Checkout.open(), which is the documented handoff point for Rewardful referral data.
If your product has moved to Paddle Billing, stop here and confirm your tracking options with both vendors. Don’t copy a Classic passthrough setup into a Billing checkout and expect it to record referrals.
Set Clear Ownership First
Give one person ownership of checkout code, another ownership of Paddle events, and an affiliate manager ownership of campaign rules. One person can hold all three roles on a small team. The responsibility still needs to be clear.
Keep a simple implementation record with the campaign name, live checkout URL, Paddle product IDs, deployment date, webhook owner, and support contact. This makes a later attribution dispute much easier to investigate.
How Paddle referral tracking moves through the stack
The tracking flow is short. Each part has one job. A visitor arrives through an affiliate link, Rewardful identifies the referral, your checkout passes that identifier to Paddle, then Paddle events let Rewardful match the purchase.
Affiliate link -> Rewardful JavaScript -> referral ID -> Paddle checkout passthrough -> Paddle webhook -> Rewardful sale and commission record
Rewardful documents that it creates a unique referral ID when a visitor comes through an affiliate link. Your checkout must send that value inside Paddle’s passthrough payload.
The Referral ID Is the Handoff Point
The Rewardful referral value is a UUID string. It isn’t an affiliate name or a campaign label. Treat it as the attribution record that connects the visitor to the later payment event.
Rewardful checks the passthrough data in Paddle webhook notifications for a valid referral attribute. When it finds one, it can record the referred customer as a lead and retain basic payment metadata, such as customer details, checkout ID, and order ID. Its explanation of how Rewardful uses your Paddle account is useful for reviewing that data path.
Connect Paddle Classic to Rewardful
Set up the account connection before changing checkout code. This gives Rewardful the information it needs to receive and process Paddle Classic payment events.
Add the Paddle Public Key
In Paddle Classic, go to Developer Tools -> Public Key. Copy the full public key and paste it into Rewardful during the Paddle connection process.
Keep the BEGIN and END markers. Don’t paste an API key into this field. A missing line or omitted marker can block the connection even when the rest of the setup looks correct.
Register Rewardful’s Webhook Endpoint
Rewardful provides a webhook endpoint URL during setup. In Paddle Classic, add that URL under Developer Tools -> Events -> URLs for receiving webhooks.
Enable the event notifications listed in the current Rewardful setup screen, then save the Paddle settings. Event labels and dashboard menus can change, so use the live instructions instead of an old screenshot or copied event list.
Use Rewardful’s Paddle integration collection as the reference point when settings differ from your existing implementation.
- Create or open the Rewardful account and select Paddle as the payment processor.
- Paste the full Paddle Classic public key into Rewardful.
- Create the first affiliate or referral campaign and set its commission terms.
- Copy Rewardful’s webhook endpoint into Paddle Classic.
- Enable the required Paddle events and save the configuration.
Don’t replace Rewardful’s webhook URL with an internal endpoint. That breaks the native payment-to-commission path. Your own systems can receive separate notifications when your plan and configuration support them.
Install the Rewardful Script and Update Checkout
The JavaScript and passthrough configuration are where most Paddle referral tracking failures occur. A webhook can’t repair a referral ID that never reached checkout.
Load Rewardful Before a Buyer Opens Checkout
Install Rewardful’s current JavaScript snippet in the shared layout of pages where affiliate visitors land. This includes pricing pages, comparison pages, product pages, and in-app upgrade screens that accept referral traffic.
Use the installation code shown in your Rewardful dashboard or the live integration guide. Don’t substitute an old script tag from a previous implementation. Then test that window.Rewardful is available before the buyer opens Paddle Checkout.
Pass the Referral Value Through Paddle
Rewardful’s documented Classic checkout pattern gets the referral value with const referral = window.Rewardful && window.Rewardful.referral.
Your Paddle.Checkout.open() call then sends it as passthrough: JSON.stringify({ rewardful: { referral: referral } }).
Paddle receives a serialized JSON string, not a JavaScript object. If your checkout already uses passthrough for plan metadata, account IDs, or analytics fields, merge the Rewardful data into the existing payload. Don’t overwrite business-critical fields to add affiliate tracking.
Review every checkout path. A pricing-page button may use the updated checkout function while an in-app upgrade button still uses an old one. Purchases that bypass Paddle.Checkout.open() also bypass this documented referral handoff.
Set Campaign Rules Before You Send Links
Technical tracking is only half the program. Affiliates need terms that match the actual Rewardful campaign configuration.
Set the commission structure, eligible products, approval rules, payout timing, and treatment of refunds in one written policy. Then make the policy match the campaign settings in Rewardful.
Rewardful’s Paddle overview confirms the product connection, but your account plan and campaign options can affect what you can configure. The published integration guide doesn’t identify a separate Rewardful plan requirement for Paddle Classic. Check your own subscription before building a program around a setting you can’t access.
Track Approved Revenue, Not Click Volume
Clicks tell you that an affiliate generated interest. They don’t prove a sale was accepted or a commission is payable.
Keep a monthly record for each campaign with affiliate ID, campaign, referred customer, Paddle order ID, checkout ID, payment status, commission status, reversals, and final payout reference. Keep the first captured record intact. Store corrections as new notes or status changes.
A completed checkout test proves the handoff ran. It doesn’t prove that every commission rule, refund outcome, or payout status works as expected.
Rewardful’s Paddle-specific documentation doesn’t publish a fixed rule for recurring commissions, refunds, chargebacks, or clawbacks. Test those cases against your configured campaign and confirm any unclear policy before you publish affiliate terms.
Test the Full Attribution Path
Run tests with a clean browser session and a controlled affiliate link. Use a non-production environment if Paddle Classic and your account configuration make one available. Otherwise, limit live testing and record each test transaction.
A Paddle referral tracking test is accepted only when the evidence matches across the browser, Paddle, and Rewardful. Don’t mark it complete because a test button opened checkout.
Use this checklist:
- Open a newly generated affiliate link and confirm Rewardful creates a referral value before checkout opens.
- Trigger checkout from every live purchase path, including pricing pages and in-app upgrades.
- Confirm the checkout call includes the expected
rewardfulreferral object inside the serialized passthrough value. - Complete an approved test purchase and verify Paddle sends events to Rewardful’s configured webhook endpoint.
- Check Rewardful for the referred lead, sale record, affiliate attribution, and expected commission status.
- Reconcile the customer email, Paddle checkout ID, order ID, campaign, and commission record.
- Run a purchase without a referral link to confirm your normal checkout still works.
- Test a renewal, cancellation, refund, or disputed payment only after you define the expected outcome for that campaign.
Record the date, tester, affiliate link, referral ID, product, order ID, and result. Route failed or unclear tests into an exception list. Don’t keep retrying a broken setup without changing the likely cause.
If your internal CRM, data warehouse, or support system also needs referral events, use Rewardful’s Developer Center to review its API and webhook options. That is a separate outbound data flow from Paddle sending payment events to Rewardful.
Fix Common Tracking Failures
Start troubleshooting at the first missing record. Don’t begin with the final commission amount when the referral ID never reached checkout.
The Sale Has No Affiliate Attribution
First, confirm that the customer entered through a real affiliate link. Then check that the Rewardful script loaded and that the checkout function read a referral value.
Next, inspect the exact passthrough construction in the deployed checkout code. Common failures include a missing JSON.stringify(), the wrong property path, or another script replacing the passthrough payload.
Also confirm that the checkout is Paddle Classic. A Paddle Billing implementation isn’t covered by Rewardful’s documented Classic integration.
Paddle Shows a Payment but Rewardful Shows Nothing
Check the Rewardful webhook URL in Paddle Classic. Confirm it hasn’t been deleted, changed, or saved in the wrong event section. Then review whether the required event notifications are active.
Compare the payment’s Paddle checkout ID and order ID with the data in Rewardful. This identifies whether the problem is webhook delivery, payload matching, or campaign attribution.
For outbound Rewardful events sent to your own application, verify the request signature before accepting data. Use Rewardful’s signed webhook documentation rather than trusting an unsigned request.
For custom checkout builds, multiple product sites, or a migration between Paddle products, Book A Call after you document the checkout paths, owners, and failed test evidence.
Final Check Before You Launch
Paddle referral tracking works when the same referral value appears in the affiliate visit, checkout passthrough, Paddle event, and Rewardful record. One consistent attribution path matters more than a large affiliate launch.
Start with one campaign, one product, and a small approved test batch. Expand only after your team can reconcile the referral, order, commission, and payout records without correction work.
