> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recurso.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Revenue Recognition Waterfall
> The recognition curve — revenue already recognized and revenue still scheduled — bucketed by calendar month, with totals. Read-only.
Returns the tenant's full recognized-plus-scheduled revenue curve, one bucket
per calendar month that has at least one recognition event: how much revenue
each month has already recognized and how much is still scheduled (pending)
to recognize in it. Buckets are grouped from the events themselves, so a
month with no `recognized` or `pending` event is simply absent — the series is
ordered but not gap-filled. Past months carry `recognized`; future months
carry `scheduled`; the current month can carry both. This is the classic
rev-rec waterfall an auditor plots to see how deferred revenue releases over
time. Read-only.
For a single month's figures plus the still-deferred balance broken down by
currency, use the [revenue recognition report](/api-reference/revrec/report).
For the ledger's own view of the deferred balance, use the
[Deferred Revenue rollforward](/api-reference/ledger/deferred-rollforward).
## Example Request
```bash theme={null}
curl "https://api.recurso.dev/v1/finance/revrec/waterfall" \
-H "Authorization: Bearer $API_KEY"
```
## Response
```json theme={null}
{
"data": {
"tenant_id": "0b7a3f7e-4a2b-4c1d-9e8f-1a2b3c4d5e6f",
"buckets": [
{ "year": 2026, "month": 6, "recognized": 700000, "scheduled": 0 },
{ "year": 2026, "month": 7, "recognized": 750000, "scheduled": 0 },
{ "year": 2026, "month": 8, "recognized": 800000, "scheduled": 0 },
{ "year": 2026, "month": 9, "recognized": 0, "scheduled": 750000 },
{ "year": 2026, "month": 10, "recognized": 0, "scheduled": 500000 },
{ "year": 2026, "month": 11, "recognized": 0, "scheduled": 250000 }
],
"total_recognized": 2250000,
"total_scheduled": 1500000,
"reporting_currency": "INR"
}
}
```
## Fields
| Field | Type | Description |
| -------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tenant_id` | string (uuid) | The tenant the waterfall belongs to |
| `buckets` | array or null | One entry per calendar month that has at least one `recognized` or `pending` recognition event, oldest first; months without events are omitted — see below. When the tenant has no such events at all the field is `null`, not `[]` |
| `total_recognized` | integer | Sum of every bucket's `recognized`, minor units |
| `total_scheduled` | integer | Sum of every bucket's `scheduled`, minor units — the still-deferred balance across all schedules |
| `reporting_currency` | string | The tenant's base currency, resolved from the ledger after the sums are taken. A label only — amounts are not converted into it (see below) |
### Bucket Fields
| Field | Type | Description |
| ------------ | ------- | ---------------------------------------------------------------------------------------------------------- |
| `year` | integer | Calendar year of the bucket |
| `month` | integer | Calendar month, `1`–`12` |
| `recognized` | integer | Sum of recognition events with status `recognized` whose recognition date falls in that month, minor units |
| `scheduled` | integer | Sum of recognition events with status `pending` whose recognition date falls in that month, minor units |
A tenant with no `recognized` or `pending` recognition events gets
`"buckets": null` (with both totals `0`), not an empty array. Guard for
`null` before iterating.
The statuses above are recognition-event statuses, not schedule statuses
(`active`, `canceled`). Only `recognized` and `pending` events are summed;
events in any other status (`processing`, `failed`, `reversed`, `canceled`)
are excluded from every bucket.
Amounts are a raw sum of each event's `amount` across whatever currencies the
underlying schedules carry — no FX conversion is applied, so on a
multi-currency tenant the figures are not denominated in `reporting_currency`.
Read `by_currency` on the [monthly report](/api-reference/revrec/report) for
the native split.
Responses are cached per tenant and URL for five minutes; the `X-Cache`
header reports `HIT` or `MISS`.
## Errors
| Status | Code | When | Fix |
| ------ | ------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `401` | `unauthorized` | No `Authorization` bearer token (and no session cookie) was sent | Send `Authorization: Bearer $API_KEY` |
| `401` | `invalid_api_key` | A bearer token was sent but is not a valid key | Check the key in [Developer keys](/api-reference/developer/list-keys) |
| `401` | `key_mode_mismatch` | The key's live/test mode does not match this API host | Use a key for the right mode — see [Authentication](/api-reference/authentication) |
Errors use the standard envelope — see [Errors](/api-reference/errors).
## OpenAPI
````yaml GET /v1/finance/revrec/waterfall
openapi: 3.1.0
info:
title: Recurso API
version: 1.0.0
description: |
The Recurso billing engine REST API.
Authenticate by passing your API key as a bearer token:
Authorization: Bearer
Obtain an API key by registering a tenant via `POST /auth/register`.
All authenticated endpoints live under the `/v1` prefix. Mutating
endpoints support idempotency via the `Idempotency-Key` header.
license:
name: MIT
identifier: MIT
servers:
- url: https://billing.example.com
description: >-
Example deployment — substitute the base URL of your own Recurso
deployment.
security:
- bearerAuth: []
tags:
- name: System
description: Health, version, and API metadata
- name: Auth
description: Tenant registration
- name: Plans
description: Product catalog plans
- name: Customers
description: Customer management
- name: Subscriptions
description: Subscription lifecycle
- name: Invoices
description: Invoices, PDFs, and Indian GST e-invoicing
- name: Coupons
description: Discounts
- name: Usage
description: Metered usage events
- name: Credit Notes
description: Customer credits
- name: Quotes
description: Quote-to-invoice lifecycle
- name: Webhooks
description: Webhook endpoint management and event feed
- name: Analytics
description: Revenue analytics
- name: Checkout
description: Public hosted checkout for invoices
- name: Payments
description: Payment order creation
- name: Inbound Webhooks
description: Receivers for payment-gateway callbacks (Razorpay, Stripe)
- name: Customer Portal
description: Customer-facing portal — magic-link auth and session-scoped data
- name: Developer
description: API key management
- name: Account
description: Tenant account settings
- name: Finance
description: Ledger accounts, entries, reconciliation, and revenue recognition
- name: Settings
description: Tax (GST) and e-invoicing (IRP) configuration
- name: Consents
description: Consent records for RBI-compliant recurring billing
- name: Referrals
description: Customer referral program
- name: Gifts
description: Gift subscriptions
- name: Mandates
description: UPI Autopay mandates
- name: Offline Payments
description: Virtual accounts and manually recorded payments
- name: Organizations
description: Multi-entity organizations grouping several tenants
- name: Accounting
description: QuickBooks / Xero accounting integrations
- name: Churn
description: Churn risk scoring and alerts
- name: Cancel Flows
description: Configurable retention flows shown at cancellation time
- name: Dunning
description: Dunning analytics and multi-channel dunning campaigns
paths:
/v1/finance/revrec/waterfall:
get:
tags:
- Finance
summary: Revenue recognition waterfall
description: |
The recognition curve — revenue already recognized and revenue still
scheduled — bucketed by month, with totals. Read-only.
operationId: getRevenueWaterfall
responses:
'200':
description: Revenue waterfall.
content:
application/json:
schema:
type: object
properties:
data:
type: object
'401':
$ref: '#/components/responses/Unauthorized'
components:
responses:
Unauthorized:
description: Missing or invalid credentials (API key or session cookie).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
required:
- error
properties:
error:
type: object
description: Structured error detail.
required:
- code
- message
properties:
code:
type: string
description: Stable machine-readable error code.
examples:
- validation_failed
- unauthorized
- forbidden
- not_found
- conflict
- rate_limited
- internal_error
- invalid_api_key
- key_mode_mismatch
- over_refund
- invoice_not_paid
- invoice_already_paid
message:
type: string
description: Human-readable explanation.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key
description: >-
Tenant API key obtained from `POST /auth/register` or `POST
/v1/developer/keys`.
````