Migrate from Stripe Billing

What This Guide Covers

Coming from Stripe Billing? The mental model is close enough that most of your integration maps one-to-one. This guide covers three things: how Stripe objects translate to Recurso, what’s genuinely different, and how to bring your live subscribers over with the cmd/import tool — idempotently, with a dry run, and without double-billing anyone mid-cycle.

Concept Mapping

Stripe Billing	Recurso	Notes
Product + Price	Plan (with one or more `prices`)	Recurso folds Stripe’s Product/Price split into a single Plan carrying per-currency prices.
Customer	Customer	Same idea. Add `gstin` / billing address for tax.
Subscription	Subscription	Connects a customer to a plan; has `current_period_start` / `current_period_end`.
Invoice	Invoice	Auto-generated at period end; GST/tax computed automatically.
Metered usage / Usage Records	Usage events (`POST /v1/usage/events`)	Report against a subscription `dimension`. See Usage-Based Billing.
Entitlements / feature flags	Entitlements	Native boolean + limit grants per plan. See Entitlements.
Webhooks (signed with `Stripe-Signature`)	Webhooks (signed with `X-Recurso-Signature`)	HMAC-SHA256 over the raw body; verify the same way.
Coupons / Promotion Codes	Coupons	See Coupons.
Payment Intents / checkout	Hosted checkout	Send customers to `https://api.recurso.dev/checkout/{invoice_id}`; the gateway is chosen from the invoice currency.

Because a Recurso Plan holds multiple currency prices, a Stripe Product with separate USD and INR Prices collapses into one Recurso Plan with two entries in its prices array.

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 (Razorpay/Stripe) 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, not add-ons. See GST Invoicing.
Gateways stay yours — Recurso orchestrates billing but charges through your own Razorpay or Stripe account, so you keep your processor relationship.

Migrating Your Subscribers

The Import wizard in Settings → Import data

The cmd/import tool in the main repository 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 — migrated customers are never double-billed mid-cycle.

Step 1: Export from Stripe

Pull your active subscriptions, their customers, and the products/prices they’re on (via the Stripe Dashboard export or the Stripe API). You’ll shape this into Recurso’s import format next. Keep each subscription’s Stripe 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). Match Stripe’s price to a plan code, and use each customer’s email as the join key.

data.json

{
  "plans": [
    {
      "code": "PRO-USD",
      "name": "Pro Plan",
      "amount": 2900,
      "currency": "USD",
      "interval_unit": "month",
      "interval_count": 1
    }
  ],
  "customers": [
    {
      "email": "jane@example.com",
      "name": "Jane User",
      "country": "US",
      "state": "CA",
      "zip": "90210"
    }
  ],
  "subscriptions": [
    {
      "external_id": "sub_stripe_1KxYz",
      "customer_email": "jane@example.com",
      "plan_code": "PRO-USD",
      "status": "active",
      "current_period_start": "2026-06-15T00:00:00Z",
      "current_period_end": "2026-07-15T00:00:00Z"
    }
  ]
}

The importer matches plans by code, customers by email, and subscriptions by external_id (your Stripe subscription ID). Set external_id to the Stripe 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 (e.g. 2026-06-15T00:00:00Z).

Prefer spreadsheets? Pass -plans-csv, -customers-csv, and -subscriptions-csv instead of a single JSON file — the columns match the field names above.

Step 3: Dry-run first

The dry run validates the whole file and reports exactly what would happen — writing nothing. It reports every problem in one pass, so you fix your export once instead of one error at a time.

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 response from POST /auth/register. The target 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 a summary — N created, N skipped (already exist), N failed — and, because it’s idempotent, a partial failure is safe to fix and re-run: what already imported is skipped.

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

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 Stripe 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/stripe/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 GST Invoicing and US Sales Tax.

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

Migrate from Stripe Billing

What This Guide Covers

Concept Mapping

What’s Different

Migrating Your Subscribers

Step 1: Export from Stripe

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

​What This Guide Covers

​Concept Mapping

​What’s Different

​Migrating Your Subscribers

​Step 1: Export from Stripe

​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

What This Guide Covers

Concept Mapping

What’s Different

Migrating Your Subscribers

Step 1: Export from Stripe

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