Connecting Paddle
Attribute sales from your Paddle checkout: the API key, the notification destination, the field that carries the click id, and what to check when a sale does not appear.
If Paddle bills your customers, connect it here and your sales, renewals and refunds flow into AffiliateRail exactly as a Stripe merchant's do. Click to sale to commission to payout, with the same ledger, the same flows and the same payouts underneath.
You need two things from Paddle: an API key and a notification destination with its signing secret. Paddle has no one-click authorisation like Stripe's, so this is a form rather than a round trip, and it takes about five minutes.
Before you start
Decide whether you are connecting sandbox or live. Paddle keeps them completely separate, on different sign-in pages and different API hosts, and a key from one never works against the other. Rehearsing in sandbox first is worth the extra ten minutes: you can put a full transaction through with a test card and watch the commission appear before any real money is involved.
Get your webhook URL
Open Settings, Integrations in AffiliateRail. The Paddle card shows a URL ending in your program id. Copy it exactly.
That URL is unique to your program, and it has to be, because a Paddle notification carries no field naming the seller who sent it. The URL is the only thing that says a sale is yours. It is not a secret (your program id is already in your tracking script), and it is not what makes the connection safe: every notification is signed, and we check the signature against your own secret before we act on anything.
Create the API key
In Paddle, go to Developer tools, then Authentication, and create a key.
It needs read access to notification settings, transactions, subscriptions, customers and adjustments. If Paddle offers a read-only preset, that is the right one. We never write to your Paddle account, the same way we never write to your Stripe.
Paddle shows the key once. Paste it straight into the Paddle card rather than into a note.
The key itself says which environment it belongs to: a live key starts pdl_live_apikey_ and a
sandbox key starts pdl_sdbx_apikey_. If you pick the wrong environment on the card, we refuse the
key and tell you which one it actually is, rather than saving it and failing at your first sale.
Create the notification destination
Still under Developer tools, go to Notifications and create a destination. Choose the webhook type rather than email, and paste the URL you copied above.
Subscribe it to these events:
| Event | Why we need it |
|---|---|
transaction.completed | The sale. Both the first purchase and every renewal |
subscription.created | Binds a customer to a partner even if the transaction is delayed |
subscription.updated, .activated, .past_due, .paused, .resumed, .canceled | Keeps the customer's status honest in your reports |
adjustment.created, adjustment.updated | Refunds and chargebacks, so a commission is voided when money goes back |
Save it, then copy the destination's signing secret. It starts pdl_ntfset_. If Paddle only
shows it once, copy it now; if you lose it, delete the destination and make a new one, then paste
the new secret over the old one here. Nothing else breaks.
Connect
Back on the Paddle card, choose the environment, paste the API key and the signing secret, and save.
We call Paddle with the key straight away, before we call anything connected. Three things can come back:
- Connected, with a destination pointing here. Everything is in place.
- Connected, with no destination pointing here. Your key works and your webhook does not. Go back and check the URL character for character; nothing will reach us until it matches.
- Refused, with a reason. Either Paddle rejected the key, or the key belongs to the other environment. Both are a one-minute fix.
The field that carries the click id
Attribution rides on one field: custom_data.rail_referral on the transaction.
Our tracking script fills it for you when your checkout opens through Paddle.js, the same way it
stamps a Stripe checkout. If you create transactions server-side instead, set the same key yourself
when you create the transaction, using the click id our script left in the visitor's rail cookie.
Paddle then does something Stripe cannot: it copies custom_data onto the subscription it creates,
and back onto every transaction that subscription creates. So the click id rides every renewal on
its own, and a partner keeps earning on a customer for as long as your commission flow says they
should, without anything on your side remembering anything.
When a sale does not appear
Work down this list. It is ordered by how often each one is the answer.
- Look at the Paddle card. It shows the last event we received and when. If that is blank or days old, the problem is between Paddle and us, not in the ledger.
- Check the delivery in Paddle, under Notifications. Paddle shows what it sent and what we
answered.
- A 400 means the signature did not verify, which almost always means the signing secret here is not the one on that destination. Paste it again.
- A 200 saying this program has no live Paddle connection means the URL is pointing at a program whose connection was disconnected.
- A 200 with anything else means we received it and made a decision, so carry on down.
- Check the customer exists under Customers. If they are there with no partner against them, the sale arrived and carried no click id: the checkout was not stamped. That is what the attribution guide is for, and the attribution report lists every sale in exactly that state so you can attribute it by hand.
- Check your flows. A customer against the right partner and no commission means the sale landed and no flow matched it. Flows covers why that happens.
Disconnecting
Disconnect on the same card. Ingest stops immediately, and every commission already earned stays exactly as it is, along with the sales, the payouts and the balances. Disconnecting only stops us reading new sales.
You can also delete the destination in Paddle, which has the same effect from the other end.
What we hold, and what we cannot do
We hold your API key and your signing secret, encrypted, and nothing else of yours. The key is read-only by request, we never write to your Paddle account, and payouts to your partners run from your own PayPal, Wise or Payoneer account, never through us. Payouts explains that side.