Paddle

What this lets you do

Connect Paddle to Traceten and see which AI sources drive paying customers, not just pageviews. When a transaction completes, Traceten matches it back to the originating session and attributes the revenue to the correct AI source.

Paddle is the only integration that requires you to pass a value through checkout. Paddle is the merchant of record, and its transaction webhooks carry no buyer email, so there is no fallback for Traceten to match on. Read Passing the visitor ID before you connect.

Before you start

A Traceten account with at least one site tracked.
A Paddle Billing account, and permission to create API keys on it.
Your Paddle Seller ID. It is shown in your Paddle account settings.
The Traceten snippet installed and verified on the site your checkout runs from.
Workspace admin in Traceten. Connecting and disconnecting a revenue source affects the whole workspace, so only admins can do it.

Connect Paddle

You connect by pasting an API key and your Seller ID. There is no OAuth redirect, and there is no notification destination to configure: Traceten creates it on your Paddle account for you.

Create an API key in Paddle

Open Paddle → Developer tools → Authentication and create an API key.Give it a name (for example, Traceten) and these permissions:

Permission	Why
`transaction.read`	Reading the revenue Traceten attributes
`notification_setting.write`	Creating the destination Traceten receives on

Copy the key. It starts with pdl_live_.

Find your Seller ID

It is the number shown in your Paddle account settings.Traceten asks for it because Paddle’s API has no endpoint that reports which account a key belongs to. Every other integration reads its own identity from the provider; for Paddle there is nothing to read, so Traceten records the Seller ID you enter and treats it as the identity of this connection. Traceten cannot verify that claim against Paddle. It does not affect the security of your data: every delivery is still checked against this connection’s own signing secret.

Paste both into Traceten

Go to app.traceten.com/dashboard, open Settings → Integrations, and choose the site your checkout runs from at the top of the page.Pick Paddle from the list of payment providers, then paste the API key and the Seller ID.Click Connect.

Confirm the connection

Paddle shows as Connected, with the last four characters of the key.Traceten stores the key encrypted. After this point it is never shown again, in the dashboard or in the API, and only those last four characters are readable back.

What Traceten does with the key

In the same request, Traceten:

Reads one transaction, to prove the key works and can actually see the revenue it is being connected for.
Creates a notification destination on your Paddle account pointed at Traceten, subscribed to three events.
Stores the key and the destination’s signing secret, both encrypted.
Starts importing your last 90 days of completed transactions.

You can see the destination Traceten created under Developer tools → Notifications. Traceten asks Paddle not to include sensitive fields in those notifications, because it needs none of them. These are the three events:

Event	What Traceten does with it
`transaction.completed`	Attributes the transaction. This is the revenue.
`adjustment.created`	Subtracts an approved refund from the source that earned it.
`adjustment.updated`	Catches a refund reaching `approved` after it was created pending.

Subscription revenue arrives on transaction.completed. Paddle bills a renewal as a transaction, so every renewal is attributed to the AI source that won the customer, and it carries the subscription id into the per-subscription lifetime value report. Traceten does not subscribe to Paddle’s subscription.* events, because the money is already on the transaction.

Refunds and net revenue

Your attributed revenue is net of refunds. Paddle reports a refund as an adjustment, and Traceten subtracts it from the AI source the original transaction was attributed to.

Only adjustments whose action is refund are subtracted. Paddle uses the same adjustment object for credits and chargebacks, and Traceten ignores both. A credit reduces a future invoice rather than returning money, so taking it off revenue already recorded would be wrong. A chargeback is a dispute, and Traceten does not act on disputes today.
A Paddle refund needs Paddle’s approval before the money moves. The figure in Traceten changes when the adjustment reaches approved, not when your customer or your team requests it. A pending_approval refund leaves your revenue alone.
The refund is dated on the day the adjustment was issued, not the day of the original transaction. A past day’s revenue figure never changes after the fact, and a day on which you refunded more than you took in reads as a negative number.
Conversion counts stay gross. A refunded transaction still counts as a conversion. The money is reported separately as a refunded figure beside the net one.
Partial refunds subtract exactly what the adjustment returned.
A cancelled subscription is not a refund. Cancelling stops future charges. The charges already paid were earned and stay in your totals, so cancelling changes no figure in Traceten. Only an approved refund adjustment takes money back off.

The amount Traceten records

Traceten records the tax-inclusive total your customer was charged, matching what a Stripe charge records. It does not record your net earnings. Two reasons: net is not comparable with the gross figures every other integration writes into the same column, so an otherwise identical Paddle site would read quietly smaller; and Paddle’s fee and earnings fields are empty until it balances the transaction, so at webhook time there is often no net figure to record at all.

Keys Traceten will not accept

Sandbox keys (starting pdl_sdbx_) are rejected in production. Sandbox transactions carry synthetic amounts that would corrupt your revenue totals. This mirrors the rule for Stripe test-mode keys.
Stripe keys. Pasting one names the mistake rather than failing on a network call.
A key with whitespace or a line break in it. Copy it again from Developer tools → Authentication.

Replay protection

Paddle signs each delivery with a timestamp, and Traceten rejects any delivery signed more than 30 seconds ago. Paddle’s own SDKs default to five seconds; Traceten allows a little more because it looks your connection up before it verifies, and that lookup can take a few seconds when its database has been idle. Paddle re-signs every retry, so a rejected delivery arrives again and succeeds.

How attribution works

When a transaction completes, Paddle sends a transaction.completed webhook to Traceten. Traceten then tries to tie the payment back to the originating session:

Checkout custom data: if you passed the visitor’s _traceten_vid cookie as traceten_visitor_id, Traceten matches it to the originating session exactly.
No match: the payment is still recorded so revenue totals stay complete, but it shows as unattributed (no AI source).

There is no email step, unlike every other integration. Paddle is the merchant of record and does not send the buyer’s email on a transaction, so custom data is the only signal there is.

Passing the visitor ID through checkout

Do this before you connect, or your revenue will all land as unattributed.

In the dashboard, open Settings → Integrations, pick Paddle and click Set up with AI. It copies a prompt for your coding assistant that wires the visitor ID into your checkout. The same card shows this site’s Visitor cookie name.

With Paddle.js, use window.traceten.getVisitorId(). It is the robust way to get the value, since it always resolves whatever the current cookie is rather than depending on a specific name:

// Client-side: read the visitor id and pass it into the checkout
const visitorId = window.traceten.getVisitorId() ?? ""; // null before the first pageview resolves

Paddle.Checkout.open({
  items: [{ priceId: "pri_...", quantity: 1 }],
  customData: { traceten_visitor_id: visitorId },
});

Or when you create a transaction server-side, forward the value your client already read via getVisitorId():

await fetch("https://api.paddle.com/transactions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PADDLE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    items: [{ price_id: "pri_...", quantity: 1 }],
    custom_data: { traceten_visitor_id: visitorIdFromClient ?? "" },
  }),
});

If you’d rather not change your client-side request shape, read the cookie directly instead:

Do not hardcode this cookie name. It is per-site and only correct on your configured domain (not on localhost). Find the real one under Sites → Settings → Cookies → Visitor cookie name.

// Client-side fallback: read the cookie by name instead of getVisitorId()
const visitorId = document.cookie.match(/(?:^|;\s*)_traceten_vid=([^;]+)/)?.[1] ?? "";

Paddle returns the value as custom_data on the webhook, and Traceten matches it back to the AI session that produced the visit. No personal data leaves your server on this path: the cookie value is pseudonymous and is not PII. For a subscription, set custom_data on the original checkout. Paddle carries it onto each renewal transaction, so renewals attribute to the AI source that won the customer in the first place.

What the 90-day import can and cannot match

Traceten imports your last 90 days of completed transactions when you connect, so revenue from before the destination existed is not lost. The 90-day bound is part of the request Traceten makes to Paddle, so older transactions are never returned to us at all. A historical transaction matches only if it already carries custom_data.traceten_visitor_id. Transactions from before you added that (which is most of them, on a first connect) are recorded as unattributed. They still count toward your revenue totals; they just carry no AI source.

Verify it worked

Paddle reads Connected in the dashboard.
The import banner finishes, and the Revenue page shows historical transactions.
Place a real transaction through a checkout that sets custom_data. It appears in Revenue with an AI source within a minute or two.

Troubleshooting

“Paddle would not let this key read transactions.” Add the transaction.read permission to the key and reconnect. “Paddle would not let this key create a notification destination.” Add the notification_setting.write permission and reconnect. “That is a Paddle sandbox key.” Traceten accepts live keys in production. Create a key from your live Paddle account. Connected, but revenue is not appearing. Check the destination under Developer tools → Notifications is still there, active, and pointed at Traceten. If you deleted it, reconnect from the Traceten dashboard. Everything shows as unattributed. Your checkout is not passing custom_data.traceten_visitor_id. For Paddle there is no fallback, so this is the whole of attribution.

Getting started

Install guide

AI crawlers

AI visibility

Dashboard

Goals and funnels

Integrations

Privacy

What this lets you do

Before you start

Connect Paddle

What Traceten does with the key

Refunds and net revenue

The amount Traceten records

Keys Traceten will not accept

Replay protection

How attribution works

Passing the visitor ID through checkout

What the 90-day import can and cannot match

Verify it worked

Troubleshooting

Next

​What this lets you do

​Before you start

​Connect Paddle

​What Traceten does with the key

​Refunds and net revenue

​The amount Traceten records

​Keys Traceten will not accept

​Replay protection

​How attribution works

​Passing the visitor ID through checkout

​What the 90-day import can and cannot match

​Verify it worked

​Troubleshooting

​Next

What this lets you do

Before you start

Connect Paddle

What Traceten does with the key

Refunds and net revenue

The amount Traceten records

Keys Traceten will not accept

Replay protection

How attribution works

Passing the visitor ID through checkout

What the 90-day import can and cannot match

Verify it worked

Troubleshooting

Next