Core Concepts

The Object Hierarchy

Recurso uses a simple hierarchy of objects to manage billing. A plan (flat prices plus usage charges) and a customer meet in a subscription, which generates invoices each cycle — flat fees in advance, metered usage in arrears. Payments settle those invoices (draining any prepaid wallet first), and every financial movement lands in the ledger.

Architecture

Every request flows through the same layers, and every financial event is written to a proper set of books. Recurso keeps a double-entry ledger with PostgreSQL as the authoritative store; when a TigerBeetle backend is connected, each posting is also dual-written to it as an optional high-throughput mirror.

PostgreSQL is always authoritative. TigerBeetle is optional and reconciled against Postgres by transaction ID — see the Double-Entry Ledger guide.

Tenants

A Tenant represents your business or a customer’s business in multi-tenant setups.

Field	Description
`id`	Unique identifier
`name`	Business name
`gstin`	GST number (for Indian businesses)
`settings`	Billing preferences

Most single-product SaaS companies will have just one tenant.

Plans

A Plan defines what you’re selling and how much it costs.

const plan = {
  id: 'plan_pro',
  name: 'Pro Plan',
  code: 'pro-monthly-inr',   // unique per tenant
  interval_unit: 'month',    // day, week, month, year
  interval_count: 1,         // e.g. 3 for quarterly
  active: true,
  hsn_code: '998314',        // GST rate source for this plan's lines
  prices: [
    { amount: 499900, currency: 'INR', type: 'recurring' }
  ],
};
// Trials are per-subscription (`trial_days` on subscription create);
// usage pricing attaches as charges — PUT /v1/plans/{id}/charges.

Pricing Models

A plan combines flat prices (billed in advance) with optional usage charges (billed in arrears at period close). A plan holding both is hybrid — one invoice carries the flat fee and the metered lines.

Flat rate

Fixed price per billing period, per currency, in minor units.

{ "amount": 4999, "currency": "INR", "type": "recurring" }

Per-unit usage

Every metered unit at one rate — decimal strings support sub-paise pricing like ₹0.0035/call.

{ "charge_model": "per_unit",
  "amounts": { "INR": { "unit_amount": "0.0035" } } }

Graduated & volume tiers

Graduated prices each band’s units at its own rate; volume prices the whole quantity at the tier it reaches.

{ "charge_model": "graduated",
  "amounts": { "INR": { "tiers": [
    { "up_to": 10000, "unit_amount": "0" },
    { "up_to": null,  "unit_amount": "0.05" }
  ]}}}

Package

Bundles that round up: ₹5.00 per 1,000 calls.

{ "charge_model": "package",
  "amounts": { "INR": { "package_amount": 500, "package_size": 1000 } } }

See the Usage-Based Billing guide for the full pipeline from event to invoice line.

Customers

A Customer is someone who pays you.

const customer = {
  id: 'cust_abc123',
  name: 'Acme Corp',
  email: 'billing@acme.com',
  phone: '+919876543210',
  gstin: '29ABCDE1234F1Z5',  // Optional, for B2B
  billing_address: {
    line1: '123 Main St',
    city: 'Bangalore',
    state: 'Karnataka',
    postal_code: '560001',
    country: 'IN'
  }
};

Subscriptions

A Subscription connects a customer to a plan.

const subscription = {
  id: 'sub_xyz789',
  customer_id: 'cust_abc123',
  plan_id: 'plan_pro',
  status: 'active',
  current_period_start: '2024-01-01T00:00:00Z',
  current_period_end: '2024-02-01T00:00:00Z',
  billing_anchor: 1,  // Day of month to bill
  cancel_at_period_end: false
};

Subscription States

Status	Description
`created`	Subscription created, awaiting first payment
`active`	Subscription is active and paid
`past_due`	Payment failed, in dunning
`incomplete`	Initial payment failed
`canceled`	Subscription ended
`trialing`	In trial period

Invoices

An Invoice is a record of what the customer owes.

const invoice = {
  id: 'inv_001',
  customer_id: 'cust_abc123',
  subscription_id: 'sub_xyz789',
  invoice_number: 'REC/2024/0001',
  status: 'paid',
  currency: 'INR',
  subtotal: 4999,
  tax_amount: 900,  // 18% GST
  total: 5899,
  due_date: '2024-01-15T00:00:00Z',
  paid_at: '2024-01-10T12:30:00Z'
};

Invoice States

Status	Description
`draft`	Not yet finalized
`open`	Awaiting payment
`paid`	Payment received
`past_due`	Payment overdue
`uncollectible`	Marked as bad debt
`void`	Canceled

Payments

A Payment records successful transactions.

const payment = {
  id: 'pay_123',
  invoice_id: 'inv_001',
  amount: 5899,
  currency: 'INR',
  status: 'succeeded',
  gateway: 'razorpay',
  gateway_payment_id: 'pay_AbCdEf123456'
};

Billable Metrics & Usage

A billable metric is a named meter over usage events — its code doubles as the event dimension it aggregates (count, sum, max, or unique property values). Events ingest one at a time or in batches of 500, with optional transaction_id idempotency so retries never double-count. At period close, each charge on the plan aggregates the elapsed period’s events and prices them onto the renewal invoice — exactly once, guarded by a rated-window claim.

Wallets, Commitments & Alerts

Wallets hold prepaid balance per customer and currency. Invoices drain the wallet before credit notes and the payment gateway; promotional credit can expire, and auto-recharge tops balances up from the saved payment method. (guide)
Commitments set a per-period revenue floor: shortfalls bill an automatic true-up line at period close. (guide)
Usage alerts watch a metric against a threshold — absolute or a percent of the entitlement limit — and fire once per billing period via webhook and email. (guide)

Webhooks

Webhooks notify your app about billing events.

Event	Description
`subscription.created`	New subscription
`subscription.created`	Subscription became active
`subscription.canceled`	Subscription canceled
`payment.succeeded`	Payment received
`payment.failed`	Payment failed
`invoice.created`	New invoice generated
`invoice.paid`	Invoice paid

Get Started

Migrate to Recurso

Usage & Monetization

Money & Books

Tax & Compliance

Recover & Retain

Customer Portal

Platform & Integrations

Deploy & Operate

Reference

Core Concepts

The Object Hierarchy

Architecture

Tenants

Plans

Pricing Models

Customers

Subscriptions

Subscription States

Invoices

Invoice States

Payments

Billable Metrics & Usage

Wallets, Commitments & Alerts

Webhooks

Next Steps

Plans

Subscriptions

​The Object Hierarchy

​Architecture

​Tenants

​Plans

​Pricing Models

​Customers

​Subscriptions

​Subscription States

​Invoices

​Invoice States

​Payments

​Billable Metrics & Usage

​Wallets, Commitments & Alerts

​Webhooks

​Next Steps

Plans

Subscriptions

The Object Hierarchy

Architecture

Tenants

Plans

Pricing Models

Customers

Subscriptions

Subscription States

Invoices

Invoice States

Payments

Billable Metrics & Usage

Wallets, Commitments & Alerts

Webhooks

Next Steps