Chargebee

Referly tracks Chargebee subscriptions by storing the referral on the customer in Chargebee. That one decision shapes the whole integration: because the referral lives on the customer rather than on a single checkout, every invoice that customer is ever billed carries it — so renewals, upgrades, and plan changes all keep earning the affiliate their commission with no extra work. Setting it up takes four things: the tracking script on your site, a custom field in Chargebee to hold the referral, a small piece of code to fill that field in at checkout, and a webhook so Chargebee tells Referly when money moves. A fifth, optional step connects your API key so Referly can read your plan names for product-level commission.

Chargebee is the most hands-on of Referly’s payment integrations — you create the custom field and the webhook yourself. Set aside 20 minutes and work through the steps in order.

What the Chargebee integration can and can’t do

What you want to track	Does Chargebee cover it?
Clicks on affiliate links	Yes, once the tracking script is on your site (Step 1).
New referred customers	Yes — as soon as a subscription is created, started, or activated for a customer carrying a referral.
Free trials	Yes — a trial subscription creates the referred customer straight away. The commission follows when the trial converts and Chargebee takes the first payment.
First payments and every renewal	Yes, and renewals need no extra setup. The referral sits on the customer, so every invoice raised against them is credited to the same affiliate.
Plan and item-level detail	Yes, but only if you complete Step 5. Without your API key, sales come through with their total but no line items, so product-based commissions won’t have anything to match on.
Tax	Yes — tax is read from the invoice so you can decide whether commission is paid on it.
Currency	Yes — the currency comes from the plan being billed.
Refunds	Yes — see Refunds.
Customers with no referral on them	No — if the customer has no referral stored, Referly records nothing at all for that subscription or invoice, not even an unattributed sale.
Coupon and discount code attribution	No — Chargebee coupons don’t identify an affiliate. If your affiliates promote codes rather than links, Stripe coupon codes or Shopify handle that.
Sign-ups with no subscription	No — Chargebee only reports subscriptions and invoices. Use the Universal integration for leads.
Shipping	No — shipping isn’t reported separately for Chargebee.
Chargebacks	No — a chargeback isn’t reversed automatically. Adjust the sale or reward by hand.
Test site and live site at the same time	No — a Referly program connects to one Chargebee site. Test and live sites in Chargebee are separate, with their own keys and their own webhooks.

Before you start

You’ll need:

Admin access to your Chargebee site, so you can add a custom field, a webhook, and an API key.
The ability to add code to your website, or someone who can.
Your Referly integration guide open. In Referly, open your program, go to Settings, then Integrations, and pick the card that matches how you take payments: Chargebee Drop-In, Chargebee Payment Links, or Chargebee API. Your webhook address is shown there, already filled in with your program’s details.

Step 1: Install the tracking script on your site

The tracking script recognises visitors who arrived from an affiliate link, records the click, and remembers who referred them until they subscribe. Copy the snippet from Step 1 of your Chargebee guide in Referly — it comes pre-filled with your program ID — and paste it inside the head section of your website, on every page.

Tracking script

<script
  src="https://referly.so/affiliate-tracker.js"
  data-affiliate
  data-program-id="YOUR_PROGRAM_ID"
  async>
</script>

If you use Google Tag Manager, switch to the Using Google Tag Manager tab in the guide for that version instead.

Step 2: Create the custom field in Chargebee

This is the field that holds the referral against each customer. Get the API name exactly right — Referly looks for that specific name and nothing else.

Open custom fields

In your Chargebee dashboard, go to Settings, then Configure Chargebee, then Custom Fields.

Add a customer field

Choose Customer as the object the field belongs to, and Single line text as its type.

Name it

Set the Label to pushlap_affiliate_id and the API Name to cf_pushlap_affiliate_id. Chargebee usually adds the cf_ prefix for you — check that the final API name matches exactly.

Save

Save the field. It’s now available on every customer in your site.

If you create customers through Chargebee’s API rather than a hosted checkout, you can skip this field and put the referral in the customer’s metadata instead, under the key pushlap_affiliate_id. Referly checks both places.

Step 3: Send the referral into Chargebee

Pick the tab that matches how your customers subscribe. In every case the snippet goes near the bottom of the page, just before the closing body tag, on the pages where checkout happens — and the tracking script from Step 1 has to be on the same page.

Drop-in checkout
Payment links
Chargebee API

Use this if you open Chargebee’s in-page checkout with Chargebee.js. It sets the custom field on the cart’s customer before checkout opens.

Chargebee drop-in

<script>
  var setupCb = function () {
    if (typeof Chargebee === "undefined") return;

    var cbInstance = Chargebee.getInstance();
    var cart = cbInstance.getCart();
    if (window.affiliateId) {
      cart.setCustomer({
        cf_pushlap_affiliate_id: window.affiliateId,
      });
    }
  };
  window.addEventListener("affiliate_id_ready", function (event) {
    "complete" === document.readyState ||
    ("loading" !== document.readyState && !document.documentElement.doScroll)
      ? setupCb()
      : document.addEventListener("DOMContentLoaded", setupCb);
  });
</script>

Use this if you send people to Chargebee payment link pages. It adds the referral onto every Chargebee link on the page, so it travels with the customer into checkout.

Chargebee payment links

<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.7.1/jquery.min.js"></script>
<script>
  $(document).ready(function () {
    setTimeout(function () {
      const affiliateId = window.affiliateId;

      $('a[href*="chargebee.com"]').each(function () {
        const oldUrl = $(this).attr("href");
        if (!oldUrl.includes("customer[cf_pushlap_affiliate_id]")) {
          const separator = oldUrl.includes("?") ? "&" : "?";
          const newUrl =
            oldUrl +
            separator +
            "customer[cf_pushlap_affiliate_id]=" +
            encodeURIComponent(affiliateId);
          $(this).attr("href", newUrl);
        }
      });
    }, 2000);
  });
</script>

Use this if you create customers yourself through Chargebee’s API. Pass the referral in the customer’s metadata when you create them — no custom field needed.

Creating a customer

import { ChargeBee } from "chargebee-typescript";
var chargebee = new ChargeBee();

chargebee.configure({ site: "your-site", api_key: "your-api-key" });

chargebee.customer
  .create({
    first_name: "John",
    last_name: "Doe",
    email: "john@example.com",
    meta_data: {
      pushlap_affiliate_id: "THE_VALUE_FROM_window.affiliateId",
    },
  })
  .request(function (error, result) {
    if (error) {
      console.log(error);
    }
  });

The value comes from your front end, where the tracking script makes it available as window.affiliateId. Send it to your backend when the customer signs up, then pass it here.

Step 4: Add the Referly webhook in Chargebee

This is how Chargebee tells Referly that a subscription started or an invoice was paid. Without it, nothing reaches Referly at all.

Open webhook settings

In your Chargebee dashboard, go to Settings, then Configure Chargebee, then API Keys and Webhooks, and open the Webhooks tab. Select Add Webhook.

Name it

Set the Webhook Name to Referly Integration, or anything else you’ll recognise later.

Paste the webhook address

Copy the webhook address from your Chargebee guide in Referly and paste it into the Webhook URL field. It already includes your program’s details, so copy it rather than typing it out.

Set the API version

Choose Version 2. Referly reads Chargebee’s version 2 format.

Choose the events

Rather than leaving All Events selected, pick these seven:

Subscription Created
Subscription Started
Subscription Activated
Subscription Cancelled
Subscription Deleted
Payment Succeeded
Payment Refunded

Exclude card information

Turn on Exclude Card Information. Referly has no use for card details, and there’s no reason to send them anywhere they aren’t needed.

Save

Save the webhook. Chargebee allows up to five webhooks per site, so this sits alongside any you already have.

Test sites and live sites in Chargebee are entirely separate. A webhook added on your test site won’t send anything from your live site — add it on both if you plan to test first, and remember each site has its own API keys too.

Step 5: Connect your API key for plan-level detail

This step is optional but strongly recommended. It lets Referly look up the plans on each invoice, which is what puts plan names on your sales and makes different commission rates per plan possible.

Create the key in Chargebee

Open API keys

In your Chargebee dashboard, go to Settings, then Configure Chargebee, then API Keys and Webhooks, and open the API Keys tab. Select Add API Key.

Choose the key type

Choose a Read-Only Key. Referly only reads your plans — it never changes anything in Chargebee — so there’s no reason to hand over write access.

Copy the key

Copy it as soon as it’s created and keep it somewhere safe. Chargebee’s API key documentation covers key types in more detail.

Note your site name

Your site name is the first part of your Chargebee address. If you sign in at mysite.chargebee.com, your site name is mysite — that part only, with no .chargebee.com on the end.

Enter them in Referly

Open the integrations dialog

In Referly, open your program, go to Settings, then Integrations, select Connect Integration in the top right, and choose Chargebee.

Fill in both fields

Paste your key into API key and your site name into Site.

Connect

Select Connect. If it works, a green Connected badge appears with your site name.

These fields lock once saved. To change the key or point at a different site, select Disconnect and connect again.

Step 6: Test the whole flow

Use your Chargebee test site

Add the custom field, the webhook, and the API key on your test site, and point your test page at your test site’s checkout.

Visit your site through an affiliate link

Use a real affiliate’s referral link from your Affiliates page, in a private window.

Check the click landed

In Referly, open that affiliate’s record and confirm the click count went up.

Go through your checkout and subscribe with one of Chargebee’s test cards.

Check the customer in Chargebee

Open the new customer in your Chargebee dashboard and look at the pushlap_affiliate_id field. If it’s empty, the Step 3 snippet didn’t run — that’s the single most common failure, and everything downstream depends on it.

Check the result in Referly

Open Customers to find the buyer attached to the affiliate, Sales to confirm the invoice amount and the plan, and Rewards to see the commission.

Switch to live

Repeat Steps 2, 4, and 5 on your live site, point your checkout back at live, and delete your test customers and sales from Referly so they don’t skew your reporting.

What happens automatically once you’re set up

A subscription is created, started, or activated

The customer becomes a referred customer in Referly, attached to the affiliate stored on their Chargebee record, with their plan name. A trial subscription lands here too, before any money has moved.

An invoice is paid

The invoice becomes a sale and the commission is worked out from the affiliate’s plan. Tax comes across, and the plans on the invoice come across as line items if you connected your API key.

A subscription renews

Every renewal invoice raises another sale, credited to the same affiliate, because the referral is stored on the customer rather than on one checkout. This is what makes recurring commissions work.

A payment is refunded

See Refunds below.

Refunds

When a payment is refunded in Chargebee, Referly finds the matching sale and marks it as refunded, so no commission is owed on money you gave back. This only applies while the commission is still on hold. Once the affiliate has been cleared for payout on that sale, it’s left alone — adjust it by hand if you want it reversed. See Refunds and Reward holds.

Disconnecting

There are two parts, and they’re independent:

To stop tracking, delete the Referly webhook in your Chargebee dashboard under Settings, then Configure Chargebee, then API Keys and Webhooks. Nothing reaches Referly after that.
To remove your API key, open Connect Integration in Referly, select Chargebee, and choose Disconnect. You can also revoke the key on Chargebee’s side.

Removing the API key alone doesn’t stop tracking — sales still arrive through the webhook, they just lose their plan-level detail. Nothing already tracked is deleted. Anything that happens while the webhook is gone is not recorded and won’t be picked up later.

Troubleshooting

Nothing is appearing in Referly

Work backwards. Open a recent customer in Chargebee and check whether the pushlap_affiliate_id field has a value. If it’s empty, the problem is the Step 3 snippet. If it has a value, check the webhook in Chargebee — that it exists, uses Version 2, and has the seven events selected.

The custom field is always empty

Three things to check: the API name is exactly cf_pushlap_affiliate_id, the tracking script from Step 1 is on the same page as the checkout snippet, and the visitor actually arrived through an affiliate link. Test in a private window with a referral link.

Customers appear but sales don't

The subscription events are getting through and the payment event isn’t. Check that Payment Succeeded is selected on your webhook in Chargebee.

Sales appear with no plan name or line items

That’s the API key connection from Step 5 missing or wrong. Check that the site name is the short name only — mysite, not mysite.chargebee.com — and that the key belongs to the same site the sales are coming from.

It worked on my test site but not live

Chargebee keeps test and live completely separate. The custom field, the webhook, and the API key all have to be created again on your live site.

Renewals aren't creating commissions

Open the customer in Chargebee and confirm the referral is still stored against them. If someone cleared the field or the customer was recreated, later invoices have nothing to match on. You can set the field on the customer by hand to fix it going forward.

Commission plans overview

Set what affiliates earn on first payments and renewals.

Product-based commissions

Pay different rates on different Chargebee plans.

Universal integration

Track sign-ups and leads that never reach Chargebee.

Refunds

How refunded sales affect what your affiliates are owed.

Getting started

Managing your program

Engaging affiliates

Gamification

Growth

Program settings

Integrations

Billing and plans

For agencies

For affiliates

What the Chargebee integration can and can’t do

Before you start

Step 1: Install the tracking script on your site

Step 2: Create the custom field in Chargebee

Step 3: Send the referral into Chargebee

Step 4: Add the Referly webhook in Chargebee

Step 5: Connect your API key for plan-level detail

Create the key in Chargebee

Enter them in Referly

Step 6: Test the whole flow

What happens automatically once you’re set up

Refunds

Disconnecting

Troubleshooting

Commission plans overview

Product-based commissions

Universal integration

Refunds

​What the Chargebee integration can and can’t do

​Before you start

​Step 1: Install the tracking script on your site

​Step 2: Create the custom field in Chargebee

​Step 3: Send the referral into Chargebee

​Step 4: Add the Referly webhook in Chargebee

​Step 5: Connect your API key for plan-level detail

​Create the key in Chargebee

​Enter them in Referly

​Step 6: Test the whole flow

​What happens automatically once you’re set up

​Refunds

​Disconnecting

​Troubleshooting

​Related

Commission plans overview

Product-based commissions

Universal integration

Refunds

What the Chargebee integration can and can’t do

Before you start

Step 1: Install the tracking script on your site

Step 2: Create the custom field in Chargebee

Step 3: Send the referral into Chargebee

Step 4: Add the Referly webhook in Chargebee

Step 5: Connect your API key for plan-level detail

Create the key in Chargebee

Enter them in Referly

Step 6: Test the whole flow

What happens automatically once you’re set up

Refunds

Disconnecting

Troubleshooting

Related