API Contract (High-Level Draft)

A behavioral draft the PM writes and engineering formalizes (e.g. into OpenAPI). It says which calls exist and what information moves in each — not field types or versioning. Illustrative only; these are not existing Chargebee endpoints.

Ingest Events

Foundation

Send usage events into the pipeline in batches.

App sends

  • Batch of events, each with a unique transaction ID, customer (or a customer alias, so senders do not need Chargebee IDs), event type, timestamp and properties

Service returns

  • Accepted or rejected per event (with reason)
  • Duplicate indication

Get Usage

Foundation

Read current usage against a meter for a customer and period.

App sends

  • Customer
  • Meter
  • Period

Service returns

  • Current usage
  • Last-updated time
  • Threshold status

Correct Usage

Foundation

Fix or remove bad usage already recorded (addresses CB-9).

App sends

  • Customer
  • Meter
  • Events or time window to correct
  • Replace or void instruction
  • Reason

Service returns

  • Corrected totals
  • Audit entry

Reserve

Crawl

Ask permission and hold an estimated amount before a metered action.

App sends

  • Customer
  • What is being metered
  • Estimated quantity
  • Unique request ID

Service returns

  • Approved or Denied (with reason), or Would-deny in shadow mode (logged, not enforced)
  • Hold reference
  • Remaining balance
  • Hold expiry

Confirm

Crawl

Settle a hold with what was actually used.

App sends

  • Hold reference
  • Actual quantity
  • Unique request ID

Service returns

  • Amount charged
  • New balance

Release

Crawl

Cancel a hold when the action failed or was abandoned.

App sends

  • Hold reference

Service returns

  • Confirmation
  • Balance restored

Get Balance

Walk

Let the app or customer see what is left.

App sends

  • Customer
  • What is being metered

Service returns

  • Current balance
  • Amount on hold
  • Low-balance flag

Supporting capabilities

Not detailed here; engineering shapes these.

  • Define meters (count, sum, max, unique count, latest).
  • Search events and read ingest status (lag, rejected events).
  • Replay or backfill raw events after a meter definition changes.
  • Configure threshold alerts and webhooks (low balance, limit reached, would-have-blocked).
  • Top-up and auto-recharge, delivered through the hosted out-of-credits page in the Walk phase.

Business rules the contract must state

  • Whether shadow mode is on by default for a new customer.
  • How long a hold lives before it auto-releases.
  • What happens when actual usage exceeds the hold (allow negative balance, or cap).
  • Repeated calls with the same request ID must be safe (no double charge).
  • What the app does if the service is unreachable — fail open or fail closed.
  • Ingest: the maximum number of events per request, and the response when a batch is partly rejected.
  • Ingest: how long a transaction ID is remembered, so a replayed event is not counted twice.
  • Ingest: how old a backdated event may be, and how a late event changes totals that have already been read.
  • Ingest: what happens to rejected events (returned with a reason, held for review, or dropped).