LiftCanary

Guides

Chargebee

Trials, paid subscriptions, revenue and cancellations from Chargebee'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. Chargebee already sends these events to a webhook. 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 Chargebee's checkout, the website snippet tells Chargebee which visitor is checking out by itself (see which visitor a payment belongs to).

  1. Connect an environment

    In LiftCanary, open Integrations and, under Billing, connect Chargebee for the environment to use. You get a webhook URL, a user name and a password. The password is shown once: copy it before you leave the page (connect again for a new one). Connect your Chargebee test site to a test environment and your live site to production, each with its own webhook.

  2. Add the webhook in Chargebee

    In Chargebee, open Settings → Configure Chargebee → Webhooks and choose Add Webhook. Paste the URL, turn on Protect webhook URL with basic authentication and enter the user name and password from LiftCanary. Send these events (the others are ignored): subscription_created, subscription_started, subscription_activated, subscription_cancelled, payment_succeeded and payment_refunded. Also tick Exclude card information from webhook call: LiftCanary never needs it.

  3. Add the LiftCanary ID field

    Open Settings → Configure Chargebee → Custom Fields and add a single-line text field called LiftCanary ID to customers. Keep it optional, and hidden at checkout (Chargebee's default for new fields). Its API name should be cf_liftcanary_id; if Chargebee shows another, enter that one in LiftCanary next to the webhook. This field tells LiftCanary which visitor a customer was: see which visitor a payment belongs to.

  4. 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 Chargebee has sent events, Goals also lists them under tracked events without a goal.

Goals from Chargebee#

GoalEvent keyCountsMeasured as
Trial startedbilling.trial_startedA subscription created in trial (subscription_created, or subscription_started for one set to start later)Conversion rate
Became a paying subscriberbilling.subscribedA trial that turns into a paid subscription (subscription_activated), or a subscription created already payingConversion rate
Subscription revenuebilling.revenueEvery successful payment (payment_succeeded), renewals included, minus refunds (payment_refunded)Value per visitor
Cancelled subscriptionbilling.cancelledA cancelled subscription (subscription_cancelled); a winner lowers itConversion rate

These goals are the same with any billing system LiftCanary connects to (Stripe and Paddle too), so a goal keeps working if you move from one to another. Each event says where it came from in its provider property. Chargebee retries a webhook call until it gets an answer, for a few days; each of its events counts once however often it arrives. 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 Chargebee event names a customer; an experiment knows visitors. LiftCanary connects the two with the customer's LiftCanary ID field: the id of the visitor who checked out, the same id the website snippet decides with. When the field is empty, it uses the Chargebee customer id instead. A visitor whose id doesn't appear in an experiment simply doesn't count in it (the whole picture, for developers: Matching payments to visitors). How the field gets filled depends on how your checkout works:

Your pages open Chargebee's checkout#

With Chargebee.js on your pages (its checkout buttons, your own buttons using its cart, or openCheckout() without a hosted page from your server), or with plain links to Chargebee's hosted pages, the website snippet fills the field by itself: right before the checkout opens it adds the visitor's id to the customer details, keeping the ones your page set, and adds customer[cf_liftcanary_id] to hosted page links when they're clicked. A field your page or server already filled is left as it is. Check it with ?liftcanary_debug=1: the console shows Chargebee checkout: cf_liftcanary_id = … when the checkout opens.

Your customers already have your user ids#

If you create Chargebee customers under your own user ids, and give the same id to LiftCanary when visitors sign in (data-user-id or liftcanary.identify(), see People across sign-in), nothing else is needed: the Chargebee customer id is the visitor's id. Visits before signing in count too, once a sign-in links them.

Your server creates the checkout#

When your server creates Chargebee's checkout (hosted pages), it adds one parameter: the visitor's id in customer[cf_liftcanary_id]. 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. Chargebee's SDKs take the same parameter on the customer.

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's LiftCanary id}"

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#

Chargebee sends amounts in the currency's smallest unit (cents, or yen for JPY); LiftCanary records them in the payment's own currency, with the currency and Chargebee'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#

Chargebee's event log shows each webhook 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 password doesn't match (connect again for a new one, then update it in Chargebee) and 404 that the environment isn't connected. In LiftCanary, the Chargebee 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 fills the field (above). On your pages, the snippet loads its checkout helper (checkout.js, about 1 KB) only while the environment is connected.

Privacy and security#

From each event LiftCanary keeps the visitor's id, the Chargebee customer, subscription and event ids, the plan, the amount and the currency: never names, emails, addresses or card details. The webhook has its own password, kept only as a fingerprint; the SDK key in your pages can't send Chargebee events, so no one can add payments that didn't happen. With a hybrid deployment, the webhook URL is your own data plane's, and the events stay in your ClickHouse.