Skip to main content

Record usage and issue corrections

Wallet is a read model. Usage and value issuance enter the accounting system through their domain workflows rather than direct wallet mutations.

Prereqs​

  • You can obtain a bearer token for the principal.
  • You understand idempotency: Operational safety.

Record usage​

Use Gate commit when an authorized runtime operation completes, or ingest a billing event when usage is rated asynchronously. Both paths produce rating allocations and settlement records that feed the wallet snapshot.

Do not reject an operation solely because its estimated cost exceeds the displayed balance. Estimates are advisory; authorize uses the current authoritative available_balance, while settlement applies actual rated usage.

Issue value​

Use one of these auditable sources:

  • a billing-plan grant
  • a subscription or top-up purchase grant
  • a campaign grant
  • an explicit one-time operator grant

Each grant resolves an outstanding_application_policy at issuance. Committed fallback reservations reduce spendability immediately. Grants with apply_to_outstanding offset settled outstanding usage at issuance and on later background grant sweeps; promotional grants normally use never.

Corrections​

Correct the source rating or issue an auditable operator grant. Always:

  • require an explicit reason
  • log actor and correlation ids
  • process idempotently

Troubleshoot​

  • A zero available_balance can deny a prepaid billable request.
  • Postpaid and hybrid modes can continue and accrue outstanding_balance.
  • 409 indicates an idempotency conflict in the originating workflow.

Next​