Skip to main content

Usage-based billing model (authorize then commit)

This model gates work in real time and records usage after the work completes.

Prereqs​

Workflow​

  1. Authorize before work: POST /mgt/v1/gate/authorize
  2. Do the protected work.
  3. Commit after work: POST /mgt/v1/gate/commits
  4. If work fails, cancel (best-effort): POST /mgt/v1/gate/cancel

What you should treat as authoritative​

  • Commit returns the authoritative priced result at commit time.
  • Pricing behavior is "floating": it uses the current price at commit time.

What to do with hints​

Common patterns:

  • pricing.not_configured: log and treat as "observable but not chargeable" until pricing is configured.
  • quota.remaining or rate.limit: implement backoff, queueing, or degradation.
  • funding.xusd_shortfall or budget.shortfall: decide your product policy (hard stop vs soft degrade).

Verify in production​

You should be able to answer these questions from logs:

  • For a given business request, what principal_id and feature_code were used?
  • Which Idempotency-Key was used for authorize and commit?
  • What hints were returned?
  • What amount was computed at commit time?

Troubleshoot​

  • 402: enforcement blocked the request (funding, quota, or budget).
  • 429: rate limit.
  • 409: idempotency conflict.

Next​