Run a Paddle affiliate program on Paddle Billing

How Paddle affiliate tracking works with custom data

Paddle.js accepts a customData object when it opens checkout. op.js gives you the visitor's click id and you pass it as op_click. Paddle stores it on the transaction and copies it to the subscription and every renewal transaction created from it.

Paddle describes that copying in its custom data guide. Keep op_click at the top level of the object.

Paddle.Checkout.open({
  items: [{ priceId: "pri_123", quantity: 1 }],
  customData: { op_click: window.openpromoter.clickId },
});

Set up a Paddle affiliate program in four steps

A Paddle affiliate program needs one notification destination and one line in your checkout code. You add the destination in Paddle, choose seven events and paste its secret key into OpenPromoter. Then you pass the click id as custom data when checkout opens.

• 1

  Add a destination

  In Paddle, open Notifications and add a destination for /api/webhooks/paddle/<workspaceId>.

• 2

  Choose seven events

  Select every event in the table below and save the destination.

• 3

  Paste the secret key

  Copy the destination's secret key into Settings > Integrations.

• 4

  Pass the click id

  Send op_click from window.openpromoter.clickId in customData.

OpenPromoter checks the Paddle-Signature header on every request. It rebuilds the HMAC from the timestamp and the raw body and rejects anything older than five minutes. Paddle explains the format in its signature verification guide.

The billing providers docs list the URL and events with copy-ready values.

Paddle webhook events and what each one does

OpenPromoter reads seven Paddle Billing events. One links the customer, one books the commission, two handle refunds and chargebacks and three follow the subscription. Each event is verified against its signature and processed only once even when Paddle delivers it twice.

Paddle sends transaction.completed for the first payment and for every renewal. Each one books its own commission while it falls inside the commission duration.

How Paddle refunds and chargebacks change commissions

Paddle records refunds and chargebacks as adjustments. OpenPromoter applies a refund only after Paddle approves it and then reduces or reverses the commission. A chargeback adjustment reverses the commission and claws it back from the next payout if you already paid it.

Test with the Paddle sandbox

The Paddle sandbox is a separate account with its own API keys, notification destinations and test cards. Turn on Sandbox when you connect it under Settings > Integrations. OpenPromoter then tags its sales and commissions as Test and keeps them out of real payouts.

Sign up at sandbox-vendors.paddle.com and use the card 4242 4242 4242 4242 with any future expiry. Source: Paddle sandbox docs (November 2026).

When the test passes, click Delete test data. Then connect your live Paddle account with Sandbox off.

Common Paddle affiliate setup mistakes

Most Paddle setup problems come from a click id missing from checkout or a destination that misses events. A secret key from the sandbox in a live connection is the other common cause. Each mistake below comes with the fix.

• Paddle Classic alerts

  The handler reads Paddle Billing only. Report Classic sales through the REST API.

• Click id read too early

  Read window.openpromoter.clickId when checkout opens. op.js loads async and sets it after load.

• A sandbox key in live

  Sandbox and live destinations have different secret keys. Paste the one for the account you connect.

• Missing adjustment events

  Subscribe to both adjustment events. Without them refunds never reach OpenPromoter.

• Nested custom data

  Keep op_click at the top level of customData. A nested value is not read.

• A short hold period

  Set the hold period to at least your refund window. The default is 30 days.

Pay Paddle affiliates and handle tax

Paddle pays you and OpenPromoter pays your partners. Partners choose Stripe Connect, PayPal, Wise or manual payment in their portal and you approve each batch. Each rail charges its own fee and OpenPromoter takes 0% of payouts on every plan.

Stripe Connect needs a Stripe account of your own as the platform. PayPal and Wise payouts need no Stripe account. The payouts page compares the rails.

Partners paid by PayPal, Wise or by hand submit a W-9 or a W-8BEN in the portal. EU VAT ids are checked against the VIES service. Every payout gets a self-billed invoice with a sequential number.

US partners need a W-9 before their payouts for the year pass the 1099-NEC threshold. That threshold is $2,000 for payments made in 2026. The 1099 guide for affiliates covers the filing.

Questions