Skip to main content
The Paddle Cometly integration sends transactions, new customers and new subscriptions from your Paddle account to Cometly as events (tracked actions such as a purchase or a new subscription). To set it up, you create an API key in Paddle, save it in Cometly, then create an event that uses a Paddle trigger. If you use an embedded Paddle checkout, also follow Track embedded Paddle checkouts. With your Paddle sales in Cometly, you can attribute them back to your ads and marketing channels. You see which ad or channel produced each sale, with the amount recorded on the event.

Before you start

Create an API key in Paddle

  1. Log in to Paddle. In the left side menu, go to Developer Tools > Authentication.
    Paddle side menu with Developer Tools expanded and Authentication highlighted
  2. On the Authentication page, click + New API key.
    Paddle Authentication page with an arrow pointing to the New API key button
  3. In the New API key window, fill out these fields:
    • Name: any name you like. We recommend “Cometly Integration” so the key is easy to find if you have several API keys.
    • Expires at: choose Never expires.
    Paddle New API key window with the Never expires checkbox ticked under Expires at
  4. Set these permissions:
    • Customers: Read
    • Notification settings: Read, Write
    • Notifications: Read, Write
    • Subscriptions: Read
    • Transactions: Read
  5. Click Save.
  6. In the “Copy your API key” window, click Copy key.
    Paddle Copy your API key window with an arrow pointing to the Copy key button

Connect Paddle to Cometly

  1. Log in to Cometly and click Integrations in the sidebar. On the Apps & Integrations page, type “Paddle” in the search box, then click Connect on the Paddle card.
    Cometly Apps and Integrations page with numbered callouts on Integrations in the sidebar, the search box with paddle typed in, and the Connect button on the Paddle card
  2. On the Paddle page, enter an Account name (a label that helps you recognize this Paddle account in Cometly), paste the key you copied from Paddle into API Key, then click Save.
    Cometly Paddle integration page with Cometly Demo entered as the Account name, a masked API Key and an arrow pointing to the Save button
The connection now appears under My Connections. You can use it right away. To let teammates in a space use it too, click the connection to expand it, then click Share Access next to that space.

Create an event

  1. Click Events Manager in the sidebar, then click Create Event.
    Cometly Events Manager on the Events tab with numbered arrows pointing to Events Manager in the sidebar and the Create Event button
  2. Under App / Integration, search for Paddle and select it. Under Events, choose the event you want to track. Then click Create.
    Cometly Create Event dialog with numbered arrows on Paddle under App / Integration, Purchase under Events, and the Create button
  3. Find the event you just created in the Events Manager table and click Configure.
    Events Manager table with a draft Purchase event for Paddle in the last row and an arrow pointing to its Configure button
  4. Under Account, select the Paddle account you connected. (You can also add one here with + Connect new Paddle account.)
  5. Under Trigger, choose what should send the event:
    Once selected, the Account and Trigger cannot be modified. To change either one, create a new event.
  6. Click Continue.

Map your data

  1. Click Check for Data, then trigger the event from inside your Paddle account. If no data shows up yet, click Save & Return When Data is Ready and come back to map your data once events are sent.
  2. Select a record and click Continue With Selected Record.
  3. Map your Paddle data fields to Cometly fields. This makes sure the event data you send (email addresses, event times and other data) lines up with Cometly’s reporting. Email and Event Time are required:
    • Email: choose the email address field from your selected record (for example, the field that holds email@example.com).
    • Event Time: choose the dynamic option The time we receive the event.
  4. Click Add Field to map more fields, such as:
  5. Click Save & Continue.

Add filters and activate the event

Filters let you control when an event in Paddle should actually create an event in Cometly. This step is optional, but we recommend it if you only want to send the event under certain conditions.
  1. Click Add Filters (the button reads Add Another Filter once you have one).
  2. Select the field you want to filter by.
  3. Choose your condition (for example (text) is, (text) contains or (text) starts with).
  4. Enter the value you want to match.
  5. Click Activate to finish. You can also click Activate without adding any filter.

Track embedded Paddle checkouts

If you use an embedded (iframe) Paddle checkout in your funnel or website, you need a few extra steps for accurate tracking. The steps below show you how to install an additional script on your page so the comet_token (the visitor’s tracking token from the Cometly tracking script) is passed into every Paddle checkout. Once this is in place, the comet_token is included with each checkout event. You can then map it in the mapping step above (Add Field > Comet Token) to complete your setup.

Step 1: Install the Cometly tracking script

Make sure the Cometly tracking script is installed in the <head> of every page of your website. See Install the Cometly pixel.

Step 2: Create a client-side token in Paddle

You need a client-side token from Paddle for the Paddle.Initialize part of the additional script.
  1. In Paddle, go to Developer Tools > Authentication.
  2. On the Authentication page, click Client-side tokens, then click + New Client-side token.
    Paddle Client-side tokens tab with an arrow pointing to the New Client-side token button
  3. Name the token “Cometly Token”, then click Save.
    Paddle New Client-side token window with Cometly Token entered in the Name field
  4. After the token is saved, open the three dots menu on its row and click Copy token.
    Paddle Client-side tokens list with the row menu open showing Copy token, Show and Revoke

Step 3: Add the Paddle script below the Cometly script

Add this script right below the Cometly script in the <head> of your landing page, so it loads before the visitor opens the embedded Paddle checkout. Replace INSERT_TOKEN_HERE with your actual client-side token.
  1. In the Paddle dashboard, go to Checkout > Checkout Settings.
  2. Scroll to the Default Payment Link section.
  3. Enter your website URL in the field.
  4. Click Save in the top right corner of the page.

Step 5: Pass the comet token into the Paddle checkout

For accurate attribution in Cometly, pass the comet_token into every Paddle checkout session. There are two ways to do this, depending on how Paddle is implemented on your site: HTML data attributes or JavaScript properties. For more about the token itself, see Comet token.
If your Paddle checkout buttons are created directly in your HTML, add the comet_token with the data-custom-data attribute.
  1. Locate your Paddle checkout button in the HTML.
  2. Add the following snippet inside the data-custom-data property:
Example:
This includes the visitor’s tracking token from Cometly in the Paddle checkout session.

Step 6: Verify the token is passed

Run a test checkout and confirm that the comet_token value appears in your Paddle event payload (for example, under custom_data). This confirms the token is being passed into the checkout for attribution. In Cometly, the comet_token appears in the payload under the webhook_payload property. You can also check that Paddle received the comet_token from your landing page: in Paddle, click Transactions in the left side menu, then open the transaction.

Check it worked

Go to Events Manager > Events Log to see the events Cometly has received and their status. After your next Paddle transaction, customer or subscription that matches the trigger, it appears there.

Frequently asked questions

Can I track both transactions and subscriptions from Paddle in Cometly?

Yes. Each event uses one trigger, and the trigger cannot be changed after you select it. Create one event for each trigger you want to track, for example one for Transaction Completed and one for Subscription Created, and select the same Paddle account in each.

Do I need to add a webhook in Paddle myself?

No. When you set up the event, Cometly uses your API key to create the notification in your Paddle account for the trigger you chose. This is why the key needs Read, Write access to Notification settings.

Why does Cometly say my Paddle API key is incorrectly formatted?

Cometly checks that the key matches the format of a Paddle API key before it saves it. Paste the full secret key, which starts with pdl_live_apikey_, with nothing cut off. A client-side token (the kind used for embedded checkouts) does not work in the API Key field.

Next steps

Still have questions or need a hand? We’re happy to help. Reach our team at support@cometly.com.