Multi-Entity Organizations

This page explains the concepts. To turn it on step by step, follow the organizations setup guide.

Consolidated Multi-Tenant Management

Organizations in Recurso let you group multiple tenants under a single parent entity. This is designed for holding companies, multi-brand businesses, and enterprises that operate several billing entities but need consolidated reporting and centralized management.

Consolidated View

See MRR and revenue across all tenants in one place

Tenant Isolation

Each tenant maintains full data isolation — customers, subscriptions, and invoices are separate

Centralized Admin

Manage all tenants from a single organization-level account

How It Works

Each tenant is a fully independent billing entity with its own customers, plans, subscriptions, invoices, and payment gateway configurations. The organization layer sits above tenants and provides cross-entity visibility.

Organization Object

Field	Type	Description
`id`	`string`	Unique organization ID (e.g., `org_abc123`)
`name`	`string`	Organization display name
`owner_email`	`string`	Email of the organization owner/admin
`created_at`	`string`	ISO 8601 timestamp
`updated_at`	`string`	ISO 8601 timestamp

Create an Organization

curl -X POST https://api.recurso.dev/v1/organizations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Holdings",
    "owner_email": "admin@acmeholdings.com"
  }'

Create Parameters

Parameter	Type	Required	Description
`name`	`string`	Yes	Display name for the organization
`owner_email`	`string`	Yes	Email address of the primary admin

List Organizations

Retrieve all organizations accessible with your API key:

curl -G https://api.recurso.dev/v1/organizations \
  -H "Authorization: Bearer $API_KEY" \
  -d limit=20

Get an Organization

curl https://api.recurso.dev/v1/organizations/org_acme01 \
  -H "Authorization: Bearer $API_KEY"

Update an Organization

Update the name or owner email of an existing organization:

curl -X PUT https://api.recurso.dev/v1/organizations/org_acme01 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Holdings International",
    "owner_email": "cfo@acmeholdings.com"
  }'

Delete an Organization

Remove an organization. This does not delete the tenants — they become standalone entities.

curl -X DELETE https://api.recurso.dev/v1/organizations/org_acme01 \
  -H "Authorization: Bearer $API_KEY"

Deleting an organization removes all tenant associations and consolidated reporting. The tenants themselves and their data are not affected — they continue operating independently.

Managing Tenants

Tenants are independent billing entities. Add existing tenants to an organization to enable consolidated reporting.

Add a Tenant to an Organization

curl -X POST https://api.recurso.dev/v1/organizations/org_acme01/tenants \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "tenant_brandx"
  }'

Add Tenant Parameters

Parameter	Type	Required	Description
`tenant_id`	`string`	Yes	The ID of the tenant to add to the organization

A tenant can belong to only one organization. Attempting to add a tenant that is already part of another organization will return an error.

List Tenants in an Organization

curl https://api.recurso.dev/v1/organizations/org_acme01/tenants \
  -H "Authorization: Bearer $API_KEY"

Remove a Tenant from an Organization

Detach a tenant from an organization without deleting the tenant or its data:

curl -X DELETE https://api.recurso.dev/v1/organizations/org_acme01/tenants/tenant_brandz \
  -H "Authorization: Bearer $API_KEY"

After removal, the tenant continues operating independently but no longer appears in consolidated reports. You can re-add it later.

Consolidated MRR

The consolidated MRR endpoint aggregates MRR metrics across all tenants in an organization, giving you a single view of your total recurring revenue.

curl https://api.recurso.dev/v1/organizations/org_acme01/analytics/mrr \
  -H "Authorization: Bearer $API_KEY"

When tenants bill in different currencies, the consolidated MRR response includes per-tenant breakdowns with their respective currencies. Recurso does not perform currency conversion — aggregate totals are grouped by currency.

Tenant Isolation

Even within an organization, tenants maintain strict data isolation. A tenant-level API key can only access its own data.

Boundary	Behavior
Customers	A customer in Tenant A cannot be accessed via Tenant B’s API key
Subscriptions	Subscriptions belong to a single tenant and cannot cross tenant boundaries
Invoices	Invoices are generated per tenant with tenant-specific numbering and branding
Payment Gateways	Each tenant can have its own Razorpay/Stripe credentials
Webhooks	Webhook endpoints are configured per tenant
API Keys	Each tenant has independent API keys; organization-level keys provide read access across tenants

Organization-level API keys should only be used for analytics and reporting. Use tenant-level API keys for all transactional operations (creating customers, subscriptions, invoices).

Use Cases

Holding Companies

A holding company owns multiple SaaS products, each as a separate tenant. The CFO views combined MRR from one dashboard while each product manages billing independently.

Multi-Brand Businesses

A company operates different brands targeting different markets. Each brand has its own pricing and payment gateway, but the finance team gets a unified revenue view.

Franchises and Resellers

Each franchisee or reseller operates as an independent tenant. The parent company monitors aggregate MRR across all entities.

Staging and Production Separation

Group tenant_prod and tenant_staging under the same org to keep test data isolated while maintaining a single management interface.

API Reference Summary

Method	Endpoint	Description
`POST`	`/v1/organizations`	Create a new organization
`GET`	`/v1/organizations`	List all organizations
`GET`	`/v1/organizations/:id`	Get organization details
`PUT`	`/v1/organizations/:id`	Update an organization
`DELETE`	`/v1/organizations/:id`	Delete an organization
`POST`	`/v1/organizations/:id/tenants`	Add a tenant to the organization
`GET`	`/v1/organizations/:id/tenants`	List all tenants in the organization
`DELETE`	`/v1/organizations/:id/tenants/:tenant_id`	Remove a tenant from the organization
`GET`	`/v1/organizations/:id/analytics/mrr`	Get consolidated MRR across all tenants

Webhook Events

Event	Description
`organization.created`	New organization created
`organization.updated`	Organization details updated
`organization.deleted`	Organization deleted
`organization.tenant_added`	Tenant added to an organization
`organization.tenant_removed`	Tenant removed from an organization

Best Practices

Use Tenant-Level Keys for Transactions

Always use tenant-specific API keys for creating customers, subscriptions, and invoices to maintain isolation

Monitor Per-Tenant Health

Use consolidated MRR to compare tenant performance and identify underperforming entities

Separate Gateways Per Tenant

Configure dedicated payment gateway credentials for each tenant to keep financial flows independent

Plan Org Structure Early

Design your organization and tenant structure before going live — migrating customers between tenants is a manual process

For businesses starting with a single entity, you can always create an organization later and add your existing tenant to it. There is no need to set up an organization on day one if you only have one billing entity.

Get Started

Migrate to Recurso

Core Concepts

Usage & Monetization

Money & Books

Tax & Compliance

Recover & Retain

Customer Portal

Platform & Integrations

Deploy & Operate

Reference

Multi-Entity Organizations

Consolidated Multi-Tenant Management

Consolidated View

Tenant Isolation

Centralized Admin

How It Works

Organization Object

Create an Organization

Create Parameters

List Organizations

Get an Organization

Update an Organization

Delete an Organization

Managing Tenants

Add a Tenant to an Organization

Add Tenant Parameters

List Tenants in an Organization

Remove a Tenant from an Organization

Consolidated MRR

Tenant Isolation

Use Cases

API Reference Summary

Webhook Events

Best Practices

Use Tenant-Level Keys for Transactions

Monitor Per-Tenant Health

Separate Gateways Per Tenant

Plan Org Structure Early

​Consolidated Multi-Tenant Management

Consolidated View

Tenant Isolation

Centralized Admin

​How It Works

​Organization Object

​Create an Organization

​Create Parameters

​List Organizations

​Get an Organization

​Update an Organization

​Delete an Organization

​Managing Tenants

​Add a Tenant to an Organization

​Add Tenant Parameters

​List Tenants in an Organization

​Remove a Tenant from an Organization

​Consolidated MRR

​Tenant Isolation

​Use Cases

​API Reference Summary

​Webhook Events

​Best Practices

Use Tenant-Level Keys for Transactions

Monitor Per-Tenant Health

Separate Gateways Per Tenant

Plan Org Structure Early

Consolidated Multi-Tenant Management

How It Works

Organization Object

Create an Organization

Create Parameters

List Organizations

Get an Organization

Update an Organization

Delete an Organization

Managing Tenants

Add a Tenant to an Organization

Add Tenant Parameters

List Tenants in an Organization

Remove a Tenant from an Organization

Consolidated MRR

Tenant Isolation

Use Cases

API Reference Summary

Webhook Events

Best Practices