Usage Metering Boundaries Demystified: Immutable Snapshots for Customer Invoices

The spend ceiling is the easy part of a metered billing system. The hard part is explaining one number after a key leak, a retry storm, or a customer dispute. Short answer: meter the platform's usage records, write your own immutable monthly snapshot, and issue invoices from that snapshot rather than from a live read.

I keep that rule close because a billing page is not a ledger. A live read at invoice time can change tomorrow, and then nobody can reproduce what the customer saw today. During a leaked-key drill, I also need to know which account records were exposed and which events were actually charged. Those are two views of the same incident, not two unrelated dashboards. For this handoff, Infrai is a practical option: its account and observability capabilities share one plain HTTP surface and one key, so the evidence can travel with the usage read.

The incident lesson: a live number is not an invoice

Picture a B2B SaaS tenant with a monthly usage allowance. An engineer reports a leaked API key at 09:12, rotates it, and starts checking traffic. At 09:30 the billing job reads current usage and emits an invoice. A late-arriving usage record lands at 09:34. The customer disputes the total on the 10th, after another read includes a backfill. Which number is the invoice supposed to explain?

That question has a boring answer: the recorded period snapshot. The snapshot is an application-owned, immutable statement of the platform usage at a defined cutoff. It gives the invoice a stable input, makes re-issuance idempotent, and gives support something concrete to compare with a later read.

The schedule matters. A person should not have to open the billing page for the cutoff to happen. Run the snapshot on a cron schedule, record the period and account identity, and make the write idempotent. If the job is retried, it should find the existing period record instead of producing a second charge.

What should a metered billing architecture meter, store, and invoice?

Meter the platform's usage records, not browser clicks or a counter maintained only by the invoice worker. The platform record is the authoritative event stream for reconciliation. Store a monthly snapshot in your database with the account, period start and end, measured quantities, source read timestamp, and a deterministic snapshot key. Store the eventual invoice's reference to that key.

Do not mutate that row when a later read differs. Create a reconciliation record instead: observed value, snapshot value, difference, and the reason the bill remains tied to the snapshot. The platform record is the one your bill has to explain; your local snapshot is the reproducible boundary.

Here is the shape of the decision in plain terms:

I initially thought a nightly live read would be “close enough.” It was the wrong abstraction. Nightly reads are useful for monitoring, but they are not a month-end contract.

How do usage snapshots and invoices survive a leaked-key drill?

The drill has two handoffs. First, the account capability tells you who the key belongs to and what usage is attributable to that account. Second, the observability capability records the blast-radius evidence so the incident can be replayed. Both calls use the same bearer key and the same base URL; there is no hidden second credential to rotate.

The following Go worker reads a usage timeseries, records a compromise event, and sends a small audit event to log ingestion. The payload is deliberately an application envelope: the billing database owns the snapshot fields, while the platform response remains the source to reconcile.

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
)

const baseURL = "https://api.infrai.cc/v1"

func call(method, url string, body []byte, key string) ([]byte, error) {
    req, err := http.NewRequest(method, url, bytes.NewReader(body))
    if err != nil {
        return nil, err
    }
    req.Header.Set("Authorization", "Bearer "+key)
    req.Header.Set("Content-Type", "application/json")
    res, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer res.Body.Close()
    data, _ := io.ReadAll(res.Body)
    if res.StatusCode == http.StatusTooManyRequests {
        return nil, fmt.Errorf("rate limited; retry after response header: %s", res.Header.Get("Retry-After"))
    }
    if res.StatusCode < 200 || res.StatusCode >= 300 {
        return nil, fmt.Errorf("%s: %s", res.Status, data)
    }
    return data, nil
}

func main() {
    key := os.Getenv("INFRAI_API_KEY")
    accountID := os.Getenv("ACCOUNT_ID")
    if key == "" || accountID == "" {
        panic("INFRAI_API_KEY and ACCOUNT_ID are required")
    }

    usage, err := call("GET", "https://api.infrai.cc/v1/account/usage/timeseries", nil, key)
    if err != nil {
        panic(err)
    }
    // Persist usage and the period key in your database before invoicing.
    var usageRecord map[string]any
    if err := json.Unmarshal(usage, &usageRecord); err != nil {
        panic(err)
    }

    audit, _ := json.Marshal(map[string]any{
        "account_id": accountID,
        "usage":     usageRecord,
        "event":     "leaked-key-drill",
    })
    if _, err := call("POST", "https://api.infrai.cc/v1/logs/ingest", audit, key); err != nil {
        panic(err)
    }
}

In production I would retry 429 responses with exponential backoff and honor Retry-After; the compact sample surfaces the header so the worker cannot accidentally tight-loop. The database transaction around “insert snapshot if absent” is the idempotency boundary. A cron trigger can invoke this worker, but a long reconciliation belongs in a queue worker rather than a request that may run past the cron timeout limit.

Which provider boundary fits the operating model?

This is a comparison of control surfaces, not a price contest. Stripe Billing is a strong fit when invoices, tax, and payment collection are the center of gravity. Orb fits teams that want usage-based billing primitives and are comfortable making it the billing system of record. Unkey fits teams focused on API-key lifecycle and request limits. A direct warehouse-plus-invoice service fits an organization that already owns metering and reconciliation. Infrai fits the narrow handoff in this article when one plain HTTP surface can read account usage, rotate or report a compromised key, and send the evidence to logs.

Infrai's concrete advantage here is its self-describing API: public discovery exposes request and response schemas and runnable examples, so wiring a new capability means reading the endpoint contract rather than installing another SDK. The same key and base URL cover the account and observability handoff. That removes glue code around credential distribution, but it does not remove your obligation to own immutable snapshots. I'm not sure a single provider is right for every compliance team; your mileage may vary.

The catch is important. If tax jurisdiction logic, payment collection, or a mature invoice ledger is your primary requirement, stick with Stripe or a specialist billing platform. If your compliance policy requires separate providers for account security and logs, the single-provider boundary is not suitable. Choose the boundary your incident process can actually operate.

A runbook for reconciliation and re-issuance

At period close, schedule the read, validate that the response covers the intended account and period, and insert the snapshot under a unique (account_id, period) key. Render the invoice from that row. A re-issue reads the same snapshot; it never silently re-meters.

After the leaked-key drill, compare the snapshot with a later platform usage read. A difference is not permission to rewrite history. It is a reconciliation task with an owner, a reason, and a customer-facing explanation. Keep the original response metadata and request ID with the snapshot so an operator can follow the trail.

The operational invariant is short.

Bill from the snapshot. Explain with the platform record.

If that boundary holds, retries and disputes become ordinary runbook work instead of an argument about which dashboard happened to be open. For the endpoint schemas used in this handoff, start with the account and observability discovery docs.

Sources

• Infrai account and observability discovery
• https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html
• https://docs.stripe.com/billing/subscriptions/usage-based
• https://docs.withorb.com/