Migrate from RevenueCat

What the Import Brings Over

RevenueCat manages in-app subscription entitlements; Recurso is a full billing engine. Migrating gives you invoices, a double-entry ledger, dunning, tax, and web billing on top of the subscriber base you already have. The import brings over subscribers (as customers), products (as plans), and active entitlements (as subscriptions) — in their current billing state, with no re-billing.

The Import wizard in Settings → Import data

Concept Mapping

RevenueCat	Recurso	Notes
Subscriber (`app_user_id`)	Customer	An email is required — Recurso identifies customers by email. Subscribers whose `$email` attribute is missing are reported as conflicts, never silently dropped.
Product	Plan	`price` (minor units), `currency`, `period_unit` + `period_count` map directly; the plan code becomes `revenuecat_<product_id>`.
Active entitlement	Subscription	Imported in its current state; `expires_at` becomes the current period end and the billing anchor, so Recurso bills at the next renewal — never re-charging a period the store already collected.
Trial entitlement	Trialing subscription	`is_trial` maps to the `trialing` status with the trial end carried over.
Store payment (App Store / Play)	—	Store-billed payment methods can’t migrate; collect a web payment method for future renewals.

What’s Different

Email is the identity. RevenueCat keys subscribers by an opaque app_user_id; Recurso requires an email per customer. The preview lists every subscriber without one so you can backfill emails before committing.
Only active entitlements import. Expired ones aren’t subscriptions any more; import history stays in RevenueCat.
No invoices are generated at import. Subscriptions resume billing at their imported period end.

Migrating Your Subscribers

Step 1: Export from RevenueCat

Assemble a JSON export with your subscribers (including their $email attribute and current entitlements) and products:

{
  "subscribers": [
    {
      "app_user_id": "user_1a2b3c",
      "email": "ada@example.com",
      "subscriptions": [
        { "product_id": "pro_monthly", "store": "app_store", "is_active": true, "is_trial": false, "expires_at": 1767225600 }
      ]
    }
  ],
  "products": [
    { "id": "pro_monthly", "title": "Pro Monthly", "price": 999, "currency": "USD", "period_unit": "month", "period_count": 1 }
  ]
}

Step 2: Dry-run first

Upload the export in Settings → Import data → RevenueCat, or via the API — the preview is a zero-side-effect plan of exactly what a commit would create, link, skip, or refuse (including every subscriber missing an email):

curl -s https://api.recurso.dev/v1/import/revenuecat/preview \
  -H "Authorization: Bearer $RECURSO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @data.json | jq '.summary'

Step 3: Import for real

curl -s https://api.recurso.dev/v1/import/revenuecat/commit \
  -H "Authorization: Bearer $RECURSO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @data.json | jq '{created, failures}'

The commit is idempotent — already-imported records are skipped, so a partial failure is safe to fix and re-run. Per-object failures are reported in the response, never fatal.

No invoices are generated by the import. Each subscription’s next invoice is issued at its imported expires_at. Connect a web payment gateway (see Payment Gateways) before that first renewal so charges succeed once the store subscription lapses.

Step 4: Prove it — the Compare gate

Before cutting over, re-run the export through the Compare gate. It diffs the export against your live Recurso data — read-only — and reports, per record: coverage (every importable subscriber, product, and entitlement exists in Recurso), fidelity (price, currency, and period exact; identity intact), and continuity (an entitlement whose expires_at drifted more than an hour from the imported period end is flagged as the double-billing / billing-gap risk it is).

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

"ready": true means zero issues. Every run persists, and GET /v1/import/compare-reports/{report_id}/document renders it as a printable, dated receipt — proof for your team that the migration was checked before go-live. The same gate runs from the Import wizard’s final step.

After Migrating

Collect web payment methods

Store-billed cards can’t follow the subscriber. Send customers a portal link to add a card or mandate before their first Recurso renewal.

Point your entitlement checks at Recurso

Use subscription status from the Recurso API (or the MCP server) where your app previously asked RevenueCat.

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 RevenueCat

What the Import Brings Over

Concept Mapping

What’s Different

Migrating Your Subscribers

Step 1: Export from RevenueCat

Step 2: Dry-run first

Step 3: Import for real

Step 4: Prove it — the Compare gate

After Migrating

Next Steps

Going to Production

Customer Portal

​What the Import Brings Over

​Concept Mapping

​What’s Different

​Migrating Your Subscribers

​Step 1: Export from RevenueCat

​Step 2: Dry-run first

​Step 3: Import for real

​Step 4: Prove it — the Compare gate

​After Migrating

​Next Steps

Going to Production

Customer Portal

What the Import Brings Over

Concept Mapping

What’s Different

Migrating Your Subscribers

Step 1: Export from RevenueCat

Step 2: Dry-run first

Step 3: Import for real

Step 4: Prove it — the Compare gate

After Migrating

Next Steps