sales-skills/sales-chargebee

Chargebee Platform Help

Step 1 — Gather context

If references/learnings.md exists, read it first for accumulated platform knowledge.

1. 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)

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.

3. 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 id and order by resource_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.

1. Webhooks are NOT HMAC-signed. Chargebee only supports basic-auth or a random URL key + its published IP ranges. Don't expect a Signature HMAC like Paddle/Stripe — design verification around basic auth + IP allowlisting.
2. Webhooks are async, unordered, and redelivered. Order by resource_version, dedupe on event id, and keep an idempotency window of 3+ days (final retry lands ~3 days 7 hours out). Not for time-critical flows.
3. 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.
4. 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."
5. 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.
6. Amounts are in the smallest currency unit (cents). 4900 = $49.00.
7. 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.