Step 1 — Gather context
If references/learnings.md exists, read it first for accumulated platform knowledge.
-
What are you trying to do?
- A) Build an API integration — create customers/subscriptions, manage invoices, pull data
- B) Set up + consume webhooks to provision access / drive dunning
- C) Migrate Product Catalog 1.0 → 2.0 (plans/addons → items/item-prices)
- D) Configure dunning / smart retries for failed payments
- E) Understand proration on mid-cycle upgrades/downgrades
- F) Set up the Chargebee MCP server / AgentKit for Claude or Cursor
- G) Decide Chargebee vs another billing tool — that's a selection question (route in Step 2)
-
Which Product Catalog? PC 2.0 uses items + item prices (current default for new sites); PC 1.0 uses plans + addons (legacy). The API endpoints differ — confirm which your site is on before coding.
-
Test or live? Use your test site + test API keys first. The Time Machine (test clocks) only exists on test sites.
Skip-ahead rule: if the user's prompt already provides enough context, skip to Step 2.
Step 2 — Route or answer directly
| If the question is about... | Route to... |
|---|---|
| Choosing a recurring-billing engine across tools (Chargebee vs Recurly vs Maxio vs Stripe Billing) | /sales-subscription-billing {question} |
| Merchant-of-Record vs self-managed tax, who remits VAT/GST | /sales-merchant-of-record {question} |
| Checkout-conversion optimization (order bumps, upsells, cart recovery) | /sales-checkout {question} |
| Subscription retention / win-back / churn strategy beyond billing | /sales-customer-success {question} |
| Connecting Chargebee to a CRM/other tools generically (iPaaS) | /sales-integration {question} |
When routing, give the exact command, e.g. "This is a billing-engine selection question — run: /sales-subscription-billing Chargebee vs Recurly for usage-based SaaS".
Step 3 — Chargebee platform reference
Read references/platform-guide.md for the full reference — the module map (what's API vs webhook vs UI-only), the pricing/limits model (free Starter cumulative $250K cap, Performance, overages), the data model with JSON shapes, and quick-start recipes (create customer+subscription; provision/revoke access on a webhook; sync subscriptions/MRR to a warehouse).
Read references/chargebee-api-reference.md for the integration surface — base URL https://{site}.chargebee.com/api/v2/, HTTP Basic auth (API key as username, empty password), form-encoded requests + JSON envelope responses, offset/limit pagination, the chargebee-idempotency-key header, the events/webhooks model (no HMAC — basic-auth/URL-key + IP allowlist), error shape, rate limits, and the MCP servers / AgentKit.
Answer using only the relevant section. Don't dump the full reference.
Step 4 — Actionable guidance
- Auth is HTTP Basic, key-as-username.
curl https://{site}.chargebee.com/api/v2/customers -u {api_key}:— the API key is the username and the password is empty (note the trailing colon). Keys are environment-specific (test vs live) and come in full-access/publishable/read-only types — use the least-privileged key. - Webhooks have NO HMAC signature. Unlike Paddle/Stripe, you can't verify an HMAC. Protect the URL with basic auth and/or a secret URL key, restrict to Chargebee's published IP ranges, then dedupe on the event
idand order byresource_version(events are async, out-of-order, and redelivered for ~2–3 days). - Know your Product Catalog version. PC 2.0 calls operate on items/item_prices; PC 1.0 on plans/addons. A PC 1.0 tutorial/SDK call won't work on a PC 2.0 site. Migration is one-way and not automatic.
- Make writes idempotent. Send a UUID in
chargebee-idempotency-key(30-minute window) so retried create/charge calls don't double-bill. - Proration is automatic, but credit type varies. Mid-cycle changes issue Adjustment credits (if the current invoice is unpaid) or Refundable credits (if paid). Verify the invoice state before assuming a refund.
- Reconcile, don't just listen. Because webhooks can be missed/late, periodically pull current state via the API to repair drift.
If you discover a gotcha, workaround, or tip not covered in references/learnings.md, append it there.
Gotchas
Best-effort from research (2026-06) — review these, especially pricing tiers and the API/webhook specifics, which change.
- Webhooks are NOT HMAC-signed. Chargebee only supports basic-auth or a random URL key + its published IP ranges. Don't expect a
SignatureHMAC like Paddle/Stripe — design verification around basic auth + IP allowlisting. - Webhooks are async, unordered, and redelivered. Order by
resource_version, dedupe on eventid, and keep an idempotency window of 3+ days (final retry lands ~3 days 7 hours out). Not for time-critical flows. - Product Catalog 1.0 vs 2.0 is a hard split. Plans/addons (PC1) vs items/item-prices (PC2) have different API calls. Migration is one-way (no rollback) and existing plans aren't auto-converted.
- The free Starter tier is cumulative, not monthly. It covers total billing since signup up to ~$250K; past that Chargebee charges 0.75% on all billing with no grace wall — model this before relying on "free."
- Smart Retry vs custom retry differ. Smart Retry auto-schedules up to ~12 attempts by decline type (hard vs soft); custom retry caps at ~5 attempts you schedule by day.
- Amounts are in the smallest currency unit (cents).
4900= $49.00. - UI is often called complex and support slow in reviews — the API/webhooks are the praised, reliable surface, so prefer automating over clicking.
Related skills
/sales-subscription-billing— Choosing & operating a recurring-billing engine across tools (Chargebee vs Recurly vs Maxio vs Zuora vs Stripe Billing vs Orb/Lago; billing models, dunning, proration, RevRec)/sales-merchant-of-record— MoR vs self-managed tax selection (Chargebee is NOT a MoR — you stay seller of record and own tax)/sales-checkout— Checkout-conversion optimization across tools (order bumps, upsells, cart recovery)/sales-customer-success— Subscription retention / churn / health-score strategy beyond billing mechanics/sales-do— Not sure which skill to use? The router matches any sales objective to the right skill. Install:npx skills add sales-skills/sales --skill sales-do -a claude-code
Examples
Example 1: Provision access when a customer subscribes (developer/automation)
User says: "How do I grant my app's Pro plan when someone subscribes through Chargebee, and revoke it when payment fails?"
Skill does: Walks Recipe 2 — configure a webhook (protect the URL with basic auth / secret key, allowlist Chargebee's IPs since there's no HMAC), then on subscription_activated/subscription_created grant access by customer_id, and on payment_failed/subscription_cancelled start dunning or revoke. Stresses ordering by resource_version, deduping on event id (redelivery), and reconciling via GET /subscriptions for missed events.
Result: Reliable, replay-safe entitlement provisioning despite unsigned, unordered webhooks.
Example 2: My subscription create call double-billed a customer
User says: "My retry logic created two subscriptions and charged twice. How do I stop that?"
Skill does: Identifies the missing idempotency key — shows adding the chargebee-idempotency-key header (a UUID) so retries within the 30-minute window are treated as the same request, and notes the smallest-unit (cents) amount format. Points to safe-retry handling on 429/5xx.
Result: Idempotent writes; no duplicate subscriptions or charges.
Example 3: Moving from Product Catalog 1.0 to 2.0
User says: "We're on plans/addons and want to switch to items. Will my API integration still work?"
Skill does: Explains PC1 (plans/addons) → PC2 (items + item prices + price points + product families): the API endpoints change, multiple currency/frequency variants collapse into one item with price points, migration is one-way with no rollback and existing plans aren't auto-migrated. Recommends testing the PC2 calls on a test site first and flags the full billing-engine view in /sales-subscription-billing.
Result: A clear migration expectation and an updated integration plan.
Troubleshooting
My webhook endpoint can't verify requests are really from Chargebee
Symptom: You're looking for an HMAC signature header to validate webhooks and can't find one.
Cause: Chargebee does not sign webhooks with HMAC (unlike Paddle/Stripe). It only supports basic-auth on the URL or a random key embedded in the URL.
Solution: Enable "Protect webhook URL with basic authentication," and/or add a secret path/query key, and restrict inbound traffic to Chargebee's published IP ranges. Then dedupe on the event id and reconcile via the API. Treat the basic-auth credentials + IP allowlist as your authenticity check.
A mid-cycle upgrade gave the customer a credit I didn't expect
Symptom: Upgrading/downgrading produced a proration credit that behaved differently than last time.
Cause: Chargebee proration depends on the current invoice state — an unpaid invoice gets an Adjustment credit applied to it; a paid invoice gets a Refundable credit applied to future invoices.
Solution: Check the current term's invoice status before changing the subscription. Use the prorate/invoice_immediately/end_of_term options to control timing, and preview with the estimate API before committing.
Events show up out of order or twice in my database
Symptom: A subscription_changed arrives before subscription_created, or you process the same event twice.
Cause: Webhook delivery order isn't guaranteed and Chargebee retries (redelivers) failed/timed-out calls for ~2–3 days.
Solution: Make handlers idempotent on the event id, compare the resource_version (process only if newer than stored), keep the idempotency window ≥3 days, and run a periodic reconciliation pulling current state from the API.