Migrate from Chargebee

Mapping Chargebee to Recurso

The Import wizard in Settings → Import data

Moving off Chargebee? Recurso covers the same billing surface — plans, subscriptions, invoices, dunning, usage, entitlements — with a self-hosted architecture and native India compliance. This guide maps Chargebee’s object model to Recurso, calls out what’s different, and walks through the cmd/import tool to migrate your live subscriber base idempotently and without double-billing anyone mid-cycle.

Concept Mapping

Chargebee	Recurso	Notes
Item (Plan) + Item Price	Plan (with one or more `prices`)	Chargebee’s Item / Item Price pair becomes a single Recurso Plan carrying per-currency prices.
Customer	Customer	Same idea. Add `gstin` / billing address for tax.
Subscription	Subscription	Connects a customer to a plan; carries `current_period_start` / `current_period_end`.
Invoice	Invoice	Auto-generated at period end; GST/tax computed automatically.
Metered / usage-based Item Price	Usage events (`POST /v1/usage/events`)	Report against a subscription `dimension`. See Usage-Based Billing.
Entitlements / Feature	Entitlements	Native boolean + limit grants per plan. See Entitlements.
Webhooks	Webhooks (signed with `X-Recurso-Signature`)	HMAC-SHA256 over the raw body.
Coupons	Coupons	See Coupons.
Credit Notes	Credit Notes	See Credit Notes.
Quotes	Quotes	Full quote lifecycle: create, send, accept, convert. See Quotes.
Hosted Pages / Checkout	Hosted checkout	Send customers to `https://api.recurso.dev/checkout/{invoice_id}`; the gateway is chosen from the invoice currency.

Chargebee’s Item Family / Item / Item Price hierarchy flattens in Recurso: one Plan holds the recurring price(s) directly. A metered add-on maps to a usage dimension you report events against.

What’s Different

Self-hosted — Recurso runs on your infrastructure (Go + PostgreSQL, optionally TigerBeetle). Your billing data lives in your own database.
No percentage fee — there’s no per-transaction billing fee taken by Recurso. You pay gateway fees and your own hosting.
Built-in double-entry ledger — every billing event posts to a ledger with a first-class reconciliation report.
India compliance is native — GST (CGST/SGST/IGST), e-invoicing via the IRP, and RBI e-mandates are first-class. See GST Invoicing.
Your gateway, your relationship — Recurso orchestrates billing but charges through your own Razorpay or Stripe account.

Migrating Your Subscribers

The cmd/import tool loads plans, customers, and subscriptions directly into the database without generating invoices or calling payment gateways. Each imported subscription keeps its original billing period, so Recurso only issues the next invoice at current_period_end — no mid-cycle double-billing.

Step 1: Export from Chargebee

Export your active subscriptions with their customers and item prices (via the Chargebee export or API). Keep each Chargebee subscription ID — it becomes the external_id that makes the import idempotent.

Step 2: Build the import file

Recurso reads a single JSON file (or three CSVs). Amounts are in minor units (paise/cents). This example shows an Indian B2B subscriber with GSTIN and place of supply carried across:

data.json

{
  "plans": [
    {
      "code": "BASIC-INR",
      "name": "Basic Plan",
      "amount": 50000,
      "currency": "INR",
      "interval_unit": "month",
      "interval_count": 1
    }
  ],
  "customers": [
    {
      "email": "ramesh.gupta@example.in",
      "name": "Ramesh Gupta",
      "country": "IN",
      "state": "MH",
      "zip": "400001",
      "gstin": "27DQBPS8356J1Z1",
      "place_of_supply": "MH"
    }
  ],
  "subscriptions": [
    {
      "external_id": "sub_chargebee_9QrSt",
      "customer_email": "ramesh.gupta@example.in",
      "plan_code": "BASIC-INR",
      "status": "active",
      "current_period_start": "2026-07-01T00:00:00Z",
      "current_period_end": "2026-08-01T00:00:00Z"
    }
  ]
}

The importer matches plans by code, customers by email, and subscriptions by external_id (your Chargebee subscription ID). Set external_id to the Chargebee ID so re-running the import skips anything already migrated.

Field reference:

Object	Required fields	Optional
plan	`code`, `name`, `amount`, `currency`, `interval_unit`	`interval_count` (default 1)
customer	`email`, `name`	`phone`, `country`, `state`, `city`, `line1`, `zip`, `tax_id`, `gstin`, `place_of_supply`
subscription	`external_id`, `customer_email`, `plan_code`, `status`, `current_period_start`, `current_period_end`	`payment_terms`

Valid subscription status values: active, trialing, paused, canceled, past_due, unpaid. Timestamps are RFC 3339.

Carrying gstin and place_of_supply over means the first Recurso invoice is already GST-correct — CGST/SGST vs IGST is decided from the customer’s state against your seller state code.

Step 3: Dry-run first

The dry run validates the whole file and reports what would happen without writing anything — surfacing every problem in one pass.

DATABASE_URL=postgres://user:pass@localhost:5432/recurso \
  go run ./cmd/import \
  -tenant <your-tenant-uuid> \
  -input data.json \
  -dry-run

Find your tenant UUID in the dashboard under Settings, or in the POST /auth/register response. The tenant must already exist.

Step 4: Import for real

DATABASE_URL=postgres://user:pass@localhost:5432/recurso \
  go run ./cmd/import \
  -tenant <your-tenant-uuid> \
  -input data.json

The tool prints N created, N skipped (already exist), N failed. Because it’s idempotent, re-running after fixing a failure only creates what’s still missing.

No invoices are generated by the import. The renewal worker issues each subscription’s next invoice at its current_period_end. Configure your gateway credentials (see Payment Gateways) before that first renewal.

Step 5: Prove it — the Compare gate

Before pointing billing at Recurso, re-run your export through the Compare gate. It diffs the export against your live Recurso data — read-only — and reports, per record:

Coverage — every importable source record exists in Recurso
Fidelity — plan amount, currency, and interval match exactly; customer identity intact
Continuity — billing resumes exactly where Chargebee stops: a subscription whose period end drifted more than an hour is flagged as the double-billing / billing-gap risk it is

curl -s https://api.recurso.dev/v1/import/chargebee/compare \
  -H "Authorization: Bearer $RECURSO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @data.json | jq '{ready, issues}'

"ready": true means zero issues — safe to cut over. The same gate runs from the dashboard’s Import wizard (“Before you cut over: run the Compare gate”).

After Migrating

Point webhooks at Recurso

Configure tax

Set GST (India) or TaxJar (US) so the first Recurso invoice is compliant. See India GST setup.

Reconcile

After the first renewal cycle, run GET /v1/finance/reconciliation to confirm the ledger, invoices, and gateway agree.

Get Started

Migrate to Recurso

Core Concepts

Usage & Monetization

Money & Books

Tax & Compliance

Recover & Retain

Customer Portal

Platform & Integrations

Deploy & Operate

Reference

Mapping Chargebee to Recurso

Concept Mapping

What’s Different

Migrating Your Subscribers

Step 1: Export from Chargebee

Step 2: Build the import file

Step 3: Dry-run first

Step 4: Import for real

Step 5: Prove it — the Compare gate

After Migrating

Next Steps

Going to Production

End-to-End Flow

​Mapping Chargebee to Recurso

​Concept Mapping

​What’s Different

​Migrating Your Subscribers

​Step 1: Export from Chargebee

​Step 2: Build the import file

​Step 3: Dry-run first

​Step 4: Import for real

​Step 5: Prove it — the Compare gate

​After Migrating

​Next Steps

Going to Production

End-to-End Flow

Mapping Chargebee to Recurso

Concept Mapping

What’s Different

Migrating Your Subscribers

Step 1: Export from Chargebee

Step 2: Build the import file

Step 3: Dry-run first

Step 4: Import for real

Step 5: Prove it — the Compare gate

After Migrating

Next Steps