---
title: "The subscription's live benefit balances (ITE-653): each plan benefit with used/remaining for the CURRENT period, derived from the redemption ledger via PlanBenefitLedger — the same math the redemption pass (ITE-659) uses, so tracker and billing can't disagree."
method: GET
path: "/Subscriptions/{id}/benefit-balances"
tags: ["Subscriptions"]
---

# The subscription's live benefit balances (ITE-653): each plan benefit with used/remaining for the CURRENT period, derived from the redemption ledger via PlanBenefitLedger — the same math the redemption pass (ITE-659) uses, so tracker and billing can't disagree.

`GET /Subscriptions/{id}/benefit-balances`

## Request

- Base URL: `https://api.clinicos.vet/backend/business`
- URL: `https://api.clinicos.vet/backend/business/Subscriptions/{id}/benefit-balances`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/clinicos/apis/pawthosx-business-api-v1/docs/Subscriptions/:id/benefit-balances/get.ts> (a function with typed inputs; its response is checked against the schema)

## Path parameters

- `id` string, required

## Response `200`

OK

- SubscriptionBenefitBalancesDto
  - `subscriptionId` string
  - `asOf` string, date-time
  - `balances` SubscriptionBenefitBalanceDto[]
    - `planBenefitId` string
    - `displayName` string
    - `period` string: "PlanTerm" | "Monthly".
    - `periodKey` string: The current period bucket ("term", or "month-N" from the subscription start).
    - `includedQuantity` union
      - number, double
      - string, double
    - `used` union
      - number, double
      - string, double
    - `remaining` union
      - number, double
      - string, double
  - `recentRedemptions` BenefitRedemptionDto[]: Redemption timeline, newest first (ITE-658 tracker). Capped at 25.
    - `id` string
    - `planBenefitId` string
    - `displayName` string
    - `quantity` union
      - number, double
      - string, double
    - `periodKey` string
    - `redeemedAt` string, date-time
    - `invoiceLineItemId` string, nullable
    - `reason` string, nullable: Reason on a MANUAL adjustment row (ITE-661); null for automatic redemptions.
    - `reversedAt` string, date-time, nullable: Set when the consuming invoice died (void/supersede/merge) — the row no longer counts as used.
    - `reversalReason` string, nullable

## Other responses

- `404`: Not Found

## Changes

- **2026-09-11** `503cd0546309`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/clinicos/apis/pawthosx-business-api-v1/changes/Subscriptions/:id/benefit-balances/get.md)

---

[API](https://skmtc.dev/clinicos/apis/pawthosx-business-api-v1.md) - [All operations](https://skmtc.dev/clinicos/apis/pawthosx-business-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/clinicos/apis/pawthosx-business-api-v1/revisions/099cf36186e0?raw)