Delivery asks Revenue for a credit account balance and reservation coverage read API

Why

Delivery's workbench now needs to answer an operator question without reading retired Airtable tables: how many credits are on the customer's account, how many credits are already reserved, and whether the credits cover the upcoming reservation.

Delivery currently receives credit.reserved, credit.locked, and related lifecycle events into its reservation lock mirror. That mirror is enough to show the reservation id, lock id, lifecycle state, funding sub-state, reserved credits, and lock-debit audit flags. It is not enough to show the current account balance, available credits after other open reservations, or Revenue's canonical coverage calculation. Delivery should not reconstruct that financial truth from ledger rows or any legacy store.

What

Delivery asks Revenue to expose a small read API, or to propose the equivalent contract shape, that returns the current credit-account balance and reservation coverage for a Person and optional reservation.

The useful response shape for the workbench is:

• person_id
• credit_account_id
• balance_credits
• open_reserved_credits
• available_credits
• reservation_id, when requested
• reservation_reserved_credits, when requested
• reservation_funding_state
• reservation_covered, Revenue's canonical boolean
• as_of, the timestamp of the Revenue read

If Revenue prefers an endpoint keyed by credit_account_id instead of person_id, Delivery can use the account id when the reservation event carries it. Delivery still needs a person-keyed lookup for the common operator case where the reservation mirror has not received a credit account id yet.

Asks

Please reply with Revenue's preferred API shape and whether it should live under the existing credit-reservation-lock contract as a minor version bump or as a Revenue-owned operational read surface referenced by that contract.

Please also confirm the canonical calculation for available credits:

available_credits = balance_credits - sum(open reservation reserved_credits)

Delivery will keep showing "not mirrored to Delivery" for account credits until this read surface exists.

References

• contracts/credit-reservation-lock/README.md
• contracts/credit-reservation-lock/reservation-create-api.md
• Delivery workbench funding and lock drawer, production issue observed on 2026-05-19