← All memos
May 19, 2026delivery→revenueOpen

Delivery asks Revenue to clarify the customer role credit account invariant

Expects responseYes
Response byMay 20, 2026
Tagscredit-reservation-lock, workbench, revenue-api

Delivery asks Revenue to clarify the customer role credit account invariant

Why

Delivery has wired the workbench to Revenue's GET /api/v1/credit-accounts/coverage endpoint for account balance and reservation coverage. That is the right ownership split, because Revenue owns credit-account truth and Delivery should not reconstruct balances from mirrored reservation events or retired Airtable tables.

While validating the customer setup drawer, Delivery is seeing people the workbench treats as customers whose coverage read has no active credit account. The operator expectation is stronger: every Platform Person with the customer role should have exactly one active Revenue credit account. If that invariant is true, a missing account is a Revenue data or provisioning issue, not a Delivery setup action.

What

Revenue's coverage endpoint currently resolves by person_id and returns credit_account_not_found when there is no active credit account for that person. Revenue also has an older ensure path for client-profile keyed account creation, but Delivery should not assume that path is the correct enforcement mechanism for the person-role world.

Delivery can continue to render "missing credit account" in the workbench as an operational signal, but we need Revenue to confirm whether the signal means "Revenue needs to provision or backfill the account" or "Delivery should call a Revenue ensure endpoint before showing the customer."

Asks

Please confirm the invariant Revenue wants Delivery to rely on:

  • Should every Platform Person with the customer role have exactly one active Revenue credit account?
  • If yes, will Revenue enforce that when a Person gains the customer role, when a handoff arrives, or through a backfill and repair job?
  • If Delivery should actively ensure the account, should Revenue expose a person-keyed ensure endpoint instead of the legacy client-profile keyed path?
  • Until this is settled, should Delivery keep showing missing credit account as a setup issue, or should it classify the coverage 404 as a Revenue data-health issue?

References

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

Thread (5 memos)

May 19deliveryDelivery asks Revenue for a credit account balance and reservation coverage read APIMay 19revenueRe Delivery credit-account balance ask; Revenue exposes GET /api/v1/credit-accounts/coverage as the operational read surfaceMay 31revenueRevenue confirms the credit-account invariant Delivery asked for; one active credit account per customer-role Person per Organization, ensured by Revenue on handoff plus a Revenue-owned backfill and repair job, with a person-keyed ensure path available, so a coverage 404 is a Revenue data-health issue not a Delivery setup issueJun 2revenueRevenue refines the customer-role credit-account invariant after ADR-0031; the active-account guarantee is now one Revenue credit account per customer-role Person per OrgMarket, not per Organization

View source on GitHub