Usage Receipts for OpenAI-Compatible SDK Cost Rows (September 2026)

[chawkian]

One gap I keep seeing in OpenAI-compatible SDK discussions is the missing post-call receipt.

The client sends a request, the gateway returns a response, and the dashboard eventually shows a cost row. That may be enough for a small demo. It is not enough for a team that has to explain a production run to engineering, support, and finance a week later.

A useful SDK receipt is not a full billing system. It is a compact record that links one application request to the route, pricing snapshot, account group, token buckets, retry behavior, and final status that the gateway used. The important point is that the receipt should be exportable by the application at the same time it handles the response. If the only durable evidence lives in a later dashboard view, the application cannot easily attach cost evidence to its own job logs.

I checked AIWave's live pricing endpoint for this discussion on Sep 2, 2026. The /api/pricing response returned success=true, 63 route records, pricing version a42d372ccf0b5dd13ecf71203521f9d2, auto_groups=["default"], and group ratios of default=3 and vip=1. A few route fields from that same snapshot were:

Model	model_ratio	completion_ratio	cache_ratio	Enabled groups
MiniMax-M2.7	0.22652	4	0.2	default, vip, svip
step-3.7-flash	0.2	6	0.2	default, vip, svip
ernie-5.0	1.232877	3.7778	0.1	default, vip, svip
xiaomi/mimo-v2.5-pro	0.7810988945590882	3	absent	default, vip, svip

Those are gateway catalog fields, not a promise that every application request will produce the same debit. They are exactly why the receipt matters. The cost row depends on route, token counts, cache classification, account group, and the pricing version in force when the gateway accepted the request.

The receipt I would want from an SDK looks like this:

{
  "request_id": "req_01J_receipt_example",
  "idempotency_key": "job_42_step_3",
  "endpoint_family": "chat_completions",
  "requested_model": "MiniMax-M2.7",
  "served_model": "MiniMax-M2.7",
  "pricing_version": "a42d372ccf0b5dd13ecf71203521f9d2",
  "effective_group": "vip",
  "input_tokens": 18400,
  "cache_hit_input_tokens": 11200,
  "output_tokens": 980,
  "retry_count": 1,
  "final_status": "success"
}

The receipt should avoid raw prompts, raw outputs, API keys, and customer-identifying fields. A request ledger can be useful without becoming a content archive. For most SDK integrations, the application needs cost evidence, not user text.

There are a few practical rules I would add.

First, include both requested_model and served_model. If the request used an alias, the receipt should show the alias and the resolved route. If the request used an exact model id, both fields may match. Either way, the application should not have to infer which route ran.

Second, include pricing_version even when the gateway has not changed pricing recently. This makes the receipt stable across later catalog edits. It also lets CI compare a known fixture against the current catalog and decide whether a test failure is caused by code, model behavior, or a changed rate card.

Third, record retry behavior beside cost fields. Retries are where SDK and gateway accounting often get mixed together. If the first attempt failed before execution and the second attempt succeeded, the receipt should make that visible. If two attempts both reached the model provider, the application needs to know that too.

Fourth, keep the schema boring. A receipt should be easy to write to JSONL, easy to redact, and easy to join against job logs. This is not a place for a clever object hierarchy.

For aiwave-sdk-python, I would consider an opt-in hook that returns the receipt next to the normal response object, or emits it through a callback:

response = client.chat.completions.create(
    model="MiniMax-M2.7",
    messages=[{"role": "user", "content": "Return a short migration checklist."}],
    temperature=0,
    extra_headers={"Idempotency-Key": "job_42_step_3"},
)

receipt = response.aiwave_usage_receipt

The open question is where this belongs in an OpenAI-compatible SDK. Should usage receipts be a first-class extension on the response object, a callback for applications that already have job ledgers, or a separate export API that developers call after the request completes?