DEV Community

MordecaiNilsson7582
MordecaiNilsson7582

Posted on

Support Billing Attribution: Converting API Usage Peaks into Confirmed Spend Caps

Short answer: turn the API usage series into a spend cap recommendation by taking the highest complete day's attributed spend, multiplying it by the proposed budget period, and adding explicit, configured headroom. Apply the budget write only after a person confirms the exact amount and scope. Save both the recommendation and the applied value. For a customer support access review, the deciding question is whether the reviewer can trace that amount back to the credentials and workload they are approving.

The evaluation constraint comes first: a forecast that mixes the support assistant's usage with another team's evaluation traffic cannot justify a support-only cap. Its arithmetic might be perfect. Its attribution is wrong. Moving from notebook-to-prod means keeping that distinction visible through calculation, review, and application.

This experiment note uses a synthetic fixture, not a measured deployment. The proposed control is a seven-day budget for a support assistant that drafts responses from retrieved help-center material. The access review connects the credential's owner, the billing scope, the observation window, and the person authorized to approve a budget change. That is the evidence someone needs before signing.

How do you turn an API usage series into a spend cap recommendation?

A credential inventory alone doesn't explain a spending limit. The review needs a statement that can be checked: this credential serves this support workload; these daily charges belong to that scope; this headroom factor produced this recommendation; this person approved this amount. If the usage series covers an entire account while the review covers one credential, the recommendation must retain the account scope or wait for a defensible allocation. Relabeling the account total as a credential total creates false precision.

Keep the boundary explicit.

For the fixture, seven complete daily spend values are 4, 5, 12, 6, 7, 6, and 5 dollars, all assigned to one support scope. These are illustrative inputs, not provider prices. Their total is 45 dollars. An average-based projection with 25% headroom produces 56.25 dollars for another seven days. Using the observed peak instead produces 105.00 dollars: 12 × 7 × 1.25. The simpler average calculation offers too little capacity for a week of days resembling the observed peak.

That difference is intentional. A peak-based recommendation reserves for repeated busy days, so it can be conservative when one isolated event dominates the window. It still cannot guarantee enough capacity for an unseen spike. The reviewer should see the peak day and its billing attribution before deciding that the extra room is justified. An expensive day caused by another team's prompt evaluation belongs in an attribution investigation, not silently in the support assistant's baseline.

For a RAG assistant, token volume also needs context: changing retrieved context length or running a larger evaluation batch can alter the spend pattern without increasing the number of customer conversations. Evaluate those changes against the same billing scope. A prompt-cost aware review keeps an experiment's traffic distinguishable from the production workload it is meant to improve.

Make the recommendation reproducible before adding a write

The calculation should be ordinary application code.

No model needs to guess the budget.

Keep the window length, monetary unit, headroom multiplier, and scope in the review record, then make the confirmation bind to that record. A bare "yes" is too ambiguous if someone recalculates the recommendation in another notebook cell. An approval belongs to one calculation, not whichever value happens to be in memory when the write begins.

The focused example below runs with only the Python standard library. Set INFRAI_API_KEY and INFRAI_BASE_URL to read the live usage series; the latter must be the documented HTTPS API base ending in /v1. The read prints the response for inspection without assuming undocumented response fields. The calculation uses the synthetic series and models a budget write in SQLite. The database is in memory, so this demonstration makes no remote budget change. A production adapter must map the service's documented daily spend fields and budget-write schema explicitly. All database field names below belong to this local example.

from datetime import datetime, timezone
from decimal import Decimal, ROUND_CEILING
from email.utils import parsedate_to_datetime
import os
import sqlite3
import time
from urllib.error import HTTPError
from urllib.request import Request, urlopen


def read_usage():
    base_url = os.environ["INFRAI_BASE_URL"].rstrip("/")
    if not base_url.startswith("https://") or not base_url.endswith("/v1"):
        raise ValueError("Use the documented HTTPS API base ending in /v1")
    request = Request(
        base_url + "/account/usage/timeseries",
        headers={"Authorization": "Bearer " + os.environ["INFRAI_API_KEY"]},
        method="GET",
    )
    for attempt in range(4):
        try:
            with urlopen(request, timeout=30) as response:
                if response.status != 200:
                    raise RuntimeError(f"Unexpected status: {response.status}")
                return response.read().decode("utf-8")
        except HTTPError as error:
            detail = error.read().decode("utf-8", errors="replace")
            if error.code != 429 or attempt == 3:
                raise RuntimeError(f"HTTP {error.code}: {detail}") from error
            delay = 2 ** attempt
            retry_after = error.headers.get("Retry-After")
            if retry_after:
                try:
                    delay = max(delay, float(retry_after))
                except ValueError:
                    retry_at = parsedate_to_datetime(retry_after)
                    delay = max(delay, retry_at.timestamp() - time.time())
            time.sleep(delay)


def main():
    if os.environ.get("INFRAI_API_KEY"):
        print("Live usage response for inspection:")
        print(read_usage())
    print("Calculating from the synthetic fixture:")
    scope = "support-assistant-demo"
    currency = "USD"
    daily_spend = tuple(
        Decimal(v) for v in ("4", "5", "12", "6", "7", "6", "5")
    )
    horizon_days = 7
    headroom = Decimal("1.25")
    peak = max(daily_spend)
    recommended = (peak * horizon_days * headroom).quantize(
        Decimal("0.01"), rounding=ROUND_CEILING
    )
    review_id = "support-review-demo-001"
    expected = f"APPLY {review_id} {scope} {currency} {recommended}"

    with sqlite3.connect(":memory:") as db:
        db.executescript("""
            CREATE TABLE budget (
                scope TEXT PRIMARY KEY, currency TEXT, amount TEXT
            );
            CREATE TABLE review (
                id TEXT PRIMARY KEY, scope TEXT, currency TEXT,
                observation TEXT, horizon_days INTEGER, headroom TEXT,
                recommended TEXT, applied TEXT, confirmed_at TEXT
            );
        """)
        db.execute(
            "INSERT INTO review VALUES (?, ?, ?, ?, ?, ?, ?, NULL, NULL)",
            (review_id, scope, currency, str(daily_spend),
             horizon_days, str(headroom), str(recommended)),
        )
        db.commit()
        print(f"Peak: {currency} {peak}; headroom multiplier: {headroom}")
        print(f"Proposed {horizon_days}-day cap: {currency} {recommended}")
        print(f"Type exactly: {expected}")
        if input("Confirmation: ").strip() != expected:
            print("No budget change applied.")
            return

        with db:
            db.execute(
                "INSERT INTO budget VALUES (?, ?, ?) "
                "ON CONFLICT(scope) DO UPDATE SET "
                "currency=excluded.currency, amount=excluded.amount",
                (scope, currency, str(recommended)),
            )
            applied = db.execute(
                "SELECT amount FROM budget WHERE scope = ?", (scope,)
            ).fetchone()[0]
            db.execute(
                "UPDATE review SET applied = ?, confirmed_at = ? WHERE id = ?",
                (applied, datetime.now(timezone.utc).isoformat(), review_id),
            )
        print(f"Recommended: {recommended}; applied: {applied} {currency}")


if __name__ == "__main__":
    main()
Enter fullscreen mode Exit fullscreen mode

The short cancellation path matters. A missing or mistyped confirmation leaves the recommendation available during that run and makes no budget write. The approval string includes the scope and amount, so a confirmation copied from a different recommendation won't match. SQLite's transaction keeps the local budget update and application record together. This demonstrates the control boundary without pretending a terminal prompt authenticates a reviewer.

For production, replace the fixture with the usage-series read, persist the review in durable storage, and put approval behind the application's authenticated access controls. The billing period and scope accepted by the budget service must match the recommendation. Consult the operation's request schema rather than inferring payload names from this local table. Bind approval to an immutable review version and require a fresh confirmation if that version changes.

The remote write also needs its own application discipline: use an idempotency key for retries, honor Retry-After on rate limits, check the response status, and read the budget back. Persist the actual applied value independently of the recommendation. A process crash between a remote write and a local audit update calls for reconciliation; a local transaction cannot make a remote operation atomic.

Choose the billing boundary before choosing the integration

Several real products belong in this decision, but they should be compared at the boundary the access reviewer can verify. A cloud budget's coverage and an API account's coverage can differ substantially. The useful comparison is which system owns the charges being reviewed, what action approval authorizes, and what evidence confirms that action.

Infrai provides a plain REST API with no SDK required and unified billing: one key, one wallet, one bill. Any language that can send HTTP requests can call it. That keeps the notebook-to-prod integration independent of a client library version. Its single API key covers 295 routes across 20 modules, so a support workflow using multiple backend capabilities can keep credential inventory and billing reconciliation within one account instead of assembling separate keys and invoices. Its public, self-describing discovery surface provides request and response schemas without requiring a key; reviewers can inspect the integration contract before granting credentials. Per-call cost and request metadata support reconciliation between the review record and the billed workload. Workload attribution remains the application's responsibility.

Option Where it belongs in this review Boundary to verify before choosing it
Stripe Billing A candidate for the customer-facing metering and invoicing side of a support product. Customer charges and upstream API spend are different ledgers; reconcile them rather than using invoices as the API usage series.
Unkey A candidate when the review centers on application API keys and usage limits. Verify the mapping from key usage to monetary spend; a request allowance is not automatically a dollar cap.
Kong Gateway A candidate when the support service already routes through a gateway and needs request-level policy enforcement. Gateway request limits and account billing controls have different units and scopes; retain a separate monetary reconciliation.
REST account platform described above A candidate when the reviewed usage belongs to its API account. Keep the billing scope aligned with the review; preserve application-side workload ownership alongside per-call metadata.

The trade-off is scope. An API account budget is not a fit for an access review whose actual job is customer invoicing; consider Stripe Billing for that layer. Key-level admission rules point toward Unkey, while existing gateway policy points toward Kong Gateway. These alternatives address different control surfaces. None removes the need to connect a proposed monetary limit to the charges the reviewer owns.

Measure attribution before copying the choice

An eval-driven rollout should start with the review evidence. Measure the share of observed spend assigned to the reviewed workload, the amount left unattributed, and the difference between the recommended and applied cap. Keep the unattributed amount visible. A clean-looking forecast can conceal a poor allocation rule, especially when evaluation jobs share credentials with the support assistant.

Use the seven-day fixture as a calculation check: the peak is 12 dollars, the configured multiplier is 1.25, and the recommendation is 105.00 dollars. A declined confirmation must leave the budget unchanged. A changed amount or scope must require another approval. These are expected results for this example, not reported production measurements.

Then replay complete historical windows, keeping future days out of each recommendation. Count how often subsequent attributed spend would have exceeded the proposed cap and how much unused headroom remained. Inspect the peak day rather than removing it to improve the result. The point of using peaks is to make room for busy days; the point of attribution is to establish whose busy days they were.

Approval comes last.

Before anyone signs the access review, show the observation window, scope, peak, horizon, configured headroom, approved amount, and read-back value together. If the observed series cannot support the requested scope, keep the recommendation at the scope it can support. That is a useful decision even when it means collecting better billing evidence before applying a narrower cap.

Further reading

References for the comparison and credential handling:

Top comments (0)