Billing operations
AI API Customer Usage Export Schema for SaaS Teams
A practical customer usage export schema for SaaS teams selling AI features: request IDs, customer keys, model routes, tokens, cost, credits, refunds, and invoice-ready CSV fields.
Why usage exports deserve a real schema
When AI features become billable, customers eventually ask for the evidence behind the invoice. A dashboard total is not enough. Finance wants a CSV, customer success wants request IDs, developers want model and token details, and support wants to know whether retries, credits, or refunds changed the final amount.
A clear usage export schema gives every team the same source of truth. It also reduces disputes because customers can reconcile their own projects, API keys, workspaces, and time windows without opening a ticket for every billing question.
Recommended CSV columns
| Column | Purpose | Example |
|---|---|---|
request_id | Stable gateway request ID used in logs, support tickets, and the usage ledger. | req_8f3c2a |
customer_id | Your tenant, workspace, organization, or account identifier. | cus_acme |
customer_api_key_label | Safe display label for the customer key, not the secret key value. | prod-chatbot |
route_policy | The gateway routing or quota policy that selected the model/provider route. | support-standard |
model_requested | Model ID sent by the client. | gpt-4o-mini |
model_served | Actual provider/model served after routing, fallback, or downgrade policy. | qwen-plus |
input_tokens | Billable prompt/input tokens after provider normalization. | 1850 |
output_tokens | Billable completion/output tokens after provider normalization. | 420 |
gross_amount_usd | Amount before credits, refunds, or plan discounts. | 0.0184 |
net_amount_usd | Final amount charged to the customer balance or invoice. | 0.0129 |
settlement_status | Whether the request was charged, credited, refunded, voided, or still pending. | charged |
created_at | UTC timestamp for export filtering and invoice reconciliation. | 2026-06-04T14:33:10Z |
Do not export secrets or raw prompts by default
Usage exports should be useful without leaking sensitive data. Avoid exporting full API keys, provider credentials, raw prompts, raw tool payloads, customer PII, or internal provider account IDs. If enterprise customers need prompt-level audit exports, put that behind a separate permission model, retention policy, and redaction review.
For normal billing exports, safe labels and correlation IDs are enough. A customer should be able to answer “which workspace, key, route, and feature caused this spend?” without receiving private request content.
Handle retries, fallback, and refunds explicitly
AI gateways often transform one customer request into multiple provider attempts. The export should not hide that complexity, but it should present a clean billable result. Keep provider-attempt details in the internal usage ledger, then expose a customer-friendly row for the settled request.
If a request failed after reservation, mark the settlement outcome clearly and connect it to your refund policy for failed LLM requests. If a fallback model was used, show both requested and served model fields so customers understand why cost or output behavior changed.
Example export row
request_id,customer_id,customer_api_key_label,route_policy,model_requested,model_served,input_tokens,output_tokens,gross_amount_usd,net_amount_usd,settlement_status,created_at
req_8f3c2a,cus_acme,prod-chatbot,support-standard,gpt-4o-mini,qwen-plus,1850,420,0.0184,0.0129,charged,2026-06-04T14:33:10ZOperational checklist
- Export only settled rows by default; offer a separate “pending usage” view if reservations matter to prepaid balance customers.
- Use UTC timestamps and document the invoice timezone separately.
- Keep customer-facing policy names stable across releases.
- Include request IDs that match support logs, rate limit headers, and billing events.
- Make refunds and credits visible as explicit settlement outcomes instead of silently adjusting totals.
- Version the schema so finance exports do not break downstream customer workflows.
How FerryAPI helps
FerryAPI is an OpenAI-compatible AI API gateway for customer API keys, model routing, quotas, prepaid balances, request IDs, and usage billing. Keeping usage export fields close to the gateway makes invoices easier to explain and support tickets easier to resolve.
Use FerryAPI to centralize customer API keys, model routes, token usage, credits, refunds, and billing-ready request records.
Related: when exports trigger customer questions, AI API admin audit logs help explain quota edits, routing changes, credits, and manual adjustments.