FirstPromoter allows you to automatically track sales, refunds, upgrades and cancellations from Paddle.
*If you're using the new Paddle Billing, please check this article:
https://help.firstpromoter.com/en/articles/8523227-how-to-integrate-paddle-billing
To integrate Paddle with FirstPromoter, you need to follow the next steps:
Getting Started > Quick Setup > Choose Paddle and follow the steps from the Integration Wizard.
1. Set up Paddle's webhooks and public key
To set the Webhooks, you will have to login Paddle > Developer tools din sidebar > Events > click on "+ Add new endpoint" and to add in the new field named Webhook Endpoint URL from FirstPromoter.
The events required by FirstPromoter are payment_succeeded, payment_refunded, subscription_payment_succeeded, subscription_payment_refunded and subscription_cancelled so please make sure these webhook events are enabled.
To get the public key from Paddle, go to Developer tools on the sidebar > Public key
Make sure you enter the public key from Paddle in the integration form and confirm the webhook connection.
**** PLEASE DO NOT REMOVE ANYTHING from the public key, just copy paste it entirely as it shows on Paddle, including -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----, otherwise you'll get a 500 error.
2. Link FirstPromoter referral with Paddle customer
a) after confirming the webhook connection you'll be redirected to Step 3 of the wizard
b) on Step 3 select Custom / Others option > JS
c) follow the instructions on Step 4 and add the main script globally including on the page where you have Paddle.js inserted (if you use that)
d) on Step 5 you'll see instructions on how to pass referral data to FirstPromoter
There are 2 options for that:
Option 1) tracking using Paddle.js
This is the easiest option to track customers on checkout using Paddle.js. You'll have to add the following code to Paddle.Setup's eventCallback method:
if (data.event === 'Checkout.Complete') {
window.fpr('referral',{email: data.eventData.user.email,uid: data.eventData.user.id})
}
Paddle.Setup will look something like this:
Paddle.Setup({
vendor: xxxxxx,
eventCallback: function(data) {
//...
if (data.event === 'Checkout.Complete') {
window.fpr('referral',{email: data.eventData.user.email,uid: data.eventData.user.id})
}
}
});
Options 2) tracking without Paddle.js
This option is for those that want to track trials before Paddle.js callbacks are fired or if they use only Paddle's backend API.
Before adding the referral tracking script (on Step 5) you should decide first what identifier FirstPromoter will use to match the referral with Paddle customer.
There are two identifiers you can use, choose one:
Email
Referral "email" matches Paddle customer email. This is the easiest approach if the user email will be the same as Paddle's customer email, at least until the first sale. After the first sale, we automatically fill the referral "uid" as Paddle user id so email won't be used anymore for further matching.
Passthrough as uid
The value you're using as passthrough in your Paddle checkout should be passed on the referral tracking function or API as "uid". Usually it's the user or account id in your DB.
Passthrough will appear on webhooks coming from Paddle and we'll be able to find the referral inside FirstPromoter based on that.
If your Paddle passsthrough is a JSON, you can pass the "uid" value used in the referral script as a "fp_uid" field of the passthrough JSON.