Connect Paddle

Paddle Billing sends completed transactions and refund adjustments to a notification destination signed with its secret key. Checkout custom data links each transaction to a visit.

Set up the notification destination

1. Copy the webhook URL

   In MetricRaven, open Settings → Integrations → Paddle and copy the webhook URL.

2. Create a destination in Paddle

   In Paddle, open Developer tools → Notifications → New destination. Choose Webhook, paste the URL, and select transaction.completed, adjustment.created and adjustment.updated. Also select customer.created and customer.updated to match payments by the buyer's email, and the subscription.* events (created, activated, trialing, updated, past_due, paused, resumed, canceled) for subscription goals.

3. Paste the secret key in MetricRaven

   Open the saved destination, copy its secret key (pdl_ntfset_…), paste it into the Paddle card and choose Connect Paddle.

Pass the visitor ID at checkout

Paddle keeps custom_data on the transaction and copies it to the subscription and its renewals. Use these keys:

1. Read the visitor ID in the browser

   The MetricRaven script exposes window.analytics.getVisitorId(). Read it when checkout starts and send it to your checkout code:

   script.js

   Copy

   1

   2

   3

   4

   // Read this in the visitor's browser when they start checkout.
   const visitorId = window.analytics?.getVisitorId() ?? null;
   // Send visitorId to your own checkout endpoint alongside its usual request data.
   // Use the authenticated user ID from your backend; do not trust a browser-supplied user ID.

2. Add it to the checkout

   With Paddle.js:

   Paddle.js

   Copy

   1

   2

   3

   4

   5

   6

   7

   // Browser: Paddle.js overlay or inline checkout.
   Paddle.Checkout.open({
     items: [{ priceId: "pri_YOUR_PRICE_ID", quantity: 1 }],
     customData: {
       metricraven_visitor_id: window.analytics?.getVisitorId() ?? "",
     },
   });

   Or create the transaction on your server, which can also set your trusted user ID:

   Transactions API

   Copy

   1

   2

   3

   4

   5

   6

   7

   8

   9

   10

   11

   12

   13

   14

   15

   16

   17

   // Server: create a transaction with the Paddle API, then open it with Paddle.js.
   const response = await fetch("https://api.paddle.com/transactions", {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       Authorization: `Bearer ${process.env.PADDLE_API_KEY}`,
     },
     body: JSON.stringify({
       items: [{ price_id: "pri_YOUR_PRICE_ID", quantity: 1 }],
       custom_data: {
         ...(visitorId ? { metricraven_visitor_id: visitorId } : {}),
         ...(user ? { metricraven_user_id: user.id } : {}),
       },
     }),
   });
   const { data } = await response.json();
   // In the browser: Paddle.Checkout.open({ transactionId: data.id })

MetricRaven links each payment to a visit using the first of these that is available:

1. The metricraven_visitor_id passed through checkout.
2. The metricraven_user_id (or the provider's customer external ID), matched to a visitor you linked with the Identify API.
3. An earlier payment from the same provider customer, so renewals keep the original attribution.
4. The checkout email, matched to an email you sent to the Identify API.
5. The checkout email, matched to a browser that called payment({ email }) within an hour of the payment.

Can't set custom data on your checkout? See Other Paddle methods to match by the buyer's email.