FirstPromoter allows you to automatically track sales, refunds, upgrades and cancellations from Paddle. With the introduction of Paddle Billing, there have been some few changes to the setup requirements.
*If you're using the classic Paddle integration, please check this article:
https://help.firstpromoter.com/en/articles/5898601-how-to-integrate-paddle-classic
To integrate Paddle with FirstPromoter, you need to follow the below steps:
Getting Started > Quick Setup > Choose Paddle and follow the steps from the Integration Wizard.
1) Set up Paddle Notifications
Our ability to track sales from paddle mainly depends on the notifications (webhooks) and events we receive from Paddle for your account. This is very crucial and without this step the tracking of sales will not be possible.
To set the Notification, you will have to log in to Paddle > Developer tools in sidebar > Notifications > select New destination
In the popup that comes up, set your description and add in the URL provided from FirstPromoter.
Your final setup should look like this:
2) Set up the Notification Events
On that same section, make sure you enable the following events
transaction.completed, transaction.cancelled, subscription.cancelled, subscription.created and adjustment.updated
After setting up the Events, Save the notification.
3) Add Secret Key
Once saved, click on the 3 menu dots on your newly created notification and select Edit destination
Copy the secret key provided and update the Secret key field in FirstPromoter.
You can then proceed to confirm the webhook connection to save.
4) 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(eventData.name === "checkout.completed"){
var email = eventData.data.customer.email;
var uid = eventData.data.customer.id;
fpr("referral",{email,uid})
}
The final Paddle Setup will look something like this:
Paddle.Setup({
seller: XXXXXX,
eventCallback: function(eventData) {
//...
if(eventData.name === "checkout.completed"){
var email = eventData.data.customer.email;
var uid = eventData.data.customer.id;
fpr("referral",{email,uid});
}
}
});
Optionally, if you prefer to use only the user id (uid)from your database instead.
You will need to pass that as customData as "fp_uid".
Paddle.Setup({
seller: XXXXXX,
customData: {
"fp_uid": "put actual user Id here",
},
eventCallback: function(eventData) {
//...
if(eventData.name === "checkout.completed"){
var uid = "put actual user id here";
fpr("referral",{email,uid});
}
}
});
You can also pass the FirstPromoter tid in the custom data as well ( for this we will grab all the details from Paddle and find the corresponding promoter with the tid . Since Paddle does not send the customer data in the notification, you can also pass this here as "email".
function getFPTid() {
return window.FPROM && window.FPROM.data.tid;
}
Paddle.Setup({
seller: XXXXXX,
customData: {
"fp_tid": getFPTid(),
"email":"user email goes here"
}
});
Option 2) Tracking without Paddle.js
If you are not using Paddle.js and have Paddle setup on the backend of your application for instance, you can choose to:
1) Send us the Email & UID (user id from your database/ Paddle's customer id)
2) Set the custom data for paddle and add
"fp_uid" which will be your user id from your database,
"email" which is the email of the lead
in conjunction with the "fp_tid" which is obtained from the _fprom_tid cookie or "fp_ref" which can be obtained from the "_fprom_ref" cookie