> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecleff.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Treasury

> The balance partitioned: fee earmark, working balance, committed outflow, and payout headroom.

The treasury view partitions your Cleff Account balance into what a new payout
can actually draw on:

* **Earmarked balance**: what Cleff has reserved for your next monthly
  invoice's fees. Fees accrue regardless of account state, so this reports
  even before an account is provisioned.
* **Working balance**: the available balance minus the fee earmark. Signed;
  `low_balance_warning` is raised when it goes negative.
* **Committed outflow**: payouts committed but not yet debited from the
  balance, with the count of payouts behind the figure.
* **Headroom**: working balance minus committed outflow, which is what a new
  payout can safely draw on. `headroom_warning` is raised when it goes
  negative, meaning committed payouts will fail at dispatch unless funds
  arrive first.

Payout creation does not reserve funds. Headroom is the read you check before
committing volume, and a shortfall surfaces at dispatch, not at creation.

The view is scoped to the Business and environment of the credential; a
sandbox credential reads the sandbox partition, never production.


## OpenAPI

````yaml GET /v1/treasury/earmarked-balance
openapi: 3.0.0
info:
  title: Cleff API
  description: >-
    Payout orchestration platform. All endpoints under /v1/ require an API key
    in the Authorization header (Bearer ck_<env>_<id>_<secret>).
  version: 0.0.1
  contact: {}
servers: []
security: []
tags: []
paths:
  /v1/treasury/earmarked-balance:
    get:
      tags:
        - Treasury
      summary: Get the current Business's earmarked balance
      description: >-
        Partitions the dedicated-account balance into the working balance and
        the earmarked in-progress invoice total, with a low-balance warning.
        Scoped to the caller's Business and environment.
      operationId: EarmarkedBalanceController_get
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EarmarkedBalanceDto'
        '401':
          description: Missing or invalid credentials
      security:
        - api_key: []
components:
  schemas:
    EarmarkedBalanceDto:
      type: object
      properties:
        currency:
          type: string
        account_provisioned:
          type: boolean
          description: >-
            False until the Business has a provisioned dedicated account. When
            false the working balance is null and no low-balance warning is
            raised, but the earmarked fee buckets still report.
        working_balance_minor:
          type: number
          nullable: true
          description: >-
            Available balance minus the in-progress invoice, in minor units.
            Signed — negative is the low-balance condition. Null when no account
            is provisioned.
        accrued_invoice_total_minor:
          type: number
          description: >-
            Monthly-invoice total accrued for the in-progress period, in minor
            units (bucket c).
        accrued_subscription_total_minor:
          type: number
          description: >-
            The subscription slice of the accrued invoice total, in minor units.
            The rest of the invoice total is usage-driven fees. Lets the caller
            show what portion of the earmark is the recurring subscription.
        next_invoice_forecast_date:
          type: string
          format: date-time
          description: >-
            Forecast collection date for the in-progress invoice (first of next
            month, UTC).
        low_balance_warning:
          type: boolean
          description: >-
            True when the working balance is negative — earmarked fees exceed
            what's available.
        committed_outflow_minor:
          type: number
          description: >-
            Payouts committed but not yet debited from the balance mirror, in
            minor units.
        committed_payout_count:
          type: number
          description: Number of payouts making up the committed outflow.
        headroom_minor:
          type: number
          nullable: true
          description: >-
            What a new payout can safely draw on: working balance minus
            committed outflow, in minor units. Signed. Null when no account is
            provisioned.
        headroom_warning:
          type: boolean
          description: >-
            True when the headroom is negative — committed payouts exceed what's
            available after the fee earmark, so they will fail at dispatch
            unless funds arrive first.
      required:
        - currency
        - account_provisioned
        - working_balance_minor
        - accrued_invoice_total_minor
        - accrued_subscription_total_minor
        - next_invoice_forecast_date
        - low_balance_warning
        - committed_outflow_minor
        - committed_payout_count
        - headroom_minor
        - headroom_warning
  securitySchemes:
    api_key:
      scheme: bearer
      bearerFormat: ck_<env>_<id>_<secret>
      type: http
      description: >-
        Cleff API key issued to a Business that self-registers via POST
        /v1/registration

````