Chargebee Integration
Connect Chargebee to automatically track subscription payments and attribute them to your affiliates. AFFY handles initial sales, renewals, and refunds — all via Chargebee's webhook system.
- Installed the AFFY tracking script on your website — customer clicks must be recorded before they reach Chargebee checkout
- Created at least one commission flow — AFFY needs a flow to calculate commissions when Chargebee events arrive
How it works
An affiliate shares their tracking link
A visitor clicks the link — AFFY records the click and sets a tracking cookie
The visitor subscribes or makes a payment in Chargebee
Chargebee sends a webhook event to AFFY with payment details
AFFY matches the customer to the affiliate click and creates a commission
Setting up the integration
Copy your webhook URL from AFFY
Add the webhook in Chargebee
- URL: paste the webhook URL you copied from AFFY
- Basic Auth: enable “Protect webhook URL with basic authentication” and choose a username and password (you decide these — write them down)
- Events: enable
payment_succeeded,subscription_created,subscription_renewed,subscription_cancelled,payment_refunded
Enter the same credentials in AFFY
Create the cf_click_id custom field in Chargebee
- Go to Configure Chargebee → Checkout & Self-Serve Portal, click the Fields tab, then scroll to Custom fields for subscription and click Add/Manage Custom Fields.
- At the top of the custom fields panel, select the Subscriptions tab, then add a new field:
- Type: Single line text
- Label: Affiliate Click ID
- API Name:
cf_click_id(must be exactly this)
- Return to Configure Chargebee → Checkout & Self-Serve Portal → Fields. Find the Affiliate Click ID field under Custom fields for subscription and click Edit.
- Set In checkout to Use as hidden parameter and In portal to Hide, then click Apply.
- Click Publish to save all changes.
The “hidden parameter” setting is critical — it tells Chargebee to accept the value via API without showing it to customers. Without this, the click ID is silently dropped and AFFY falls back to email-based attribution.
Passing the affiliate click ID at checkout
To reliably attribute Chargebee payments to affiliates, the AFFY click ID must be stored on the Chargebee subscription via the cf_click_id custom field. Due to a Chargebee v4 checkout limitation, passing this value as a URL parameter is silently dropped — the only reliable method is to create the checkout session via the AFFY API.
subscription[cf_click_id]directly in the hosted page URL does not work in Chargebee's v4 checkout — the value is silently ignored. This was confirmed by Chargebee support. Use the AFFY API approach below instead.Recommended — create checkout via AFFY API
Call the AFFY checkout endpoint from your frontend. AFFY creates the Chargebee hosted page server-side with cf_click_id correctly embedded, and returns the checkout URL.
// Get the AFFY click ID from the tracking script
const clickId = typeof AffyJS !== 'undefined' && AffyJS.getReferralId
? AffyJS.getReferralId()
: null;
// Replace YOUR_PUBLIC_ID with your AFFY client public ID
// (found in Settings → Integration → Chargebee → Webhook URL)
const response = await fetch(
'https://affy.pro/api/v1/public/chargebee/YOUR_PUBLIC_ID/create-checkout',
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
planId: 'your-chargebee-item-price-id',
email: customerEmail,
clickId: clickId
})
}
);
const { checkoutUrl } = await response.json();
window.location.href = checkoutUrl;Checkout URL format
Chargebee has two catalog models. Use the format that matches your account:
| Catalog model | Checkout URL parameter |
|---|---|
| Plans model (older accounts) | subscription[plan_id]=your-plan-id |
| Items model (newer accounts) | subscription_items[item_price_id][0]=your-item-price-id |
Not sure which model you use? In your Chargebee dashboard, go to Product Catalog— if you see “Item Families” you're on the Items model. If you see “Plans” directly, you're on the Plans model.
What gets tracked automatically
| Chargebee Event | What AFFY does |
|---|---|
| payment_succeeded | Creates a commission for the referred affiliate |
| subscription_created | Records the new subscription; commission created on first payment |
| subscription_renewed | Creates a commission for the renewal payment |
| subscription_cancelled | No commission action — cancellation is logged for reporting |
| payment_refunded | Marks the related commission as Refunded |
How refunds are handled
When a refund is issued in Chargebee, AFFY automatically marks the related commission as Refunded and removes it from the payout queue.
Full refund
The entire commission is reversed.
Partial refund
The commission is reduced proportionally to the refunded amount.
Refund after payout
Commission is still marked Refunded — you'll need to reconcile with the affiliate manually.
Attribution reliability
AFFY uses a three-step attribution chain to match Chargebee payments to affiliates. Each step is tried in order — if one fails, the next is attempted:
| Method | How it works | Reliability |
|---|---|---|
| Click ID (cf_click_id) | Affiliate click ID passed at checkout via subscription[cf_click_id] URL param — stored on the Chargebee subscription | Highest — works even if customer changes email |
| Affiliate Ref | Affiliate reference code passed via subscription metadata | High — works if metadata is populated at checkout |
| Customer email | Email from the Chargebee webhook is matched against leads already recorded by the AFFY tracking script | Medium — fails if customer uses a different email at checkout than during tracking |