> ## 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.
# Subscription Financial Summary
> One subscription's financial position: MRR, recurring list price and interval, next-invoice date and base amount, and its invoice-derived outstanding position per currency.
## What it returns
One subscription's financial position:
* **`mrr`** — the monthly-normalized list price, counted only when the
subscription is `active` (`0` otherwise). This matches the tenant-wide
[MRR](/api-reference/analytics/mrr) definition, so summing it across
subscriptions agrees with the dashboard.
* **`recurring_amount`**, **`interval_unit`**, **`interval_count`** — the
recurring list price and its interval.
* **`next_invoice_date`** and **`next_invoice_base_amount`** — when it will
renew and the base amount. Base is the plan list price only; it excludes tax,
coupon, add-ons, and usage, so it is never the total that will be due.
* **`outstanding`** — the subscription's invoice-derived position per currency,
in the same shape as the
[customer financial summary](/api-reference/customers/financial-summary).
See [Explain any number](/advanced/explain-any-number) for how this fits with
the other drill-down endpoints.
## Example request
```bash theme={null}
curl https://api.recurso.dev/v1/subscriptions/b9071c55-0e14-4720-80f3-665613ceb7de/financial-summary \
-H "Authorization: Bearer $API_KEY"
```
## Example response
```json theme={null}
{
"data": {
"subscription_id": "b9071c55-0e14-4720-80f3-665613ceb7de",
"status": "active",
"currency": "USD",
"mrr": 100000,
"recurring_amount": 100000,
"interval_unit": "month",
"interval_count": 1,
"current_period_start": "2026-08-01T00:00:00Z",
"current_period_end": "2026-09-01T00:00:00Z",
"next_invoice_date": "2026-09-01T00:00:00Z",
"next_invoice_base_amount": 100000,
"coupon_id": null,
"discount_active": false,
"outstanding": [
{
"currency": "USD",
"outstanding": 118000,
"past_due": 0,
"past_due_count": 0,
"billed": 354000,
"paid": 236000
}
]
}
}
```
## Fields
| Field | Type | Description |
| --------------------------------------------- | ---------------------------- | -------------------------------------------------------------------------- |
| `status` | string | The subscription's current status |
| `currency` | string | The subscription's billing currency |
| `mrr` | integer (int64) | Monthly-normalized recurring value; `0` unless `active` |
| `recurring_amount` | integer (int64) | Recurring list price per interval, minor units |
| `interval_unit` / `interval_count` | string / integer | Billing interval (e.g. `month` × `1`) |
| `current_period_start` / `current_period_end` | string (date-time) | The current billing period |
| `next_invoice_date` | string (date-time), nullable | When the next invoice will be generated; `null` when it will not renew |
| `next_invoice_base_amount` | integer (int64) | Plan list price only — excludes tax, coupon, add-ons, and usage |
| `coupon_id` | string (uuid), nullable | Attached coupon, if any |
| `discount_active` | boolean | Whether that coupon currently applies |
| `outstanding[]` | array | Per-currency `outstanding`, `past_due`, `past_due_count`, `billed`, `paid` |
Read-only. A missing or cross-tenant `id` returns `404`. For what canceling
this subscription would do to these numbers, see
[Cancel Preview](/api-reference/subscriptions/cancel-preview).
## OpenAPI
````yaml GET /v1/subscriptions/{id}/financial-summary
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/subscriptions/{id}/financial-summary:
get:
tags:
- Subscriptions
summary: Subscription financial summary
description: >
One subscription's financial position: MRR (monthly-normalized list
price, counted only when active — 0 otherwise, matching the tenant-wide
MRR definition), the recurring list price + interval, the next-invoice
date and base amount when it will renew (base = list price only; it
excludes tax/coupon/add-ons/usage), and its invoice-derived outstanding
position per currency. Read-only; cross-tenant ids return 404.
operationId: getSubscriptionFinancialSummary
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: The subscription's financial summary.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
subscription_id:
type: string
format: uuid
status:
type: string
currency:
type: string
mrr:
type: integer
format: int64
description: Monthly-normalized recurring value; 0 unless active.
recurring_amount:
type: integer
format: int64
interval_unit:
type: string
interval_count:
type: integer
current_period_start:
type: string
format: date-time
current_period_end:
type: string
format: date-time
next_invoice_date:
type: string
format: date-time
nullable: true
next_invoice_base_amount:
type: integer
format: int64
description: >-
Plan list price only; excludes
tax/coupon/add-ons/usage. Never the total due.
coupon_id:
type: string
format: uuid
nullable: true
discount_active:
type: boolean
outstanding:
type: array
items:
type: object
properties:
currency:
type: string
outstanding:
type: integer
format: int64
past_due:
type: integer
format: int64
past_due_count:
type: integer
billed:
type: integer
format: int64
paid:
type: integer
format: int64
'404':
description: Subscription not found.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key
description: >-
Tenant API key obtained from `POST /auth/register` or `POST
/v1/developer/keys`.
````