---
title: "GET /api/patient-payments/balances"
method: GET
path: "/api/patient-payments/balances"
---

# GET /api/patient-payments/balances

`GET /api/patient-payments/balances`

## Request

- Base URL: `https://forecaster.cairhealth.com`
- URL: `https://forecaster.cairhealth.com/api/patient-payments/balances`
- Auth: none required

Fetch patient AR page–aligned balances: PATIENT_AR outstanding (IBF lifecycles excluded), ledger manual remaining, PATIENT_CASH unallocated credits, patient-level currentBalance, and lastPayment from Transactions ledger. Look up by external patientId.

## Query parameters

- `patientId` string, required

## Response `200`

Balances fetched successfully

- object
  - `success` boolean
  - `data` object
    - `patientId` string
    - `patientFhirId` string
    - `currentBalance` number: max(0, Σ claim outstanding + Σ manual remaining − unallocated credits)
    - `lastPayment` object, nullable: Newest payment from Transactions ledger (amount + date), or null
      - `paymentAmount` number
      - `paymentDate` string, date-time
      - `paymentMethod` string, nullable
      - `paymentTraceId` string, nullable
    - `unallocatedCreditTotal` number
    - `unallocatedCredits` object[]
    - `manualCharges` object[]
    - `claims` object[]

## Other responses

- `400`: Missing patientId
- `401`: Unauthorized
- `404`: Patient or organization not found
- `500`: Server error

## Changes

- **2026-11-03** `b32380ccde9a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cairhealth/apis/cair-health-apis/changes/api/patient-payments/balances/get.md)

---

[API](https://skmtc.dev/cairhealth/apis/cair-health-apis.md) - [All operations](https://skmtc.dev/cairhealth/apis/cair-health-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/cairhealth/apis/cair-health-apis/revisions/b32380ccde9a?raw)