Re Delivery credit-account balance ask; Revenue exposes GET /api/v1/credit-accounts/coverage as the operational read surface

Why

Revenue accepts the ask. Credit-account balance, open reservation coverage, and the boolean answer to "does this reservation fit under the current credit account" are Revenue-owned commercial truth. Delivery should read them from Revenue instead of deriving them from its reservation mirror, the append-only ledger, or any retired Airtable table.

What

Revenue added a Revenue-owned operational read surface:

GET /api/v1/credit-accounts/coverage

The route uses the same Platform JWT bearer authentication as GET /api/v1/reservations/lock-states. It requires organization_id, accepts either person_id or credit_account_id, and accepts optional reservation_id.

The response shape is the one Delivery asked for:

export type CreditAccountCoverageResponse = {
  person_id: string;
  credit_account_id: string;
  balance_credits: number;
  open_reserved_credits: number;
  available_credits: number;
  reservation_id?: string;
  reservation_reserved_credits?: number;
  reservation_funding_state?: "pending_funding" | "funded" | "refunding" | "refunded" | null;
  reservation_covered?: boolean;
  as_of: string;
};

Canonical calculation confirmed:

available_credits = balance_credits - open_reserved_credits

open_reserved_credits is the sum of reservations in RESERVED and LOCKED for the resolved credit account and organization. Terminal reservations do not subtract from availability. For an open requested reservation, reservation_covered is true when the account balance covers all current open reservations, including the requested reservation.

Revenue's preference is to keep this as a Revenue-owned operational read surface, documented in revenue/docs/api/credit-account-coverage-v1/README.md, and referenced from the credit-reservation-lock contract only if the read becomes a cross-domain contract dependency beyond Delivery's workbench. The lock contract should keep owning state semantics; this endpoint owns one operational read projection over Revenue tables.

References

• Delivery request: 2026-05-19-delivery-credit-account-balance-api
• Revenue implementation docs: revenue/docs/api/credit-account-coverage-v1/README.md
• Revenue route: revenue/src/app/api/v1/credit-accounts/coverage/route.ts
• Revenue service: revenue/src/modules/credit-accounts/service.coverage-read.ts