> ## Documentation Index
> Fetch the complete documentation index at: https://docs.partnero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chargebee integration

> Track purchases made through Chargebee and attribute them to the partner who referred the customer

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:

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

<Note>
  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.
</Note>

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

1. In Partnero, go to **Integration** and scroll to **Apps & Integrations**.
2. Click **Authorize** next to Chargebee.
3. Enter your **API key**, from Chargebee under **Settings** → **API Keys**.
4. Enter your **site name** — the subdomain of your Chargebee URL, so `your-site-name` from
   `your-site-name.chargebee.com`.
5. 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.

<Warning>
  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.
</Warning>

## 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:

1. Open the program and go to **Integration**.
2. 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:

```html theme={"system"}
<!-- 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

<Tabs>
  <Tab title="Hosted Pages">
    Use this if customers check out through
    [Chargebee Hosted Pages](https://www.chargebee.com/docs/2.0/hosted_pages.html).

    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.

    ```html theme={"system"}
    <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]`.
  </Tab>

  <Tab title="Your own backend">
    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:

    ```javascript theme={"system"}
    chargebee.customer.create({
      email: customerEmail,
      cf_partnero_partner: partnerKeyFromCookie
    });
    ```

    Use `cf_partnero_referral` instead in a refer-a-friend program.
  </Tab>
</Tabs>

<Note>
  Statistics only appear in Partnero after a referred customer completes their first purchase.
</Note>

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Commissions" icon="percent" href="/knowledge-base/commissions-rewards/guide-to-commission-set-up">
    Set up recurring commissions
  </Card>

  <Card title="Transactions API" icon="code" href="/api-reference/transactions/create">
    Record transactions yourself
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.