> ## 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 Deferred Revenue Rollforward
> The Deferred Revenue account's movement for one calendar month — opening balance, deferrals added, amounts released, and the derived closing balance. Read-only.
Returns the movement of the Deferred Revenue account (code `2100`) over a
calendar month, sourced straight from the ledger: the balance carried in at
the start of the month, new deferrals booked during it (credits), amounts
recognized or reversed out of it (debits), and the closing balance. The
identity is always `opening + added - released == closing`. This is the
rollforward an auditor ties to the Deferred Revenue line of the
[trial balance](/api-reference/ledger/trial-balance).
For the schedule-sourced view of the same balance — what the recognition
schedules say is still deferred — use the
[revenue recognition report](/api-reference/revrec/report). The
[month-end close pack](/api-reference/finance/close-pack) returns both and
reports whether they tie.
## Query Parameters
| Parameter | Type | Required | Description |
| --------- | ------- | -------- | ------------------------------- |
| `month` | integer | **Yes** | Calendar month, `1`–`12`. |
| `year` | integer | **Yes** | Calendar year, `2000` or later. |
The period runs from `00:00:00 UTC` on the first of the month up to, but not
including, the first of the next month.
## Example Request
```bash theme={null}
curl "https://api.recurso.dev/v1/ledger/deferred-rollforward?month=8&year=2026" \
-H "Authorization: Bearer $API_KEY"
```
## Response
```json theme={null}
{
"data": {
"tenant_id": "0b7a3f7e-4a2b-4c1d-9e8f-1a2b3c4d5e6f",
"period_start": "2026-08-01T00:00:00Z",
"period_end": "2026-09-01T00:00:00Z",
"opening": 2900000,
"added": 1400000,
"released": 800000,
"closing": 3500000,
"reporting_currency": "INR"
}
}
```
## Fields
| Field | Type | Description |
| -------------------- | ------------------ | ------------------------------------------------------------------------------------------ |
| `tenant_id` | string (uuid) | The tenant the rollforward belongs to |
| `period_start` | string (date-time) | First instant of the month (inclusive) |
| `period_end` | string (date-time) | First instant of the following month (exclusive) |
| `opening` | integer | Deferred Revenue balance at `period_start`, minor units |
| `added` | integer | New deferrals booked in the period — credits to Deferred Revenue, minor units |
| `released` | integer | Amounts recognized or reversed out in the period — debits to Deferred Revenue, minor units |
| `closing` | integer | `opening + added - released`, minor units |
| `reporting_currency` | string | The tenant's base currency; use its exponent to format the minor-unit amounts |
Responses are cached per tenant and URL for five minutes; the `X-Cache`
header reports `HIT` or `MISS`.
## Errors
| Status | Code | When | Fix |
| ------ | ------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `400` | `validation_failed` | `month` missing or outside `1`–`12` | Pass `month=1`…`12` |
| `400` | `validation_failed` | `year` missing, not an integer, or before 2000 | Pass a four-digit year, `2000` or later |
| `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/ledger/deferred-rollforward
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/ledger/deferred-rollforward:
get:
tags:
- Finance
summary: Deferred-revenue rollforward
description: |
The Deferred Revenue account's movement for a calendar month: opening
balance, deferrals added, amounts released, and the derived closing
(opening + added - released). Read-only.
operationId: getDeferredRollforward
parameters:
- name: month
in: query
required: true
schema:
type: integer
minimum: 1
maximum: 12
- name: year
in: query
required: true
schema:
type: integer
responses:
'200':
description: Deferred-revenue rollforward.
content:
application/json:
schema:
type: object
properties:
data:
type: object
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
components:
responses:
BadRequest:
description: The request body or parameters are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
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`.
````