LiftCanary

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:

WhereThe id
In the browserliftcanary.userId()
On your server, the visitor is signed inYour user id: the one you give identify() or data-user-id
On your server, not signed inThe liftcanary_anon cookie (ANONYMOUS_ID_COOKIE in the server SDKs)
No cookie: a site that asks for consent, and the visitor didn't acceptNothing. 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 goesThe snippet fills itYour server, when it creates the checkout
Stripeclient_reference_id of a Checkout Session; or metadata.liftcanary_id on the customerPayment Links, pricing tables, buy buttonsCheckout Session: client_reference_id. Without Checkout: the customer's metadata
PaddleCustom data, liftcanary_id, copied to the subscription and its renewalspaddle_button elements and Paddle.Checkout.open()A transaction it creates: custom_data
ChargebeeThe customer custom field cf_liftcanary_idChargebee.js checkouts and hosted page linksA 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 event2. A link3. Otherwise
StripeMetadata 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 metadataThe Stripe customer id (cus_…)
PaddleCustom data liftcanary_id on the subscription or the transaction—The Paddle customer id (ctm_…)
ChargebeeThe 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).

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:

Two steps
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:

TypeScript
// 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#

Chargebee API · hosted page
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=1 the console shows each id the snippet passes, such as Stripe checkout: client_reference_id = … or Paddle 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_id is 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.