Chargebee integration

Chargebee needs more hands-on setup than Stripe or Paddle: you create the custom field and the webhook yourself, in your Chargebee dashboard. There are three parts, and all three are required:

Create a custom field in Chargebee to carry the partner key on the customer record.
Authorize Chargebee so Partnero receives the payments your customers make.
Add referral tracking to your site so the partner key reaches Chargebee in the first place.

Your program’s own integration guide, with your program ID and webhook credentials already filled in, lives in the app under Integration → Guides → Chargebee. It is the source of truth for the values below.

Step 1: Create the custom field in Chargebee

Do this before authorizing — Partnero checks that the field exists and will refuse to connect without it. In Chargebee, go to Settings → Configure Chargebee → Custom Fields and add a Customer custom field of type Single Line Text:

Program type	API name	Label
Affiliate	`cf_partnero_partner`	Partner Code
Refer-a-friend	`cf_partnero_referral`	Referral Code

The API name must match exactly. Copy it from the in-app instructions rather than retyping it.

Step 2: Authorize Chargebee

In Partnero, go to Integration and scroll to Apps & Integrations.
Click Authorize next to Chargebee.
Enter your API key, from Chargebee under Settings → API Keys.
Enter your site name — the subdomain of your Chargebee URL, so your-site-name from your-site-name.chargebee.com.
In Chargebee, go to Settings → Configure Chargebee → API Keys and Webhooks and add a webhook using the endpoint, credentials and event list shown in the Partnero integration window.

Unlike Stripe and Paddle, Chargebee webhooks are not created for you. If you skip the webhook, Partnero never hears about the payments and no commission is generated.

Step 3: Add referral tracking to your site

This is what tells Partnero which partner referred a customer. Without it, Chargebee sends Partnero payments it cannot attribute to anyone.

Install the tracking script

This snippet identifies visitors arriving through a partner’s referral link and stores the partner key in a first-party cookie. Copy your own snippet from the app — don’t retype the one below. It is generated per program and already contains your program ID:

Open the program and go to Integration.
Copy the PartneroJS snippet shown there. It also appears inside every guide on the Guides tab.

Paste it before the closing </head> tag on every page a referred visitor might land on — ideally site-wide. For reference, the snippet looks like this, where YOUR_PROGRAM_ID is filled in for you:

<!-- PartneroJS -->
<script>
(function(p,t,n,e,r,o){p['__partnerObject']=r;function f(){var c={a:arguments,q:[]};var r=this.push(c);return "number"!=typeof r?r:f.bind(c.q);}
f.q=f.q||[];p[r]=p[r]||f.bind(f.q);p[r].q=p[r].q||f.q;o=t.createElement(n);var _=t.getElementsByTagName(n)[0];o.async=1;
o.src=e+'?v'+(~~(new Date().getTime()/1e6));_.parentNode.insertBefore(o,_);})(window,document,'script','https://app.partnero.com/js/universal.js','po');
po('program', 'YOUR_PROGRAM_ID', 'load');
</script>
<!-- End PartneroJS -->

Pass the partner key into Chargebee

Hosted Pages
Your own backend

Use this if customers check out through Chargebee Hosted Pages.This script finds links to your Chargebee hosted checkout and appends the partner key as the custom field, so Chargebee stores it on the customer it creates. Place it on every page containing hosted checkout links, at the bottom of the page directly above the closing </body> tag.

<script>
(function () {
    'use strict';

    var COOKIE = "partnero_partner";
    var FIELD = "customer[cf_partnero_partner]";

    function getCookie(name) {
        var match = document.cookie.match('(^|;)\\s*' + name + '=([^;]+)');
        if (!match) return null;
        try { return decodeURIComponent(match[2]); } catch (e) { return match[2]; }
    }

    var referralCode = getCookie(COOKIE);

    function applyReferralCode(link) {
        if (!referralCode) return;
        try {
            var url = new URL(link.href, location.origin);
            if (url.hostname.includes("chargebee.com") && url.pathname.includes("/hosted_pages/")) {
                url.searchParams.set(FIELD, referralCode);
                link.href = url.toString();
            }
        } catch (e) {}
    }

    function updateAllLinks() {
        document
            .querySelectorAll('a[href*="chargebee.com/hosted_pages/"]')
            .forEach(applyReferralCode);
    }

    document.addEventListener("DOMContentLoaded", updateAllLinks);

    document.addEventListener("click", function (event) {
        var link = event.target.closest("a[href*='chargebee.com/hosted_pages/']");
        if (link) {
            applyReferralCode(link);
        }
    }, true);
})();
</script>

In a refer-a-friend program change COOKIE to partnero_referral and FIELD to customer[cf_partnero_referral].

Use this if you create Chargebee customers or subscriptions server-side. Read the cookie from the incoming request and set the custom field on the customer:

chargebee.customer.create({
  email: customerEmail,
  cf_partnero_partner: partnerKeyFromCookie
});

Use cf_partnero_referral instead in a refer-a-friend program.

Statistics only appear in Partnero after a referred customer completes their first purchase.

What gets tracked

Once all three steps are done, Partnero records successful payments and transactions made by your referred customers, and reverses the commission automatically when a payment is refunded or a transaction is deleted.

Troubleshooting

Partnero will not let me authorize

The custom field is missing or its API name does not match. Partnero validates cf_partnero_partner (or cf_partnero_referral for refer-a-friend) before connecting. Check it is a Customer field, not a subscription or invoice field.

Purchases are not appearing in Partnero

Check the webhook. Chargebee webhooks are created by you, not by Partnero, so confirm the endpoint and credentials in Chargebee match the ones in the Partnero integration window and that the listed events are selected. Chargebee’s own webhook logs will show whether delivery is failing.

The customer exists in Chargebee but the sale is attributed to nobody

The custom field is empty on that customer. Open the customer in Chargebee and check cf_partnero_partner holds a partner key. If it is blank, the tracking script did not reach the hosted page link — usually because the script sits above the link markup, or the visitor had no partnero_partner cookie.

Hosted page links are not being rewritten

The script only touches links whose host contains chargebee.com and whose path contains /hosted_pages/. If you serve checkout from a custom domain, set the custom field server-side instead.

Overview

AI tools

Getting started

Billing integrations

Coupon tracking

E-commerce

Website builders & CMS

Courses & communities

Forms & scheduling

CRM & automation

Payouts

Email & marketing

Webhooks

Chargebee integration

Step 1: Create the custom field in Chargebee

Step 2: Authorize Chargebee

Step 3: Add referral tracking to your site

Install the tracking script

Pass the partner key into Chargebee

What gets tracked

Troubleshooting

Next steps

Commissions

Transactions API

​Step 1: Create the custom field in Chargebee

​Step 2: Authorize Chargebee

​Step 3: Add referral tracking to your site

​Install the tracking script

​Pass the partner key into Chargebee

​What gets tracked

​Troubleshooting

​Next steps

Commissions

Transactions API

Step 1: Create the custom field in Chargebee

Step 2: Authorize Chargebee

Step 3: Add referral tracking to your site

Install the tracking script

Pass the partner key into Chargebee

What gets tracked

Troubleshooting

Next steps