Billing operations
Multi-Provider AI Invoice Reconciliation for SaaS Teams
A practical reconciliation checklist for SaaS teams matching OpenAI-compatible gateway usage records against multiple AI provider invoices, currencies, token prices, customer charges, and customer usage exports.
Why reconciliation gets messy after the first provider
Most AI products can explain early spend by opening one provider dashboard and checking total tokens. That breaks when production traffic uses several model providers, fallback rules, cached-token pricing, customer API keys, prepaid balances, and different invoice periods. Finance sees provider invoices; product sees customer usage; engineering sees traces. Reconciliation is the work of proving that all three views describe the same requests.
An OpenAI-compatible gateway is the best place to create the shared record because every request already passes through it before provider routing, retry, fallback, quota checks, and customer charging.
Reconciliation data you need per request
| Field group | Examples | Why it matters |
|---|---|---|
| Gateway identity | request_id, trace_id, idempotency_key | Deduplicates retries and ties application logs to provider records. |
| Customer owner | tenant_id, workspace_id, api_key_id, feature | Maps provider spend back to the customer, plan, or product surface that caused it. |
| Provider call | provider, provider_request_id, served_model, region | Lets finance match gateway usage to provider invoice rows and support tickets. |
| Usage quantities | input_tokens, output_tokens, cached_tokens, image_units | Preserves the unit basis for token, multimodal, and cached-context pricing. |
| Pricing version | provider_price_version, customer_price_version, exchange_rate_id | Prevents historical usage from changing when provider pricing or currency rates change later. |
| Billing outcome | provider_cost_usd, customer_charge_usd, balance_delta, invoice_period | Separates what the business paid from what the customer was charged or allowed. |
Daily reconciliation workflow
- Close the gateway usage window: freeze a UTC time range and export all billable, free, failed-after-provider, and retried requests.
- Normalize provider units: convert each provider's token, cached-token, image, embedding, and request units into a common schema.
- Join by provider request id: match exact provider ids where available, then use timestamp/model/token tolerance only for records missing ids.
- Compare cost and quantity: flag mismatches by provider, model, customer, and route instead of only checking one global total.
- Separate commercial charge: apply customer price tables, plan allowances, coupons, prepaid balances, and internal/test exemptions after provider cost is verified.
- Publish exceptions: send engineering a short list of missing ids, unexpected model substitutions, duplicate retries, and unpriced usage.
Exception categories to track
| Exception | Likely cause | Resolution |
|---|---|---|
| Provider invoice has usage missing from gateway records | Direct provider key usage, health checks outside the gateway, or logging failure. | Block unmanaged provider keys and route all production calls through the gateway. |
| Gateway has usage missing from provider invoice | Late invoice export, non-billable trial model, cached invoice delay, or failed pre-provider request. | Mark the invoice status and recheck after provider billing finalizes. |
| Cost differs but tokens match | Wrong price table version, cached-token discount, currency conversion, or model alias change. | Version provider prices and store the resolved model, not only the requested model. |
| Customer charge differs from provider cost | Expected markup, plan allowance, prepaid credit, coupon, or enterprise discount. | Keep provider_cost, customer_charge, and allowance_applied as separate fields. |
| Duplicate customer charge | Retry without idempotency or settlement replay. | Use gateway request ids and append-only ledger entries with idempotent settlement. |
Month-end controls
- Lock provider price tables before generating customer invoice exports.
- Confirm every production provider key maps to a gateway route or explicit internal cost center.
- Sample high-cost customer invoices and trace each line back to provider calls.
- Review fallback-driven cost increases separately from normal usage growth.
- Export unresolved exceptions with owner, severity, and whether customer billing should wait.
How this fits with FerryAPI architecture
FerryAPI focuses on the gateway layer that SaaS teams need before AI billing becomes reliable: OpenAI-compatible requests, customer API keys, tenant quotas, prepaid balances, model routing, and usage records that survive reconciliation. The goal is not just cheaper model access; it is a billing trail that finance, support, and engineering can all trust.
Related FerryAPI guides: AI API usage attribution schema, LLM prepaid balance implementation, model routing vs. fallback, and OpenRouter alternatives for SaaS billing.
Related: AI API usage ledger design explains how to make gateway usage events durable enough for billing, refunds, and provider invoice reconciliation.
Related: AI API cost anomaly detection runbook helps catch provider-cost spikes before the monthly invoice reconciliation step.
FerryAPI helps SaaS teams route model requests, manage customer API keys, enforce quotas, and track multi-provider AI usage for billing. Explore FerryAPI.