> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cometly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Paddle integration

> Set up the Paddle Cometly integration to send transactions, customers and subscriptions as events, so each sale is tied to the ad behind it.

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](#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

* Install the Cometly pixel (the tracking script that records visits to your site). See [Install the Cometly pixel](https://docs.cometly.com/getting-started/install-pixel.md).

## 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](https://mintcdn.com/cometly/alvP4_0ekdK-CBm_/images/integrations/platforms/paddle/01.webp?fit=max\&auto=format\&n=alvP4_0ekdK-CBm_\&q=85\&s=cec778b4a96ecf9debfc55adfa8b2b95)

2. On the Authentication page, click **+ New API key**.

   ![Paddle Authentication page with an arrow pointing to the New API key button](https://mintcdn.com/cometly/alvP4_0ekdK-CBm_/images/integrations/platforms/paddle/02.webp?fit=max\&auto=format\&n=alvP4_0ekdK-CBm_\&q=85\&s=3af4aa9c9496afe5160fb4b62b60bf13)

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](https://mintcdn.com/cometly/alvP4_0ekdK-CBm_/images/integrations/platforms/paddle/03.webp?fit=max\&auto=format\&n=alvP4_0ekdK-CBm_\&q=85\&s=4867c59e003591aef6de97791eed6868)

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](https://mintcdn.com/cometly/alvP4_0ekdK-CBm_/images/integrations/platforms/paddle/04.webp?fit=max\&auto=format\&n=alvP4_0ekdK-CBm_\&q=85\&s=f9b059e6cd3683419014e8db63c14b11)

## 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](https://mintcdn.com/cometly/alvP4_0ekdK-CBm_/images/integrations/platforms/paddle/05.webp?fit=max\&auto=format\&n=alvP4_0ekdK-CBm_\&q=85\&s=cca1a12ce6604d71c47ebc84c25c104f)

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](https://mintcdn.com/cometly/alvP4_0ekdK-CBm_/images/integrations/platforms/paddle/06.webp?fit=max\&auto=format\&n=alvP4_0ekdK-CBm_\&q=85\&s=ccd9da58d718d58d16047d6484f5eb69)

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](https://mintcdn.com/cometly/alvP4_0ekdK-CBm_/images/integrations/platforms/paddle/07.webp?fit=max\&auto=format\&n=alvP4_0ekdK-CBm_\&q=85\&s=1a93529692506e4454b8eef717d92f76)

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](https://mintcdn.com/cometly/alvP4_0ekdK-CBm_/images/integrations/platforms/paddle/08.webp?fit=max\&auto=format\&n=alvP4_0ekdK-CBm_\&q=85\&s=8335847722f2496fb86278a2acf27011)

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](https://mintcdn.com/cometly/alvP4_0ekdK-CBm_/images/integrations/platforms/paddle/09.webp?fit=max\&auto=format\&n=alvP4_0ekdK-CBm_\&q=85\&s=c0a111c5f1bd41ab7c13eff644dbcd36)

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:

   | Trigger | When it fires |
   | - | - |
   | **Transaction Completed** | A transaction is completed in your Paddle account. |
   | **Customer Created** | A customer is created in your Paddle account. |
   | **Subscription Created** | A subscription is created in your Paddle account. |

   > [!NOTE]
   >
   > 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:

   * First Name
   * Last Name
   * Phone
   * Amount
   * Comet Token (`comet_token`), if you use an embedded (iframe) Paddle checkout, covered in [Track embedded Paddle checkouts](#track-embedded-paddle-checkouts)

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](https://docs.cometly.com/getting-started/install-pixel.md).

### 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](https://mintcdn.com/cometly/alvP4_0ekdK-CBm_/images/integrations/platforms/paddle/13.webp?fit=max\&auto=format\&n=alvP4_0ekdK-CBm_\&q=85\&s=65e7c7b2ca6c0c93b118cdd0273ccaa8)

3. Name the token "Cometly Token", then click **Save**.

   ![Paddle New Client-side token window with Cometly Token entered in the Name field](https://mintcdn.com/cometly/alvP4_0ekdK-CBm_/images/integrations/platforms/paddle/14.webp?fit=max\&auto=format\&n=alvP4_0ekdK-CBm_\&q=85\&s=3c136db6b3b72f293480398f975ced9c)

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](https://mintcdn.com/cometly/alvP4_0ekdK-CBm_/images/integrations/platforms/paddle/15.webp?fit=max\&auto=format\&n=alvP4_0ekdK-CBm_\&q=85\&s=62ac42bf378aa13476ab4ef8a80a4a53)

### 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.

```html theme={null}
<script src="https://cdn.paddle.com/paddle/v2/paddle.js"></script>
<script>
Paddle.Initialize({ token: 'INSERT_TOKEN_HERE' });
</script>
```

### Step 4: Assign a default payment link

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](https://docs.cometly.com/concepts/comet-token.md).

> [tab] HTML data attributes
>
> 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:
>
> ```text theme={null}
> "comet_token": cometToken()
> ```
>
> Example:
>
> ```html theme={null}
> <a
>   href="#"
>   class="paddle_button"
>   data-theme="light"
>   data-custom-data='{
>     "comet_token": cometToken()
>   }'
>   data-customer-address-country-code="US"
>   data-customer-email="weloveyourproduct@paddle.com"
>   data-items='[
>     {
>       "priceId": "pri_01k8prs4006dyks6c1xe1x3rge",
>       "quantity": 1
>     }
>   ]'
> >
>   Buy Now
> </a>
> ```
>
> This includes the visitor's tracking token from Cometly in the Paddle checkout session.

> [tab] JavaScript properties
>
> If your Paddle checkout is initialized with JavaScript (for example, with `Paddle.Checkout.open()`), add the `comet_token` with the `customData` property.
>
> 1. Locate the section of your code that calls the Paddle checkout.
> 2. Add the `comet_token` inside the `customData` object.
>
> Example:
>
> ```javascript theme={null}
> Paddle.Checkout.open({
>   settings: {
>     theme: "light",
>   },
>   items: [
>     {
>       priceId: "pri_01k8prs4006dyks6c1xe1x3rge",
>       quantity: 1,
>     },
>   ],
>   customData: {
>     "comet_token": cometToken(),
>   },
>   customer: {
>     email: "weloveyourproduct@paddle.com",
>     address: {
>       countryCode: "US",
>     },
>   },
> });
> ```

### 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

* [Send these conversions back to your ad platforms with the Conversion API](https://docs.cometly.com/guides/conversion-api/overview.md)
* [Use the Events Log to check what Cometly received](https://docs.cometly.com/support/troubleshooting/general/event-log.md)
* [Understand how events work in Cometly](https://docs.cometly.com/guides/events/how-events-work.md)
* [Learn what the comet token is and how it ties a sale to a visitor](https://docs.cometly.com/concepts/comet-token.md)

Still have questions or need a hand? We're happy to help. Reach our team at [support@cometly.com](mailto:support@cometly.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.