Install on Chargebee

Chargebee is subscription billing on top of your own payment gateway, and Rekomi supports it natively. You paste your site name and a Read-Only API key into Rekomi, then add one webhook in Chargebee pointed at your per-workspace Rekomi URL. From that point on, payments, subscription renewals, and refunds flow into Rekomi with no relay code to write or maintain. Still evaluating? See Why Rekomi for Chargebee →.

One thing to know up front: Chargebee webhooks are unsigned (Chargebee does not support webhook signing), so Rekomi authenticates every delivery with Basic Authentication credentials that Rekomi generates for you. The password is shown exactly once; you paste it into Chargebee's webhook settings alongside the URL.

What you need

• Your site name. The subdomain of your Chargebee URL: acme from acme.chargebee.com. Test sites end in -test (for example acme-test) and have their own keys and webhooks.
• A Read-Only API key. In Chargebee, open Settings > Configure Chargebee > API Keys and Webhooks > API Keys and click + Add API Key, choosing the Read-Only type with access to all resources (a restricted read-only key also works as long as it can read customers). Rekomi uses it to validate the connection and run periodic health checks; it is never used to change anything in your site.

Connect in Rekomi

Step 1. Go to /dashboard/setup/chargebee. The page shows your per-workspace webhook URL and the Basic Authentication credentials (username rekomi plus a generated password).

Step 2. Copy the webhook URL, the username, and the password. The password is shown once. It is stored encrypted and cannot be displayed again; if you lose it, the setup page has an explicit Regenerate button that mints a new one (the old one stops working immediately, so you would update the Chargebee webhook with the new value).

Step 3. Enter your site name and the Read-Only API key and click Connect Chargebee. Rekomi validates the pair live against your site before accepting it.

Add the webhook in Chargebee

In Chargebee, open Settings > Configure Chargebee > API Keys and Webhooks > Webhooks and click Add Webhook:

1. Paste the webhook URL from the Rekomi setup page.
2. Turn on "Protect webhook URL with basic authentication" and enter the username and password from the setup page.
3. Set the API version to V2. Rekomi processes V2 payloads only; V1 deliveries are rejected so Chargebee retries them after you fix the version.
4. Check "Exclude card information from the webhook call". Rekomi never needs card data.
5. Select these events:

• payment_succeeded
• payment_refunded
• payment_failed
• subscription_created
• subscription_activated
• subscription_cancelled
• subscription_reactivated
• subscription_changed
• subscription_deleted
• credit_note_created

An "All Events" configuration also works (Rekomi acknowledges and ignores event types it does not use), but the explicit list keeps the traffic lean.

Attribution: carry rekomi_ref on the subscription (required)

Chargebee hosts the checkout on its own domain, so the affiliate referral has to travel from the visitor's browser into the subscription record. This step is required: without it, payments arrive with no referral and no commission is credited.

First, make sure the Rekomi head script is installed on your marketing site so the affiliate cookie is set when a visitor lands on an affiliate link:

<script>
  (function(){
    var s=document.createElement('script');
    s.src='https://js.rekomi.com/v1/rekomi.js';
    s.async=true;
    s.dataset.programId='YOUR_PROGRAM_ID';
    document.head.appendChild(s);
  })();
</script>

The program ID is in Settings > Tracking in the Rekomi dashboard.

Then pick the recipe that matches how you create subscriptions. Rekomi reads the referral from the subscription first, then the customer, in both the meta_data and custom-field renderings.

Creating subscriptions via the API. Set meta_data on subscription create. Read the referral on your frontend with window.Rekomi.getReferral() and send it to your backend with the checkout request:

{
  "meta_data": { "rekomi_ref": "REFERRAL_FROM_YOUR_FRONTEND" }
}

Hosted pages or the drop-in script. Create a Subscription custom field in Chargebee (Settings > Configure Chargebee > Custom Fields) with the API name cf_rekomi_ref, single-line text. Then stamp it onto your checkout URLs:

<script>
  document.addEventListener('DOMContentLoaded', function () {
    var ref = window.Rekomi && window.Rekomi.getReferral();
    if (!ref) return;
    document
      .querySelectorAll('a[href*=".chargebee.com/hosted_pages"]')
      .forEach(function (a) {
        var url = new URL(a.href);
        url.searchParams.set('subscription[cf_rekomi_ref]', ref);
        a.href = url.toString();
      });
  });
</script>

Using Chargebee's drop-in script instead of hosted-page links? Pass the same field on the product object before opening checkout:

var ref = window.Rekomi && window.Rekomi.getReferral();
if (ref) product.data["cf_rekomi_ref"] = ref;

Custom fields created on a test site are published to the live site from the Chargebee custom-fields settings, so create the field once and publish it.

What gets recorded

• Payments are recorded when payment_succeeded fires: the first successful payment of a subscription is the first conversion, and one-time charges without a subscription are one-time conversions.
• Subscription renewals are recorded as recurring conversions on every successful renewal payment, so recurring revenue-share commissions keep accruing automatically. The referral set at signup stays on the subscription, and Rekomi also falls back to the customer's conversion history, so renewals credit the same affiliate.
• Signups (subscription_created) are recorded as zero-value events so the customer is tied to the affiliate before the first payment.
• Refunds, full or partial, claw back the commission automatically and proportionally when payment_refunded fires, in the same audit trail as the original conversion.

Refunds and chargebacks

Refunds you issue in Chargebee (refundable credit notes) arrive as payment_refunded and reverse commission proportionally: a 40% refund claws back 40% of the commission. Chargebacks handled through Chargebee's Chargeback Management feature reach Rekomi the same way, as refunds and credit notes, and claw back too. Disputes resolved outside that feature (directly at your payment gateway) do not generate Chargebee events and are invisible to Rekomi; adjust those manually if they matter for a payout.

Adjustment credit notes that reduce an invoice without moving cash are observed but never recorded as money.

Security

• Every webhook delivery is authenticated with the Basic Authentication credential before anything is processed; deliveries that fail the check are rejected.
• Keep the webhook URL and the credentials private: treat them like a password. Everything travels over HTTPS end to end.
• Chargebee does not support webhook signing, which is why Rekomi mints the credential instead of the more common signing-secret flow you may know from Stripe or Paddle. The credential plus your unguessable per-workspace URL are the authentication.
• Your Read-Only API key and the webhook password are stored encrypted at rest and never returned by the API. Disconnecting wipes both and retires the webhook URL.

Quirks worth knowing

• One conversion source per workspace. Chargebee Connect is mutually exclusive with Stripe Connect, Paddle, Braintree, Shopify, Lemon Squeezy, Polar, Recurly, Gumroad, Creem, Dodo Payments, and the S2S API, so the same sale is never counted twice. Disconnect one before connecting another.
• Chargebee API keys do not expire. If the health check flags the connection as broken, the key was deleted or disabled, the site was renamed, or the webhook credentials were changed; it is never a routine expiry.
• Late deliveries are fine. Chargebee retries failed webhooks for up to two days. Rekomi de-duplicates by event id, so retries and replays never double-count.
• Test sites are separate sites. acme-test has its own API keys and webhooks. Connect the test site to a sandbox workspace to rehearse; connect the live site for production.

Rehearse on your test site

1. In your Chargebee test site, enable the Chargebee Test Gateway and create a Read-Only API key.
2. Create the cf_rekomi_ref Subscription custom field (or plan to use meta_data via the API).
3. Connect the test site in Rekomi and add the webhook in Chargebee with the Basic Authentication credentials, API version V2, and the event list above.
4. Open a hosted checkout with subscription[cf_rekomi_ref] set to an approved affiliate's link slug and pay with a test card. The conversion should appear on the campaign's Activity tab within a minute.
5. Use Chargebee's Time Machine to advance a billing term and confirm the renewal payment credits the same affiliate.
6. Refund the invoice (partially, then fully) and confirm the commission claws back proportionally.

Troubleshooting

"Connection needs attention" banner or reconnect email. The stored API key stopped validating: it was deleted or disabled in Chargebee, or the site name changed. Create a fresh Read-Only key and reconnect on /dashboard/setup/chargebee; your tracking history is preserved.

Events stop arriving but the connection shows healthy. The health check probes the API key, not the webhook. Check the webhook still exists in Chargebee, points at the right URL, uses API version V2, and has Basic Authentication set to the current credentials (a regenerated password must be updated in Chargebee too). Chargebee's webhook dashboard shows the delivery attempts and their responses.

Deliveries rejected as unauthorized. The Basic Authentication credentials in Chargebee do not match. Regenerate the password on the setup page and paste the new value into the Chargebee webhook settings.

Payments arrive but no affiliate is credited. The event reached Rekomi without rekomi_ref on the subscription or customer. Verify the stamping snippet runs on every page that links to checkout, that the head script ran before the buyer clicked through (so window.Rekomi.getReferral() has a value), that the custom field's API name is exactly cf_rekomi_ref (case-sensitive), and that API-created subscriptions set meta_data.rekomi_ref.

V1 events rejected. Rekomi processes API version V2 only. Edit the webhook in Chargebee to V2; Chargebee redelivers the failed events and Rekomi records them.

Related

• S2S tracking API reference
• JavaScript pixel reference
• Refund handling