Skip to main content
All CollectionsIntegrations
How to integrate Paddle (Billing)
How to integrate Paddle (Billing)

Paddle integration with FirstPromoter

Harvey Gil avatar
Written by Harvey Gil
Updated over a week ago

Automating the tracking of sales, refunds, upgrades, and cancellations from Paddle is simple with FirstPromoter.

Follow these steps to seamlessly integrate Paddle with FirstPromoter:

1. Accessing Paddle Integration

  • Navigate to your profile located in the upper-right section and select "Settings."

  • Access the "Integrations" tab.

  • Scroll down to the "Integrations with third-parties" section.

  • Select "Setup" under Paddle.

2. Setting 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.

  • Log in to your Paddle account.

  • Navigate to Developer tools in the sidebar > Notifications > select New destination.

  • Set a description and add the URL provided by FirstPromoter.

  • Ensure the following events are enabled: transaction.completed, transaction.cancelled, subscription.cancelled, subscription.created, and adjustment.updated.

  • Save the notification.

3. Adding Secret Key

  • Click the three menu dots on your newly created notification and select Edit destination.

  • Copy the secret key provided and update the Secret Key field in FirstPromoter.

4. Confirming Webhook Connection

  • Proceed to confirm the webhook connection in FirstPromoter to save the settings.

5. Linking FirstPromoter Referral with Paddle Customer

  • After confirming the webhook connection, you'll be redirected to Step 3 of the wizard.

  • Select Custom / Others option > JS.

  • Follow the instructions on Step 4 to add the main script globally, including on the page with Paddle.js inserted (if applicable).

  • Step 5 will provide instructions on passing referral data to FirstPromoter. There are two options for this:

Option 1) Tracking using Paddle.js

  • Add the provided 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 should look 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, pass it as customData with "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 not using Paddle.js and managing Paddle setup on the backend, choose to:

    • Send the Email & UID (user id from your database/Paddle's customer id).

    • Set the custom data for Paddle and add "fp_uid" (user id from your database), "email" (email of the lead), "fp_tid" (obtained from the _fprom_tid cookie), or "fp_ref" (obtained from the "_fprom_ref" cookie).

Did this answer your question?