Paddle checkout attribution: carry the channel in custom_data

To get Paddle checkout attribution, put the marketing source into the checkout's custom data before the buyer pays. On Paddle Billing that is a customData object in Paddle.Checkout.open(), or custom_data on a transaction your server creates.

Paddle Billing copies it to the subscription and returns it in the transaction.completed webhook, so the channel is still attached on payment 12. Paddle Classic calls the same field passthrough.

Where Paddle checkout attribution gets lost

The usual explanation is a redirect that strips UTM parameters.

On Paddle Billing the overlay checkout guide has the overlay opening as a modal on your page, while an inline checkout sits in the page layout, so your script can still read the query string and cookies.

The gap is the hand-off: a Paddle Billing transaction records the buyer, price, tax and payment method, and nothing about the ad that sent them.

How to pass the channel into a Paddle checkout

Steps 1 and 2 cover an overlay or inline checkout. Step 3 replaces them when your server builds the transaction.

Step 1: Save the first source on the landing page

By the time someone clicks Subscribe, a page or two of navigation has usually dropped the query string. Read the 4 UTM keys you use on the first pageview and keep the first source for each visitor.

1const KEYS = ["utm_source", "utm_medium", "utm_campaign", "utm_content"];2const params = new URLSearchParams(location.search);3 4if (params.get("utm_source") && !localStorage.getItem("first_touch")) {5  const touch = {};6  for (const key of KEYS) if (params.get(key)) touch[key] = params.get(key);7  localStorage.setItem("first_touch", JSON.stringify(touch));8}

Step 2: Pass it to Paddle.Checkout.open()

The custom data guide uses utm_medium, utm_source and utm_content as its own example, next to an integration_id. Keep the object flat, because Paddle Billing warns that nested values may display incorrectly in the dashboard.

When nothing was saved, send a marker such as none, since an object needs at least 1 key.

1function openCheckout() {2  const saved = JSON.parse(localStorage.getItem("first_touch") || "null");3  Paddle.Checkout.open({4    items: [{ priceId: "pri_01gs59hve0hrz6nyybj56z04eq", quantity: 1 }],5    customData: saved || { utm_source: "none" }, // an empty object is invalid6  });7}

Step 3: Or create the transaction on your server

Put custom_data in the POST /transactions body, then pass the returned ID to Paddle.Checkout.open({ transactionId }) or send the buyer to checkout.url. I'd set anything you act on, such as discounts or plan access, here, since a browser can send anything.

1const res = await fetch("https://api.paddle.com/transactions", {2  method: "POST",3  headers: {4    Authorization: "Bearer " + process.env.PADDLE_API_KEY,5    "Content-Type": "application/json",6  },7  body: JSON.stringify({8    items: [{ price_id: "pri_01gs59hve0hrz6nyybj56z04eq", quantity: 1 }],9    custom_data: { utm_source: "newsletter", utm_medium: "email", utm_campaign: "oct-launch" },10  }),11});12const { data } = await res.json();13// data.id is the txn_... ID for Paddle.Checkout.open({ transactionId }).14// data.checkout.url is the payment link for the same transaction.

Step 4: Read it from transaction.completed

The transaction.completed event fires once a transaction is fully paid and processed, carrying custom_data, subscription_id, currency_code and the totals, so write one row per payment.

The checkout.completed event in Paddle.js carries the same object for on-page tracking such as a Google Analytics 4 purchase hit.

1export async function POST(req: Request) {2  const raw = await req.text(); // verify Paddle-Signature against this raw body first3  const event = JSON.parse(raw);4  if (event.event_type !== "transaction.completed") return new Response("ok");5 6  const t = event.data;7  await saveSale({8    eventId: event.event_id, // unique per event: skip repeats9    transactionId: t.id,10    subscriptionId: t.subscription_id, // null for one-time prices11    currency: t.currency_code,12    subtotalMinor: t.details.totals.subtotal, // string in minor units13    source: t.custom_data?.utm_source ?? "missing",14  });15  return new Response("ok");16}

Verify the Paddle-Signature header first, as the signature verification guide lays out, then answer within 5 seconds.

A handler that stores the sale but replies late gets the event again, and 3 deliveries would count a $49 payment 3 times and credit its channel with $147. Dedupe on event_id.

Why the subscription needs the value too

Paddle Billing copies a transaction's custom data to the subscription it creates, and a subscription's to every transaction created from it: renewals, upgrades, downgrades and one-time charges. Take a $49 monthly plan sold through one newsletter link.

Over 12 payments that adds up to $588.

That carry-forward is what makes lifetime value by channel possible. Credit the pre-tax amount, because the total includes tax. The transaction in the custom data guide has a 20% rate:

Step 5: Subtract refunds from the channel

A refund never edits the sale. The adjustments guide records it as an adjustment against the completed transaction, announced by adjustment.created and later by adjustment.updated.

The payload carries transaction_id and subscription_id but no custom_data, so join on the transaction ID to the row you saved in step 4.

Live refunds start as pending_approval, and Paddle Billing approves some itself, such as 400 USD or less on a verified account. Subtract a refund once it is approved.

Step 6: Fix subscribers who already paid

A billed, canceled or completed transaction cannot be edited, but a subscription can. Send PATCH /subscriptions/{subscription_id} with a custom_data object and every later transaction created from it carries the value.

Match existing subscribers to your own click records by email and write the source onto each one. Payments already taken stay blank.

For 1,000 subscribers that is 5 list calls plus 1,000 updates, about 4.2 minutes at 240 requests a minute. If your handler was down, Paddle Billing can replay a failed notification through its API.

Step 7: Test in the sandbox

Buy once in the sandbox with utm_source=newsletter in the landing URL and look for it in 3 places: the checkout.completed callback, the transaction.completed body and the subscription.created body. Absent from all 3 means the call never sent it.

Present in the webhook but absent from your database means the handler reads the wrong field.

The Paddle Billing numbers that shape the setup

Paddle Classic and passthrough

On Paddle Classic the field is passthrough, a string sent with every webhook for the order, so the habit is JSON inside it, parsed on the way back.

The data mapping turns it into both transaction.custom_data and subscription.custom_data on Paddle Billing, so keep your key names when you migrate.

Keep the source alive until the buyer pays

Step 1 keeps the source in localStorage, and Safari Intelligent Tracking Prevention limits it.

Someone who clicks a newsletter link on Monday and returns directly 9 days later arrives with nothing saved and sends the marker.

Set the visitor ID from your server's response header, since the 7-day rule is written about script-created storage, and pass the buyer's email into checkout as a second match key.

The Safari ITP post goes deeper, and Stripe users do the same job with checkout metadata.

How TrackRev reads Paddle custom data

TrackRev is SaaS affiliate software with revenue attribution built in. Its pixel keeps a visitor ID in a first-party cookie named vid and exposes it as window.trk.vid. Passing it to Paddle Billing is the whole page-side integration.

Paddle.Checkout.open({
  items: [{ priceId: "pri_01gs59hve0hrz6nyybj56z04eq", quantity: 1 }],
  customer: { email: user.email },
  customData: { vid: window.trk.vid },
});

If all you need is the channel in your own database, the handler above does it with 1 webhook and 1 table. Sellers on Paddle Classic need another route.

The Paddle integration page, pricing and Paddle revenue attribution by marketing channel have the setup screens, plans and reporting.