Quick Start

The Recurso dashboard after first sign-in

Using Recurso Cloud? You can skip the installation steps below. Cloud users receive API credentials after joining the waitlist — learn more.

Installation

Fastest path: clone the repository and run make demo. It builds and starts the full stack (API, dashboard, PostgreSQL, TigerBeetle, Mailhog), waits for the API to become healthy, and loads demo data. Then open the dashboard at http://localhost:5173 and log in with API key sk_test_12345.

Choose your preferred setup method:

Docker (Recommended)
From Source
Cloud (Early Access)

# Clone the repository
git clone https://github.com/recurso-dev/recurso.git
cd recurso

# Start with Docker Compose
docker-compose up -d

# API available at http://localhost:8080

# Clone the repository
git clone https://github.com/recurso-dev/recurso.git
cd recurso

# Install dependencies
go mod download

# Set up environment
cp .env.example .env

# Start the server — migrations run automatically at boot
make run

Recurso Cloud is managed hosting — no installation required.

Join the waitlist — email cloud@recurso.dev to request access
Receive your API credentials — we’ll provision your instance and send you an API key
Test the connection:

curl https://your-instance.recurso.cloud/v1/customers \
  -H "Authorization: Bearer $RECURSO_API_KEY"

The rest of this quickstart (creating plans, customers, and subscriptions) works identically on Cloud. Replace http://localhost:8080 with your Cloud instance URL.Compare plans

Configuration

Set these environment variables:

.env

# Database
DATABASE_URL=postgres://user:pass@localhost:5432/recurso

# API
PORT=8080

# Payment Gateways (optional)
RAZORPAY_KEY_ID=rzp_test_xxx
RAZORPAY_KEY_SECRET=xxx
STRIPE_SECRET_KEY=sk_test_xxx

# Email (optional)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=noreply@example.com
SMTP_PASSWORD=xxx

Create an API Key

Start the dashboard — a React app in the frontend/ directory of the repository:
cd frontend npm install npm run dev
Open the dashboard at http://localhost:5173 (the Vite dev server proxies API calls to the API at http://localhost:8080)
Navigate to Settings → API Keys
Click Create API Key
Copy and store securely

Test the connection:

curl http://localhost:8080/v1/customers \
  -H "Authorization: Bearer your-api-key"

Optional: Load Demo Data

Want a populated dashboard before creating anything yourself? Seed the dev database with a sample tenant — plans, customers, subscriptions, invoices, events, and a webhook endpoint:

make seed

make seed wipes all existing data in the target database before loading the demo dataset. Only use it on a fresh local install.

Then log in to the dashboard with the demo API key sk_test_12345 and explore. When you’re done exploring, run make seed again for a clean slate or register your own tenant. In dev, any emails the system sends (invoices, dunning notices, and so on) are captured by Mailhog — view them at http://localhost:8025.

Want a public, safe-to-share sandbox instead of a local dev stack? docker compose -f docker-compose.demo.yml up -d runs Recurso in demo mode — mock gateways, blocked destructive settings, auto-login, and an hourly reset.

Create Your First Plan

Create a pricing plan

curl -X POST http://localhost:8080/v1/plans \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Plan",
    "code": "PRO-INR",
    "interval_unit": "month",
    "interval_count": 1,
    "amount": 4999,
    "currency": "INR"
  }'

import { Recurso } from 'recurso';
const recurso = new Recurso('your-api-key', 'http://localhost:8080');

const plan = await recurso.plans.create({
  name: 'Pro Plan',
  code: 'PRO-INR',
  interval_unit: 'month',
  interval_count: 1,
  amount: 4999,      // minor units
  currency: 'INR',
});

client := recurso.NewClient("your-api-key")

plan, _ := client.Plans.Create(ctx, &recurso.PlanCreateParams{
  Name:         "Pro Plan",
  Code:         "PRO-INR",
  IntervalUnit: "month",
  Amount:       4999, // minor units
  Currency:     "INR",
})

Amounts are always minor units — 4999 is ₹49.99.

Add a customer

curl -X POST http://localhost:8080/v1/customers \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "email": "billing@acme.com",
    "metadata": { "company_size": "mid-market" }
  }'

const customer = await recurso.customers.create({
  name: 'Acme Corp',
  email: 'billing@acme.com',
  metadata: { company_size: 'mid-market' },
});

customer, _ := client.Customers.Create(ctx, &recurso.CustomerCreateParams{
  Name:  "Acme Corp",
  Email: "billing@acme.com",
})

Start a subscription

curl -X POST http://localhost:8080/v1/subscriptions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_abc",
    "plan_id": "plan_pro"
  }'

const subscription = await recurso.subscriptions.create({
  customer_id: customer.id,
  plan_id: plan.id,
});

sub, _ := client.Subscriptions.Create(ctx, &recurso.SubscriptionCreateParams{
  CustomerID: customer.ID,
  PlanID:     plan.ID,
})

That’s a running billing stack: the subscription invoices itself every period, usage rates onto the same invoice, and every posting lands on the ledger.

See the first invoice it just issued:

curl "http://localhost:8080/v1/invoices?subscription_id=<subscription-id>" \
  -H "Authorization: Bearer your-api-key"

To collect it, send the customer to the hosted checkout page at http://localhost:8080/checkout/<invoice-id> (see Payments) — or bill accrued usage immediately with POST /v1/subscriptions/{id}/bill-usage.

Record usage (metered pricing)

If the plan carries usage charges, report events as they happen — they aggregate into billable metrics and rate onto the next renewal invoice:

curl -X POST http://localhost:8080/v1/usage/events \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_id": "sub_abc",
    "customer_id": "cust_abc",
    "dimension": "api_calls",
    "quantity": 1200
  }'

Batch up to 500 events per call at /v1/usage/events/batch with a transaction_id per event for idempotent retries — see usage-based billing.

Handle webhooks

import express from 'express';
import crypto from 'crypto';

const app = express();

// Use express.raw so the HMAC runs over the exact bytes Recurso
// signed — re-serializing with JSON.stringify breaks verification.
app.post('/webhooks/recurso', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-recurso-signature'] ?? '';
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body) // raw Buffer
    .digest('hex');

  const valid =
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  if (!valid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.body);
  switch (event.type) {
    case 'subscription.created':
      // Grant access to your product
      break;
    case 'payment.succeeded':
      // Payment received
      break;
    case 'subscription.canceled':
      // Revoke access
      break;
  }

  res.sendStatus(200);
});

Watch the books balance

This is the part most billing tools don’t have. Every event you just triggered — the invoice, the payment, the usage — posted balanced double-entry rows to a real ledger. Ask Recurso to prove it:

curl http://localhost:8080/v1/finance/reconciliation \
  -H "Authorization: Bearer your-api-key"

{
  "data": {
    "invoices_checked": 1,
    "paid_invoices_checked": 1,
    "total_discrepancies": 0,
    "discrepancies": [],
    "tb_compared": false
  }
}

total_discrepancies: 0 is the whole point: every billing record ties to its ledger postings, down to the minor unit. That check runs daily in production, and the same invariant is enforced in CI on every commit to Recurso itself. Read how the postings work in the Ledger guide.

Self-Hosting

For production deployments, see the self-hosting guide on GitHub.

Next Steps

Core Concepts

Plans, customers, subscriptions, invoices — and how the ledger ties them together.

Usage-based billing

Billable metrics, charge models, wallets, commitments, and alerts.

The Ledger

Double-entry postings, account codes, and the reconciliation that reads zero.

Going to production

Hardening, backups, and the production checklist.

Get Started

Migrate to Recurso

Core Concepts

Usage & Monetization

Money & Books

Tax & Compliance

Recover & Retain

Customer Portal

Platform & Integrations

Deploy & Operate

Reference

Installation

Configuration

Create an API Key

Optional: Load Demo Data

Create Your First Plan

Self-Hosting

Next Steps

Core Concepts

Usage-based billing

The Ledger

Going to production

​Installation

​Configuration

​Create an API Key

​Optional: Load Demo Data

​Create Your First Plan

​Self-Hosting

​Next Steps

Core Concepts

Usage-based billing

The Ledger

Going to production

Installation

Configuration

Create an API Key

Optional: Load Demo Data

Create Your First Plan

Self-Hosting

Next Steps