Guides
Paddle
Trials, paid subscriptions, revenue and cancellations from Paddle Billing's notifications, as goals.
Most of what a subscription business wants from an experiment happens after the visit: a trial turns into a paying customer two weeks later, a renewal is charged, a customer cancels or gets a refund. Paddle Billing sends these events to a notification destination. Connect it to LiftCanary and they become goals: trials started, paying subscribers, revenue and cancellations, counted for the visitor who saw your experiment. Connecting it takes no code, and when your pages open Paddle's checkout with Paddle.js, the website snippet tells Paddle which visitor is checking out by itself (see which visitor a payment belongs to).
Connect an environment
In LiftCanary, open Integrations and, under Billing, connect Paddle for the environment to use. You get a webhook URL. Connect your Paddle sandbox to a test environment and your live account to production, each with its own destination.
Add a notification destination in Paddle
In Paddle, open Developer tools → Notifications and add a new destination of the webhook type. Paste the URL and send these events (the others are ignored):
subscription.created,subscription.activated,subscription.canceled,transaction.completed,adjustment.createdandadjustment.updated.Paste its secret key into LiftCanary
Paddle makes a secret key for the destination when you save it, and signs every call with it. Open the destination in Paddle, copy the key (it starts with
pdl_ntfset_) and paste it into LiftCanary, next to the URL. Until then LiftCanary refuses Paddle's calls, and Paddle retries them, so nothing is lost if you paste it soon.Add the goals
In Goals, choose New goal and one of the goals under From your billing system, then use it in experiments like any other goal. Once Paddle has sent events, Goals also lists them under tracked events without a goal.
Goals from Paddle#
| Goal | Event key | Counts | Measured as |
|---|---|---|---|
| Trial started | billing.trial_started | A subscription created in trial (subscription.created with the status trialing) | Conversion rate |
| Became a paying subscriber | billing.subscribed | A trial that turns into a paid subscription (subscription.activated), or a subscription created already paying | Conversion rate |
| Subscription revenue | billing.revenue | Every completed payment (transaction.completed), renewals included, minus approved refunds (adjustment.created or adjustment.updated) | Value per visitor |
| Cancelled subscription | billing.cancelled | A cancelled subscription (subscription.canceled); a winner lowers it | Conversion rate |
These are the same goals as Stripe's and Chargebee's, so a goal keeps working if you move between them; each event says where it came from in its provider property. A payment counts once, however often Paddle sends it, and a transaction that pays nothing (a trial starting, a payment method update) doesn't count. A refund counts once Paddle approves it, against the visitor its payment counted for. Revenue goals cap each visitor's total at the 99th percentile of paying visitors by default, so one large annual plan can't decide a test (see Goals).
Which visitor a payment belongs to#
A Paddle event names a customer; an experiment knows visitors. LiftCanary connects the two with the checkout's custom data: the id of the visitor who checked out, under the key liftcanary_id (you can pick another next to the webhook). Paddle copies custom data from the checkout's transaction to the subscription it creates and from there to every renewal, so each later event carries it too. Without it, LiftCanary uses the Paddle customer id instead. A visitor whose id doesn't appear in an experiment simply doesn't count in it. For the whole picture, with code for each case, see Matching payments to visitors.
Your pages open Paddle's checkout#
With Paddle.js on your pages, the website snippet adds the visitor's id by itself, both to paddle_button elements and to Paddle.Checkout.open() calls from your own code, and keeps the custom data your page set. A key your page already set is left as it is. Check it with ?liftcanary_debug=1: the console shows Paddle checkout: liftcanary_id = … when the checkout opens.
<!-- Paddle.js adds it at checkout, nothing to change: -->
<a href="#" class="paddle_button" data-items='[{"priceId":"pri_…","quantity":1}]'>Subscribe</a>
<script>
// Your own code: the snippet adds liftcanary_id next to your custom data.
Paddle.Checkout.open({ items: [{ priceId: "pri_…", quantity: 1 }], customData: { plan: "pro" } });
</script>Your server creates the transaction#
When your server creates the transaction and the page opens the checkout with its id (transactionId), Paddle takes the custom data from the transaction, so your server adds it there. In the browser the visitor's id is liftcanary.userId(); on your server, it's your signed-in user's id, or the liftcanary_anon cookie for a visitor who isn't signed in.
curl https://api.paddle.com/transactions \
-H "Authorization: Bearer {paddle_api_key}" \
-H "Content-Type: application/json" \
-d '{
"items": [{ "price_id": "pri_…", "quantity": 1 }],
"custom_data": { "liftcanary_id": "{the visitor's LiftCanary id}" }
}'Your customers already have your user ids#
If your checkout already puts your user id in custom data, and you give the same id to LiftCanary when visitors sign in (data-user-id or liftcanary.identify(), see People across sign-in), enter that key next to the webhook instead of liftcanary_id: nothing else is needed. Visits before signing in count too, once a sign-in links them.
Trials and late conversions#
A visitor who starts a 14-day trial on the last day of a test pays after it ends. The paying-subscriber and revenue goals therefore keep counting for 14 days after an experiment ends when you add them in the dashboard: set this to your trial length on the goal (Late conversions, up to 30 days; see Goals). Only visitors who were in the experiment count; the report says until when its results can still change.
Revenue and currency#
LiftCanary records what the customer paid (the transaction's grand total, tax included) in the payment's own currency, with the currency, your payout currency and Paddle's exchange rate kept on each event. Revenue goals add amounts as they are, so they read best for a site that charges in one currency.
Check it works#
Paddle's notification log shows each call with LiftCanary's answer. A counted event answers {"accepted":1,"eventKey":"billing.subscribed","userId":"…"}, with the visitor it counted for; an event that isn't a goal answers {"ignored":"…"} with the reason. 401 means the signature doesn't match: paste the destination's secret key into LiftCanary again. 404 means the environment isn't connected. In LiftCanary, the Paddle card under Integrations shows the last 7 days for each environment: how many events arrived, how many carried a LiftCanary ID, and how many came from visitors who were in an experiment. If few carry an id, check how your checkout passes custom data (above).
Privacy and security#
From each event LiftCanary keeps the visitor's id, the Paddle customer, subscription, transaction and event ids, the price, the amount and the currency: never names, emails, addresses, card details or the rest of your custom data. Each call is checked against Paddle's signature, and calls signed more than five minutes earlier are refused; the SDK key in your pages can't send Paddle events, so no one can add payments that didn't happen. LiftCanary keeps the secret key encrypted and never shows it again. With a hybrid deployment, the webhook URL is your own data plane's, and the events stay in your ClickHouse.