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).
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
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.
