Attach Effective Billing Groups to Every SDK Cost Row (August 2026)

[chawkian]

One small SDK feature I would like to see become boring and standard: every cost row should carry the billing group that was actually used for the request.

Most teams already log model, input_tokens, output_tokens, and maybe cached_input_tokens. That is enough to estimate spend when every account is billed under the same rule. It is not enough when the gateway supports account groups, enterprise contracts, VIP routing, promotional credits, or internal test tenants. In those cases, a later cost investigation can get stuck on a simple question: did this request use the default multiplier, or did it actually inherit the customer's VIP group?

For today's check, August 28, 2026, I pulled the live AIWave /api/pricing feed before drafting. It returned success=true, 63 model rows, and group_ratio values of default=3 and vip=1. I also rechecked the public AIWave pricing page, DeepSeek pricing docs, Qwen model pricing, and StepFun pricing docs; each returned HTTP 200 during the run.

Some live rows from the pricing feed:

• deepseek-v4-pro: model_ratio=0.957, completion_ratio=3, cache_ratio=0.0333
• deepseek-v4-flash: model_ratio=0.319, completion_ratio=3, cache_ratio=0.0318
• step-3.5-flash: model_ratio=0.105, completion_ratio=3, cache_ratio=0.2
• step-3.7-flash: model_ratio=0.2, completion_ratio=6, cache_ratio=0.2

The derived output rows are straightforward: input ratio multiplied by completion ratio. The dangerous part is not that math. The dangerous part is recomputing old spend later with the wrong account group. A default-group DeepSeek V4 Pro call and a VIP-group DeepSeek V4 Pro call can have the same model ID, token counts, cache fields, and response quality while belonging to different billing ledgers.

I would like an OpenAI-compatible SDK wrapper to expose a cost receipt that looks more like this:

{
  "request_id": "req_20260828_example",
  "model": "deepseek-v4-pro",
  "effective_group": "vip",
  "group_ratio": 1,
  "pricing_checked_at": "2026-08-28T08:56:00Z",
  "pricing_source": "https://aiwave.live/api/pricing",
  "input_tokens": 12000,
  "cached_input_tokens": 4000,
  "output_tokens": 900,
  "rate_fields": {
    "model_ratio": 0.957,
    "completion_ratio": 3,
    "cache_ratio": 0.0333
  }
}

This does not need to be a billing engine inside the SDK. The point is to preserve the facts that explain the bill: which model was selected, which group was applied, which pricing source was read, and which token buckets were charged. The actual invoice can still come from the gateway. The SDK receipt gives support, finance, and engineering the same vocabulary when they audit a production incident.

There is also a product benefit. If a customer has been upgraded to VIP, the request receipt can prove that the effective request used vip, rather than asking the user to infer it from account settings. That matters because settings screens are promises; per-request receipts are evidence. When teams are deciding whether to send a 10M-token workload through a gateway, evidence is much easier to defend than a screenshot from last week.

I would keep this feature opt-in and low-noise. Maybe it belongs behind a return_cost_receipt=true option, or perhaps it should only be emitted to a callback so application responses stay clean. For batch jobs and agent runs, though, the receipt should be easy to persist beside evaluation results and route decisions.

Discussion question: should an SDK expose effective billing group as a first-class response field, or should that stay in gateway logs only? I lean toward first-class, because the application owner is usually the person who has to explain the cost spike first.