Guides
Stripe
Trials, paid subscriptions, revenue and cancellations from Stripe's webhook, 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. Stripe sends these events to a webhook endpoint. 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 visitors check out through a Payment Link, a pricing table or a buy button, the website snippet tells Stripe 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 Stripe for the environment to use. You get a webhook URL. Connect Stripe's test mode to a test environment and live mode to production, each with its own endpoint.
Add a webhook endpoint in Stripe
In Stripe, open Developers → Webhooks and add a destination for events from your account, sent to a webhook endpoint. Paste the URL and send these events (the others are ignored):
checkout.session.completed,customer.created,customer.updated,customer.subscription.created,customer.subscription.updated,customer.subscription.deleted,charge.succeeded,refund.createdandrefund.updated. Any API version works.Paste its signing secret into LiftCanary
Stripe makes a signing secret for the endpoint (it starts with
whsec_) and signs every call with it. Copy it from the endpoint in Stripe and paste it into LiftCanary, next to the URL. Until then LiftCanary refuses Stripe's calls, and Stripe 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 Stripe has sent events, Goals also lists them under tracked events without a goal.
Goals from Stripe#
| Goal | Event key | Counts | Measured as |
|---|---|---|---|
| Trial started | billing.trial_started | A subscription created in trial (customer.subscription.created with the status trialing) | Conversion rate |
| Became a paying subscriber | billing.subscribed | A trial, or an incomplete subscription whose first payment went through, that turns active (customer.subscription.updated), or a subscription created already active | Conversion rate |
| Subscription revenue | billing.revenue | Every successful charge (charge.succeeded), renewals and one-time payments included, minus succeeded refunds (refund.created or refund.updated) | Value per visitor |
| Cancelled subscription | billing.cancelled | A cancelled subscription (customer.subscription.deleted); a winner lowers it | Conversion rate |
These are the same goals as Paddle'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 charge counts once, however often Stripe sends it, and a refund counts once it has succeeded, against the visitor its charge counted for. A subscription that recovers from past_due isn't a new paying subscriber. 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#
Stripe's events name a customer; an experiment knows visitors. Only one event says which visitor checked out: Checkout's checkout.session.completed, in its client_reference_id. When it arrives, LiftCanary links the Stripe customer to that visitor (and, for a payment without a customer, the payment). Every other event of the customer counts for the visitor through that link: the subscription, each renewal, a refund months later, whichever order Stripe sends them in. A visitor who signs in only after paying still counts, through their sign-in (see People across sign-in). A customer that nothing links counts under its Stripe customer id, and 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.
Payment Links, pricing tables and buy buttons#
The website snippet passes the visitor's id by itself: it adds client_reference_id to buy.stripe.com links when they're clicked, and sets client-reference-id on stripe-pricing-table and stripe-buy-button elements, including ones your page renders later. A reference your page set is left as it is. Stripe accepts letters, digits, - and _ only, so another id (an email, say) is encoded, and LiftCanary decodes it. Check it with ?liftcanary_debug=1: the console shows Stripe checkout: client_reference_id = ….
<!-- Nothing to change: the snippet adds the visitor's id when it's clicked or shown. -->
<a href="https://buy.stripe.com/…">Subscribe</a>
<stripe-pricing-table pricing-table-id="prctbl_…" publishable-key="pk_live_…"></stripe-pricing-table>
<stripe-buy-button buy-button-id="buy_btn_…" publishable-key="pk_live_…"></stripe-buy-button>Your server creates the Checkout Session#
Most apps with their own backend create the Checkout Session on the server: pass the visitor's id as client_reference_id there. In the browser that 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. If you already pass your own user id there, and give the same id to LiftCanary when visitors sign in, nothing else is needed.
// Node, when your server creates the Checkout Session.
// visitorId: liftcanary.userId() sent from the page, your signed-in user's id,
// or the liftcanary_anon cookie for a visitor who isn't signed in.
const session = await stripe.checkout.sessions.create({
mode: "subscription",
line_items: [{ price: "price_…", quantity: 1 }],
client_reference_id: visitorId,
success_url: "https://example.com/welcome",
});Without Checkout#
With Elements or your own payment flow there is no checkout to carry it: put the visitor's id in the customer's metadata under liftcanary_id (you can pick another key next to the webhook), and LiftCanary links the customer when Stripe reports it created or updated. The same key on a payment's metadata (payment_intent_data.metadata) names the visitor of that payment directly; on a subscription's, of its trial, paying and cancellation events, but not of its payments.
// Without Checkout (Elements, the API): when you create the customer.
const customer = await stripe.customers.create({
email,
metadata: { liftcanary_id: visitorId },
});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 each charge's amount in its own currency (Stripe sends the smallest unit: cents, or yen for JPY), with the currency kept on each event. Revenue goals add amounts as they are, so they read best for a site that charges in one currency. An authorization that isn't captured yet doesn't count.
Check it works#
Stripe shows each delivery to the endpoint with LiftCanary's answer. A counted event answers {"accepted":1,"eventKey":"billing.subscribed","userId":"cus_…"}, a checkout {"accepted":1,"linked":{"cus_…":"…"}} with the visitor it linked, and an event that isn't a goal {"ignored":"…"} with the reason. 401 means the signature doesn't match: paste the endpoint's signing secret into LiftCanary again. 404 means the environment isn't connected. With the Stripe CLI you can send test events to a local collector (stripe listen --forward-to). In LiftCanary, the Stripe card under Integrations shows the last 7 days for each environment: how many events arrived, how many found their visitor, how many came from visitors who were in an experiment, and whether the last one found its visitor. Checkouts that came without client_reference_id are counted and named there, and the card copies instructions for your developer.
Privacy and security#
From each event LiftCanary keeps the visitor's id, the Stripe customer, subscription, charge, refund and event ids, the price, the amount and the currency: never names, emails, addresses, card details or the rest of your metadata. Each call is checked against Stripe's signature, and calls signed more than five minutes earlier are refused; the SDK key in your pages can't send Stripe events, so no one can add payments that didn't happen. LiftCanary keeps the signing secret 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.