Guides
Matching payments to visitors
For developers: the id to pass at checkout, where Stripe, Paddle and Chargebee carry it, and how payments find the visitor.
A billing system knows customers; an experiment knows visitors. For a payment to count in a test, LiftCanary has to know which visitor became the customer. On many sites the website snippet arranges this by itself at checkout. This page is for developers: the id to pass, where each billing system carries it, how LiftCanary resolves it, and what to send when your server creates the checkout.
The id to pass#
Pass the id LiftCanary decided the visitor's variations with. In the browser that's liftcanary.userId(): your user's id once you called identify() (or set data-user-id), otherwise the visitor's anonymous id. On your server it's the same rule:
| Where | The id |
|---|---|
| In the browser | liftcanary.userId() |
| On your server, the visitor is signed in | Your user id: the one you give identify() or data-user-id |
| On your server, not signed in | The liftcanary_anon cookie (ANONYMOUS_ID_COOKIE in the server SDKs) |
| No cookie: a site that asks for consent, and the visitor didn't accept | Nothing. The payment counts under the customer, outside experiments, as everything else about that visitor. |
import { ANONYMOUS_ID_COOKIE } from "@liftcanary/node";
/** The id LiftCanary decided with: your user's when signed in, else the anonymous visitor's. */
function liftcanaryId(req) {
return req.user?.id ?? req.cookies[ANONYMOUS_ID_COOKIE] ?? req.body?.liftcanaryId ?? null;
}The id isn't a secret and doesn't need to be verified: it only says which visitor a payment belongs to. At worst a customer puts their own payment under another visitor's id; a payment that didn't happen can't be added without the webhook's secret. Keep it under 256 characters. If the landing page and the app are on different subdomains, share the anonymous id first (data-cookie-domain, see From landing page to app), or your server reads another one.
Where each billing system carries it#
| Where the id goes | The snippet fills it | Your server, when it creates the checkout | |
|---|---|---|---|
| Stripe | client_reference_id of a Checkout Session; or metadata.liftcanary_id on the customer | Payment Links, pricing tables, buy buttons | Checkout Session: client_reference_id. Without Checkout: the customer's metadata |
| Paddle | Custom data, liftcanary_id, copied to the subscription and its renewals | paddle_button elements and Paddle.Checkout.open() | A transaction it creates: custom_data |
| Chargebee | The customer custom field cf_liftcanary_id | Chargebee.js checkouts and hosted page links | A hosted page: customer[cf_liftcanary_id] |
The key (liftcanary_id, cf_liftcanary_id) can be changed next to each webhook under Integrations. If your checkout already passes your own user id under another key, and you give LiftCanary the same id, point it at that key and you're done.
How LiftCanary finds the visitor#
For every event a webhook sends, LiftCanary takes the first of these that exists:
| 1. The id on the event | 2. A link | 3. Otherwise | |
|---|---|---|---|
| Stripe | Metadata liftcanary_id on the payment, or on the subscription (for its own events) | The customer (or a guest's payment) linked to a visitor by Checkout's client_reference_id, or by the customer's metadata | The Stripe customer id (cus_…) |
| Paddle | Custom data liftcanary_id on the subscription or the transaction | — | The Paddle customer id (ctm_…) |
| Chargebee | The customer's cf_liftcanary_id | — | The Chargebee customer id |
Refunds count against whoever their payment counted for: Paddle's and Stripe's refunds don't say who they're for, so LiftCanary looks up the payment they refund. Each event's matched_by property says how it was found: field (the id was on it) or customer_id (the customer, then any link).
Links, and people across sign-in#
Results never compare raw ids; they compare people. A link says that one id belongs to another: an anonymous visitor to the user they signed in as (identify()), or a Stripe customer to the visitor who checked out. Results follow links up to two steps, so all of these are one person, and the payment counts for the variation the visitor saw:
cus_Q1 → anon 0bba95cc-… → user u_8812
(Stripe Checkout) (signed up after paying)Links are applied when results are computed, not when events arrive. Stripe doesn't keep events in order (the subscription and the first payment often arrive before the checkout that links them), and a renewal can come months later: both find the visitor once the link exists. An id belongs to the first one it was linked to, so a shared computer where someone else signs in later doesn't merge two people, and a customer who checks out again from another browser stays with the first visitor.
When your server creates the checkout#
The snippet can't reach a checkout your server creates (most apps with their own backend do this for Stripe): pass the id there. One parameter is enough for every later event of that customer.
Stripe#
// Checkout: one parameter. LiftCanary links the Stripe customer it creates to the visitor.
const session = await stripe.checkout.sessions.create({
mode: "subscription",
line_items: [{ price: "price_…", quantity: 1 }],
client_reference_id: liftcanaryId(req), // letters, digits, - and _ (see below)
success_url: "https://example.com/welcome",
});
// Without Checkout (Elements, your own flow): on the customer, once.
const customer = await stripe.customers.create({
email: req.user.email,
metadata: { liftcanary_id: liftcanaryId(req) },
});Stripe accepts letters, digits, - and _ in client_reference_id, up to 200 characters, and silently drops anything else. Anonymous ids and most user ids fit. If yours don't, encode them the way the snippet does:
// Only if your ids contain other characters (an email…): Stripe drops such a
// client_reference_id without an error. LiftCanary decodes this form.
const ref = /^[A-Za-z0-9_-]{1,200}$/.test(id) ? id : "lc64_" + Buffer.from(id).toString("base64url");Link the customer, as above: that covers every event, payments and refunds included. Metadata liftcanary_id elsewhere names a visitor only for what carries it: on a payment (payment_intent_data.metadata, which Stripe copies to the charge), that payment; on a subscription (subscription_data.metadata), its trial, paying and cancellation events, but not its payments, which are charges.
Paddle#
// A transaction your server creates and the page opens with Paddle.Checkout.open({ transactionId }).
// Paddle copies custom data to the subscription it creates and to every renewal.
const transaction = await paddle.transactions.create({
items: [{ priceId: "pri_…", quantity: 1 }],
customData: { liftcanary_id: liftcanaryId(req) },
});Chargebee#
curl https://{site}.chargebee.com/api/v2/hosted_pages/checkout_new_for_items \
-u $CHARGEBEE_API_KEY: \
-d "subscription_items[item_price_id][0]=pro-USD-monthly" \
-d "customer[cf_liftcanary_id]=<the visitor id>"If you create Chargebee customers under your own user ids and identify visitors with the same ids, nothing else is needed: the customer id is the visitor's id.
Check it#
- In the browser: with
?liftcanary_debug=1the console shows each id the snippet passes, such asStripe checkout: client_reference_id = …orPaddle checkout: liftcanary_id = …. - In the billing system: its webhook log shows LiftCanary's answer to each call:
{"accepted":1,"eventKey":"billing.revenue","userId":"…"}with the id the event counted under, or for a Stripe checkout{"accepted":1,"linked":{"cus_…":"…"}}with the visitor it linked. - In LiftCanary: each billing card under Integrations shows the last 7 days: events, how many found their visitor (the id was on them, or their customer is linked to one), how many came from visitors in an experiment, and whether the last event found its visitor, so one test checkout tells you where you stand. A Stripe checkout without
client_reference_idis counted apart and named on the card. Under How do your pages open the checkout? the card says whether your case needs a developer, shows the code, and copies instructions to send them.