How to Set Up an Affiliate or Referral Program With Paddle

Set up an affiliate or referral program on Paddle Billing: pass the partner in custom data, commission on transaction.completed, and reverse refunds.

Muzahid Maruf — Founder of TrackRev.io

Muzahid MarufUpdated

Affiliate programs · 8 min read
On this page
  1. 01How does Paddle affiliate tracking work?
  2. 02How to set up an affiliate program with Paddle, step by step
  3. 03How do you set up a referral program on Paddle?
  4. 04Which tools can run a Paddle affiliate program?
  5. 05What does TrackRev do for a Paddle program?

Explore with AI

Opens this article inside the chosen assistant with a ready-made prompt.

To set up an affiliate program with Paddle, store the partner's ID at the click, pass the ID into Paddle Checkout as custom data, and write a commission when a signed transaction.completed webhook arrives.

Where Stripe Checkout takes a client_reference_id, Paddle Checkout takes customData. Paddle is also the merchant of record, so its totals include tax and a refund never edits the original transaction.

The build has 8 steps, and steps 1 to 7 run in a Paddle sandbox.

According to Paddle's API example, a 20% commission on the $599.00 subtotal is $119.80, against $130.43 on the $652.15 total, so the base you choose changes every payout.

First pick Paddle Billing, second save the ID at the click, third commission on the subtotal, and finally reverse refunds.

Key takeaways

  • Commission on transaction.completed, and on the pre-tax subtotal: in Paddle's own API example, 20% of the $599.00 subtotal is $119.80, against $130.43 on the $652.15 total.
  • Refunds arrive as adjustments, and Paddle Billing can approve live refunds of 400 USD or less automatically, so reverse commissions on adjustment events.
  • Use Paddle Billing, which accounts opened since August 8, 2023 get. Rewardful's own page says it supports Paddle Classic only.

How does Paddle affiliate tracking work?

Paddle affiliate tracking is a chain of 6 stages that carries one partner ID from a click to a refund. Paddle Billing opens checkout from a page on your approved domain that loads Paddle.js.

Your script there can read the first-party cookie, and the Paddle overlay or inline form never sees the cookie, so the partner ID goes into customData in Paddle.Checkout.open().

Paddle Billing then copies the ID to the subscription and every renewal, so one ID covers 12 renewals a year on a monthly plan. Paddle's fee is 5% + 50¢ per checkout transaction.

StageWhat happensPaddle field or event
1. ClickYour script stores the partner's ID in a cookieNone
2. CheckoutYour page opens Paddle Checkout with the ID attachedcustomData
3. PaymentPaddle charges the buyer and creates the subscriptiontransaction.paid, then transaction.completed
4. CommissionYour server verifies the webhook and writes a commissionPaddle-Signature, custom_data
5. RenewalPaddle copies the custom data onto each renewaltransaction.completed again
6. RefundPaddle records an adjustment and leaves the transaction aloneadjustment.created, adjustment.updated

How to set up an affiliate program with Paddle, step by step

Do steps 1 to 7 in a Paddle sandbox, which has its own data and charges no real cards, and step 8 on your live account.

Step 1: Which Paddle version do you have, and how do you open a sandbox?

Per Paddle's migration guide, accounts opened before August 8, 2023 start on Paddle Classic and later ones on Paddle Billing, with separate data, APIs and webhooks. This post covers Billing.

Classic passes data in a passthrough string of up to 1,000 characters (checkout parameters) and added structured custom data in August 2022.

A sandbox is a separate Paddle account with its own data that charges 0 real cards. Classic data lives in a passthrough string of up to 1,000 characters, while Billing data lives in customData.

Open a Paddle Billing sandbox at sandbox-vendors.paddle.com, where API keys contain _sdbx and client-side tokens start with test_.

Step 2: Which commission rules should you set?

Commission rules are the 5 settings that decide every payout: rate and term, commission base, attribution window, hold period and payout schedule. Set all 5 before writing code, because each one changes what the webhook handler must store.

The table gives 1 example per rule, from 25% for 6 months to a $100 payout minimum.

RuleExample settingPaddle detail
Rate and term25% for 6 monthsEach renewal is its own transaction.completed (how to pick a rate)
Commission baseSubtotal minus discountTotals include tax (step 6)
Attribution window30 to 90 daysSafari clears script cookies after 7 idle days (step 3)
Hold period30 days, your refund windowA refund can be approved after Paddle's review
PayoutMonthly, $100 minimumPaddle pays you, so paying partners is a separate run

For example, on a $29 monthly plan, 25% recurring for 6 months pays $7.25 per renewal and $43.50 per customer who stays the whole term (29 x 0.25 x 6). A customer who cancels after 2 payments costs $14.50.

Step 3: How do you save the partner ID at the click?

The saved partner ID is a first-party cookie that a script writes when a visitor arrives through an affiliate link, ready for step 4.

According to WebKit, Safari's Intelligent Tracking Prevention deletes cookies created in JavaScript after 7 days without interaction, so a Monday click and a purchase 10 days later, with no visit in between, reach checkout with no ID.

Keep a second match key, such as an email captured at signup or a coupon code (step 6).

For example, a visitor who arrives on day 1 and pays on day 10 loses the cookie after day 7, so a 30-day attribution window needs the second key to cover days 8 to 30.

Step 4: How do you pass the partner ID into Paddle Checkout?

Passing the ID means attaching 1 cookie value to the Paddle.Checkout.open() call as customData. Paddle Billing's custom data guide asks for a JSON object with at least one key and advises against nesting.

In practice, the code below passes null when no cookie exists, so organic sales carry no partner.

Paddle.js (Paddle Billing)
// "ref" is the first-party cookie your affiliate tracking wrote at the clickconst partner = document.cookie.match(/(?:^|; )ref=([^;]+)/)?.[1] ?? null; Paddle.Checkout.open({  items: [{ priceId: "pri_01gs59hve0hrz6nyybj56z04eq", quantity: 1 }],  customData: { partner_id: partner },});

A server-created transaction takes the same object as custom_data in POST /transactions, before billing. Paddle Billing copies a transaction's custom data to its subscription, and a subscription's to every later transaction, so one ID covers every renewal.

The Paddle checkout attribution guide goes deeper.

Step 5: How do you receive transaction.completed webhooks?

A notification destination is the endpoint that receives Paddle events. In the Paddle dashboard, open Events, then Notifications, and subscribe a webhook destination to transaction.completed, adjustment.created and adjustment.updated.

Commission on completed: a paid transaction may still lack payout totals, a subscription ID and an invoice number.

Per Paddle's docs, Paddle signs each delivery in the Paddle-Signature header, and the table lists 9 rules, including 200 within 5 seconds and up to 60 live retries over 3 days.

Paddle's SDKs reject a timestamp older than 5 seconds by default, and the sample route below widens the check to 300 seconds to tolerate clock skew.

Deduplicate on event_id, which starts with evt_, and compare occurred_at, because ordering is not guaranteed across 60 retries.

Webhook rulePaddle's value
SignatureThe Paddle-Signature header holds ts and h1, an HMAC SHA-256 of ts, a colon and the raw body
Replay checkPaddle's SDKs reject a ts more than 5 seconds old by default
Response deadline200 within 5 seconds, then process from a queue
Live retriesUp to 60 over 3 days, 20 of them in the first hour and 47 in the first day
Sandbox retries3 over 15 minutes
Allowlist6 live and 6 sandbox source IP addresses, listed in Paddle's delivery docs
Active destinations10 at once, each with its own pdl_ntfset_ secret
Deduplicationevent_id, prefixed evt_
OrderingNot guaranteed, so compare occurred_at

From Paddle's signature verification, delivery and notification destination docs.

Webhook endpoint (Next.js route handler)
import { createHmac, timingSafeEqual } from "node:crypto"; export async function POST(req: Request) {  const raw = await req.text(); // the raw body, exactly as Paddle sent it  const header = req.headers.get("paddle-signature") ?? "";  const ts = /ts=(\d+)/.exec(header)?.[1];  const sigs = [...header.matchAll(/h1=([0-9a-f]+)/g)].map((m) => m[1]);  if (!ts || sigs.length === 0) return new Response("bad request", { status: 400 });   const expected = createHmac("sha256", process.env.PADDLE_WEBHOOK_SECRET!)    .update(ts + ":" + raw)    .digest("hex");  const valid = sigs.some(    (s) => s.length === expected.length && timingSafeEqual(Buffer.from(s), Buffer.from(expected)),  );  if (!valid) return new Response("invalid signature", { status: 401 });  // 300 seconds is wider than the SDK default of 5, to tolerate clock skew  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return new Response("stale", { status: 400 });   const event = JSON.parse(raw);  if (await alreadySeen(event.event_id)) return new Response("ok"); // your dedupe store  await enqueue(event); // your queue; commission logic runs after the 200  return new Response("ok");}

Step 6: How do you calculate and record the commission?

In the verified event from step 5, read data.custom_data for the partner, data.subscription_id for the subscription and data.details.totals for the money.

Paddle Billing sends amounts as strings in the currency's smallest unit, so the "59900" subtotal in its API reference example is $599.00. Store currency_code on every commission row, and divide by 100 for USD.

That example has $53.15 of tax at 8.875%, a $652.15 total, a $33.11 fee and $565.89 of earnings.

BasePaddle fieldAmount20% commission
What the buyer paiddetails.totals.total$652.15$130.43
Price before taxdetails.totals.subtotal$599.00$119.80
Price before tax and feedetails.totals.earnings$565.89$113.18

Amounts from the example transaction in Paddle's API reference. The 20% rate is only for the arithmetic.

Which amount should the commission use?

In that example the $33.11 fee is 5% of the $652.15 total plus 50¢, so Paddle charged it on the tax-inclusive amount.

The earnings field is described as the total minus the fee, yet the example shows the subtotal minus the fee ($599.00 minus $33.11), so check a sandbox payload in step 8 before relying on it.

Use the subtotal minus any discount, the base from step 2, which partners can verify against your price list.

On a $29 plan priced before 20% VAT the total is $34.80, so 25% of the total pays $8.70 against $7.25, which is $1.45 too much on every renewal.

Each renewal from step 5 is its own transaction.completed with the same custom data, so write one commission per transaction up to your term.

To credit partners who send no clicks, give each a Paddle discount code and match discount_id; a discount covers only the first transaction unless it is recurring.

Step 7: How do you reverse commissions on refunds and chargebacks?

Paddle Billing's adjustments guide says billed and completed transactions can't change, so a refund is an adjustment and the transaction stays completed, which a tool reading only transaction status misses.

Most live refunds start as pending_approval and become approved or rejected; Paddle approves a live refund itself at 400 USD or less, if the account is verified, the amount is under your balance and the buyer didn't pay by bank transfer.

Reverse the step 6 commission once an adjustment is approved. A partial refund takes back the same share: $10 refunded on a $40 sale at 20% returns $2 of the $8 commission.

Chargebacks arrive as adjustments with the actions chargeback_warning, chargeback and chargeback_reverse; reverse on the first two and restore on the third. The refund clawback guide covers commissions already paid.

Step 8: How do you test in the sandbox and go live?

A sandbox test is a 3-part pass of the flow: 1 purchase, 1 renewal and 1 refund. Paddle Billing's webhook simulator can replay a renewal, but only to destinations whose usage type is Platform and simulation or Simulation.

Buy through a partner link, simulate a renewal, refund the payment (the sandbox approves refunds every 10 minutes, so wait 10 minutes before checking the reversal) and check the commissions from steps 6 and 7: expect 1 commission written per transaction and 1 reversal after the refund is approved.

To go live, swap in live credentials and recreate the catalog and notification destination, as the go-live checklist from Paddle lists.

How do you set up a referral program on Paddle?

A referral program is a program that rewards customers for bringing in new ones, and steps 3 to 8 carry over: the referrer's ID travels in custom data and the reward fires on the friend's first transaction.completed.

Paddle Billing's credits aren't promotional credits, so pay cash or put a Paddle discount on the referrer's subscription, which can recur for up to 999 billing periods.

A discount's usage limit is one total across all customers, so a one-use-per-friend rule is yours to write. TrackRev's referral campaigns add cash or credit rewards on paid plans.

For example, a 25% reward on a friend's first $29 transaction is $7.25.

Which tools can run a Paddle affiliate program?

Five options can run a Paddle Billing affiliate program: TrackRev, Rewardful, Tolt, Affonso or a build of your own. Prices are in the comparison of affiliate software for Paddle.

Ask all 5 vendors which total each commissions on and whether each reads adjustment events, because a tool that reads only transaction status misses refunds.

Rewardful's own page says it supports Paddle Classic only, which rules it out for accounts opened since August 8, 2023.

OptionWhat its page says about Paddle
TrackRevPaddle Billing API key, hourly sync and an optional instant webhook; no Paddle Classic
Build it yourselfSteps 3 to 7, plus a partner portal, payout run and tax forms
RewardfulIntegrates with Paddle Classic only, and not with Paddle Billing
ToltTwo-way sync, with commission deducted on issued refunds; no version named
AffonsoAdded in 2025, covering refunds, discount codes and referral links; no version named

Paddle support as each vendor describes it, October 2026.

What does TrackRev do for a Paddle program?

TrackRev is SaaS affiliate software for indie hackers and small SaaS teams, with link tracking and revenue attribution built in. We built TrackRev to read Paddle Billing sales with no limit on tracked revenue, from $29 a month.

In our Paddle integration, the sync runs hourly with 30 days back on the first run, and an optional webhook makes new sales instant.

The first sync pulls 30 days of sales, so a program started in November 2026 sees October sales on day 1.

SettingValue
PlansIndie $29 a month, or $348 over 12 months (1 workspace, 1 tracked domain, solo) and Growth $299 a year (up to 10 workspaces and domains, unlimited team members); no cap on commission tracked on either; the free plan has 50 links and 1,000 events a month, for link tracking only
ConnectionRead-only Paddle Billing key with Customer, Product, Subscription, Transaction and Discount access
SyncHourly, 30 days back on the first run, instant with an optional webhook on transaction.completed
Join keycustomData: { vid: window.trk.vid } in the step 4 call, falling back to the buyer's email
Renewals and codesRenewals inherit the first visitor; a Paddle discount code assigned to a partner credits them without a click
Cookie window60 days by default, 1 to 3,650 allowed
Hold period0 to 180 days, default 0
PayoutsPayPal or Wise CSV export, then mark each paid

In our Paddle integration, we verify the webhook signature, then read the transaction from the Paddle API. Choose another route on Paddle Classic, or for a managed marketplace of partners, which PartnerStack vs TrackRev compares.

Our own pricing page lists the plans.

Found this useful? Share it.

PostLinkedIn

Frequently asked questions

Muzahid Maruf — Founder of TrackRev.io

Written by

Muzahid Maruf

Founder, TrackRev.io & Contant.io

Muzahid Maruf founded TrackRev.io, SaaS affiliate software with no limit on tracked revenue, and Contant.io. He writes about affiliate programs.

Writes about Marketing attribution · Link tracking · Revenue analytics · SaaS growth

Run your affiliate program without a revenue cap.

Affiliate software for indie hackers and small SaaS teams: $29 a month flat, 0% fees, link tracking and revenue attribution built in. Free to start, no card.