Chargebee platform help — subscription billing & revenue-management orchestration on top of your own payment gateway; you stay seller of record (NOT a Merchant of Record). REST API (`{site}.chargebee.com/api/v2`, HTTP Basic auth: API key as username, empty password), webhooks, three MCP servers + AgentKit, 40+ gateways, smart dunning, proration, revenue recognition (ASC 606), Product Catalog 1.0 vs 2.0. Use when building a Chargebee API or webhook integration, Chargebee webhooks have no HMAC signature to verify, handling out-of-order or duplicate webhook events, migrating Product Catalog 1.0 to 2.0, configuring smart dunning/retries for failed payments, confused by prorated credits on a mid-cycle upgrade, syncing subscriptions or MRR to a CRM or warehouse, or setting up the Chargebee MCP server in Claude or Cursor. Do NOT use for choosing a recurring-billing engine across tools (use /sales-subscription-billing) or Merchant-of-Record vs self-managed tax selection (use /sales-merchant-of-record).
Instrucciones de origen · Vista previa de solo lectura
name
sales-chargebee
description
Chargebee platform help — subscription billing & revenue-management orchestration on top of your own payment gateway; you stay seller of record (NOT a Merchant of Record). REST API (`{site}.chargebee.com/api/v2`, HTTP Basic auth: API key as username, empty password), webhooks, three MCP servers + AgentKit, 40+ gateways, smart dunning, proration, revenue recognition (ASC 606), Product Catalog 1.0 vs 2.0. Use when building a Chargebee API or webhook integration, Chargebee webhooks have no HMAC signature to verify, handling out-of-order or duplicate webhook events, migrating Product Catalog 1.0 to 2.0, configuring smart dunning/retries for failed payments, confused by prorated credits on a mid-cycle upgrade, syncing subscriptions or MRR to a CRM or warehouse, or setting up the Chargebee MCP server in Claude or Cursor. Do NOT use for choosing a recurring-billing engine across tools (use /sales-subscription-billing) or Merchant-of-Record vs self-managed tax selection (use /sales-merchant-of-record).
argument-hint
[describe what you need help with in Chargebee]
license
MIT
version
1.0.0
tags
["sales","payments","billing","platform"]
github
https://github.com/chargebee
Chargebee Platform Help
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
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.
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.
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.
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-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.
