> ## 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.

# Customer Financial Summary

> A customer's invoice-derived financial position, one block per currency: outstanding, past due, lifetime billed, and paid.

## What it returns

A customer's invoice-derived financial position, one block per currency:

* **`outstanding`** — the amount remaining on `open` + `past_due` invoices.
* **`past_due`** / **`past_due_count`** — the past-due slice of that, and how
  many invoices it spans.
* **`billed`** — lifetime issued total.
* **`paid`** — lifetime paid.

Written-off invoices are excluded from `outstanding`; `draft` and `void`
invoices are excluded from `billed` and `paid`. Money is never summed across
currencies — a customer billed in both USD and INR gets two blocks, not one
converted figure. Every number here is derived from invoices you can list with
[List Invoices](/api-reference/invoices/list) filtered by `customer_id`, so it
can always be explained; see [Explain any number](/advanced/explain-any-number).

## Example request

```bash theme={null}
curl https://api.recurso.dev/v1/customers/0b7a3f7e-4a2b-4c1d-9e8f-1a2b3c4d5e6f/financial-summary \
  -H "Authorization: Bearer $API_KEY"
```

## Example response

```json theme={null}
{
  "data": {
    "customer_id": "0b7a3f7e-4a2b-4c1d-9e8f-1a2b3c4d5e6f",
    "currencies": [
      {
        "currency": "USD",
        "outstanding": 236000,
        "past_due": 118000,
        "past_due_count": 1,
        "billed": 944000,
        "paid": 708000
      }
    ]
  }
}
```

## Fields

| Field            | Type            | Description                                                   |
| ---------------- | --------------- | ------------------------------------------------------------- |
| `currency`       | string          | ISO currency code for this block                              |
| `outstanding`    | integer (int64) | Amount remaining on `open` + `past_due` invoices, minor units |
| `past_due`       | integer (int64) | The past-due portion of `outstanding`                         |
| `past_due_count` | integer         | Number of past-due invoices                                   |
| `billed`         | integer (int64) | Lifetime issued total (excludes `draft`/`void`)               |
| `paid`           | integer (int64) | Lifetime paid (excludes `draft`/`void`)                       |

<Note>
  Read-only. A customer with no non-draft invoices returns an empty
  `currencies` list; a missing or cross-tenant `id` returns `404`. For the
  customer's account-credit position, use the
  [credit statement](/api-reference/customers/credit-statement).
</Note>


## OpenAPI

````yaml GET /v1/customers/{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 <api_key>

    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/customers/{id}/financial-summary:
    get:
      tags:
        - Customers
      summary: Customer financial summary
      description: >
        A customer's invoice-derived financial position, one block per currency:
        outstanding (open + past_due amount remaining), the past-due slice with
        its invoice count, lifetime billed (issued total), and paid. Written-off
        invoices are excluded from outstanding; draft/void from billed/paid.
        Money is never summed across currencies.
      operationId: getCustomerFinancialSummary
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The financial summary.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      customer_id:
                        type: string
                        format: uuid
                      currencies:
                        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: Customer 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`.

````