Per-Customer AI Usage Metering: Build Billing Evidence for Embedded AI Features

Per-customer AI usage metering is the operating system behind fair billing for embedded AI features. If a support copilot, document analyzer, image generator, or workflow agent runs inside your product, the model invoice does not tell you which customer caused which spend, which feature created the demand, or whether a disputed line item should be credited.

That gap gets expensive quickly. Provider dashboards can show usage by project, API key, user, model, line item, or day. Gateways can preserve metadata, logs, token counts, status, and cost. Billing systems can receive usage events with customer IDs, values, timestamps, and idempotency keys. But none of those pieces becomes billing evidence until your application stamps the right customer context on each AI request and reconciles the chain before the invoice closes.

Flatkey matters in this workflow because the public site positions flatkey.ai as one API key for GPT, Claude, Gemini, DeepSeek, image, audio, and video models, with pricing, usage analytics, cost controls, and one invoice across providers. Treat that as the unified access and review surface. Do not treat it as a substitute for your own customer attribution contract. Before production billing, verify the exact dashboard fields, request logs, export behavior, model catalog, pricing units, and retention settings in your current Flatkey account.

Per-Customer AI Usage Metering: The Short Version

Per-customer AI usage metering should answer four questions for every embedded AI feature:

| Question | Evidence field | Why it matters | |---|---|---| | Which customer caused the request? | customer_meter_id or hashed tenant ID | Supports billing, credits, and customer-level limits | | Which feature created the usage? | feature_id, route, workflow, or SKU | Separates chat, search, summaries, agents, and background jobs | | What did the AI call consume? | model, input tokens, output tokens, request count, cache tokens, media units | Converts usage into provider and invoice units | | Can finance defend the charge? | request ID, timestamp, billing period, pricing version, meter event ID, reconciliation status | Supports audit trails and dispute review |

The useful pattern is not "log everything." The pattern is privacy-safe customer attribution, durable request evidence, and controlled rollups into billing-meter events. That is how per-customer AI usage metering turns embedded AI from a gross-margin surprise into a reviewable product line.

Why Team-Level Usage Is Not Enough

Team-level usage tracking helps engineering manage spend, but it is too coarse for embedded AI billing. A single production API key can mix traffic from free trials, paid customers, internal staff, demo accounts, retries, background indexing, and test fixtures. If you only group by team or environment, the invoice conversation becomes guesswork.

Customer-level attribution becomes necessary when:

• You bundle AI credits into paid plans.
• You charge overages for premium AI usage.
• Sales promises customer-specific credits or caps.
• Procurement asks how AI usage appears on invoices.
• A customer disputes a charge or says a feature was not used.
• Support needs to explain why one tenant crossed a quota.
• Finance needs gross margin by account, segment, or feature.

Per-customer AI usage metering does not require sending personal data to the AI provider. In fact, it should avoid that. The customer key you meter should usually be an internal billing-safe identifier, such as cust_meter_8f2a9c, not an email address, company name, prompt, or end-user name.

Build The Customer Metering Contract First

The metering contract is the small set of fields every AI request must carry before it reaches the gateway or provider. Keep it stable, boring, and auditable.

| Field | Example | Rule | |---|---|---| | customer_meter_id | cust_8f2a9c | Internal customer or tenant ID, pseudonymous when possible | | billing_account_id | acct_2041 | Account that owns the invoice, not necessarily the end user | | feature_id | support_summary | Product feature or billable SKU | | environment | prod | Separate production from staging and test traffic | | request_id | req_01HX... | Unique app request ID for replay and support | | idempotency_key | meter_01HX... | Unique meter event key so retries do not double bill | | model_requested | gpt-4o-mini or gateway alias | What the app asked for | | model_served | actual model after routing | What actually ran, when available | | unit_basis | tokens, requests, seconds, images | The unit that will roll into billing | | pricing_version | ai-plan-2026-07 | Version used for customer-facing calculation | | privacy_mode | metadata_only | Whether prompt/output payloads are retained |

This contract should be created by the product and finance teams together. Engineering owns capture quality; finance owns billing interpretation; support owns the explanation customers will hear.

Stamp Metadata Before The AI Call Leaves Your App

The safest place to add customer context is the service boundary that already knows the authenticated tenant and feature. Do not ask frontend clients to send customer IDs as trusted billing evidence. The backend should derive the customer meter ID from the session, tenant, entitlement, or job owner.

type AiMeteringContext = {
  customerMeterId: string;
  billingAccountId: string;
  featureId: "support_summary" | "contract_review" | "agent_run";
  environment: "prod" | "staging" | "dev";
  requestId: string;
  pricingVersion: string;
};

function buildAiMetadata(ctx: AiMeteringContext) {
  return {
    customer_meter_id: ctx.customerMeterId,
    billing_account_id: ctx.billingAccountId,
    feature_id: ctx.featureId,
    environment: ctx.environment,
    app_request_id: ctx.requestId,
    pricing_version: ctx.pricingVersion,
  };
}

The exact transport depends on your gateway and SDK. Cloudflare AI Gateway, for example, documents custom metadata for request tagging and says metadata values appear in logs for search and filtering. Its logging docs also describe metadata-only logging when cf-aig-collect-log-payload: false is used, keeping token counts, model, provider, status code, cost, and duration while skipping raw prompt and response payloads. Vercel AI Gateway documents user and tag fields for reporting, plus headers such as ai-reporting-user and ai-reporting-tags for stamping usage without rewriting every call site.

Those examples are provider and gateway patterns, not Flatkey feature claims. If you use Flatkey, verify the current supported metadata path and logs in your account before relying on a field for billing.

Preserve Provider Usage And Cost Dimensions

Your internal customer ledger should not flatten provider detail too early. Provider usage APIs often expose dimensions that help explain cost changes later.

OpenAI's organization usage endpoint supports grouping completions usage by fields such as project, user, API key, model, batch, and service tier, and returns usage fields such as input tokens, output tokens, cached tokens, audio tokens, request count, model, project ID, user ID, and API key ID. OpenAI's organization costs endpoint supports grouping costs by project, line item, and API key, and returns amount, currency, line item, project ID, API key ID, and quantity fields.

That does not mean your customer ledger should use OpenAI user IDs as customer IDs. It means your per-customer AI usage metering layer should preserve enough request-level context to join:

• App customer ID to gateway request ID.
• Gateway request ID to provider request or generation ID.
• Provider usage units to customer-facing billable units.
• Provider cost line item to customer usage bucket.
• Retry/fallback events to the final billable decision.

If a provider report later shows a cost spike by model or API key, you need to trace it back to customer, feature, and invoice period without exposing prompt content.

Use A Customer Usage Ledger

A customer usage ledger is the reviewable table between raw AI logs and customer invoices. It should be append-only or versioned, because invoice disputes often ask what was known at close, not what the current dashboard says after a backfill.

| Column | Example | Purpose | |---|---|---| | occurred_at | 2026-07-10T11:03:22Z | Source request time | | billing_period | 2026-07 | Invoice grouping | | customer_meter_id | cust_8f2a9c | Customer attribution | | feature_id | support_summary | Feature attribution | | environment | prod | Exclude nonbillable traffic | | app_request_id | req_01HX... | Support trace | | gateway_request_id | gw_91b... | Gateway trace | | provider_request_id | gen_72c... | Provider trace, when available | | model_served | model-alias | Model actually used | | input_tokens | 841 | Usage unit | | output_tokens | 226 | Usage unit | | requests | 1 | Usage unit | | raw_provider_cost | 0.0042 | Internal cost basis | | billable_units | 1,067 tokens | Customer-facing unit | | pricing_version | ai-plan-2026-07 | Pricing interpretation | | meter_event_id | meter_01HX... | Billing-system handoff | | reconciliation_state | matched | Evidence quality |

This ledger is the value asset for per-customer AI usage metering. Raw logs are too detailed for finance. Invoices are too late for engineering. The ledger is the shared evidence layer.

Convert Ledger Rows Into Billing Meter Events

If you use Stripe or another usage-based billing system, do not send every raw AI request blindly. First decide what counts as billable usage.

Stripe's meter event API requires an event_name and a payload. The payload must contain fields that match the meter's customer mapping and value settings; the docs show examples using payload[value] and payload[stripe_customer_id]. Stripe also supports an identifier for uniqueness and a timestamp measured in Unix seconds, with timestamp bounds defined by the API.

That maps cleanly to the ledger:

{
  "event_name": "embedded_ai_tokens",
  "identifier": "meter_01HX7VJ8AQB8",
  "timestamp": 1783681402,
  "payload": {
    "stripe_customer_id": "cus_123",
    "value": 1067,
    "feature_id": "support_summary",
    "pricing_version": "ai-plan-2026-07"
  }
}

The billing event should be idempotent. If your worker retries after a timeout, the same AI request should not create two billable events. Keep the meter event ID in the customer ledger and store the billing API response, even when the response is "already processed."

Decide What Is Not Billable

Per-customer AI usage metering is as much about exclusions as charges. Your ledger should classify traffic before it enters billing:

| Traffic type | Default billing decision | Evidence to keep | |---|---|---| | Production customer action | Billable, if the plan allows metered AI | Customer ID, feature, request ID, usage units | | Internal support action on behalf of customer | Usually nonbillable or separately classified | Staff ID, ticket ID, customer ID, reason | | Retry after provider error | Bill only the successful logical request | Original request ID, retry count, final status | | Fallback from one model to another | Bill according to policy, not both blindly | Model requested, model served, routing decision | | Staging/dev/test traffic | Nonbillable | Environment, owner, test marker | | Abuse or automated loop | Often credited or capped | Rate-limit event, detection reason, customer notice | | Data backfill or migration | Usually nonbillable | Job ID, operator, approval |

Publish these rules internally before customers ask. A documented policy prevents support, finance, and engineering from making ad hoc exceptions for every dispute.

Keep Prompt Content Out Of Billing Evidence When Possible

Billing evidence rarely needs raw prompts or completions. Most disputes can be handled with timestamp, feature, customer, model, token counts, request status, and customer-facing event labels.

A privacy-safe per-customer AI usage metering policy should separate:

• Metering metadata: customer meter ID, feature, environment, request ID, model, tokens, cost, timestamp.
• Operational payloads: prompts, retrieved documents, generated text, attachments, tool inputs.
• Support annotations: ticket ID, reviewer ID, credit reason, customer-facing explanation.

Store the first category longer than the second. Restrict the second category more aggressively. Cloudflare's metadata-only logging pattern is useful here because it shows a common operational split: retain usage metrics and request metadata without storing request and response bodies for that request. If your gateway or vendor offers a similar control, test it before you send regulated customer traffic.

Reconcile Before The Invoice Closes

The reconciliation job is where per-customer AI usage metering becomes billing evidence. Run it before invoices are finalized, not after the first complaint.

Use this daily or hourly workflow:

1. Pull raw app AI events for the billing period.
2. Pull gateway logs or exports for the same period.
3. Pull provider usage and cost summaries by model, API key, project, or line item.
4. Pull billing-meter event acknowledgements.
5. Join on request IDs, timestamps, customer meter IDs, and model aliases.
6. Mark each ledger row as matched, missing_gateway_log, missing_provider_usage, meter_not_sent, meter_duplicate, nonbillable, or needs_review.
7. Block invoice finalization for unresolved high-value rows.
8. Export a customer-level summary for support and finance.

The most important report is not total spend. It is the exception queue. A small number of unmatched rows can create the biggest customer trust problem.

Build A Dispute Packet

When a customer asks, "Why was I charged for AI usage?", support should not open five dashboards and improvise. Prepare a dispute packet format:

| Section | Include | Avoid | |---|---|---| | Summary | billing period, feature, usage units, customer plan, total charge | Prompt or completion text unless explicitly needed | | Evidence | request IDs, timestamps, model class, token/request counts, meter event IDs | Internal provider secrets or raw API keys | | Policy | billable rule, retry/fallback policy, included-credit policy | Unapproved one-off explanations | | Decision | accepted, credited, corrected, or escalated | Blame-shifting between vendors | | Follow-up | limit change, bug fix, customer notification | Undocumented manual edits |

This is especially important for embedded AI features because the user who clicked the feature may not be the buyer who reviews the invoice. The packet must explain the charge in product language, not only API language.

Implementation Checklist

Use this checklist before launching customer-facing AI billing:

• Every AI request receives a backend-derived customer_meter_id.
• Nonproduction traffic is marked before it reaches the gateway.
• The app creates a stable app_request_id for every logical AI action.
• Retries share a parent request ID and do not double count by default.
• Fallback events record requested model, served model, and billing policy.
• The gateway or provider log can be joined back to the app request.
• Provider usage and cost exports are preserved at useful grouping levels.
• A customer usage ledger stores billable and nonbillable rows.
• Billing-meter events use idempotent identifiers.
• Finance can review customer, feature, model, and period rollups.
• Support has a dispute packet template.
• Prompt and completion retention is minimized separately from metering metadata.
• Customers can see enough usage detail to understand their bill.

Where Flatkey Fits

Flatkey is relevant when the operating problem is model-access and invoice sprawl. The current public Flatkey site emphasizes one key across GPT, Claude, Gemini, DeepSeek, image, audio, and video models, an OpenAI-compatible gateway, usage analytics and cost control, request logs, and one invoice across providers. That is a practical foundation for teams that want fewer provider accounts and a cleaner review surface.

For per-customer AI usage metering, use Flatkey as the unified route where your production AI traffic can be reviewed, priced, and governed. Keep customer-level billing evidence in your own app ledger unless your current Flatkey account explicitly supports the exact field, export, retention, and billing workflow you need. Then reconcile Flatkey usage records with provider summaries and your billing meter before invoices go out.

If you are designing the commercial model, pair this guide with AI API cost attribution by team, cost per AI API request, and AI API invoice reconciliation. When you need current model pricing and plan details, use the Flatkey pricing page.

FAQ

Is per-customer AI usage metering the same as API usage logging?

No. API usage logging records what happened technically. Per-customer AI usage metering connects that activity to a customer, feature, billing period, pricing version, and invoice decision.

Should customer IDs be sent to model providers?

Usually no. Use a privacy-safe internal meter ID or gateway metadata when supported. Avoid sending emails, company names, prompts, or end-user personal data as billing identifiers unless your legal and privacy review explicitly approves it.

What unit should embedded AI features bill on?

The best unit depends on the product. Tokens are precise for text, requests are easier for customers to understand, seconds can fit video or audio, and credits can normalize multiple modalities. Whatever unit you choose, keep the raw provider units in the ledger so finance can reconcile margin.

How should retries and fallbacks be billed?

Bill the logical customer action, not every internal attempt, unless your customer terms say otherwise. Preserve retry and fallback evidence so engineering can debug cost spikes without double charging customers.

What is the minimum viable evidence packet?

A practical packet includes customer meter ID, feature, timestamp, request ID, model or model class, usage units, billing period, pricing version, meter event ID, reconciliation status, and support decision. That is the minimum that makes per-customer AI usage metering defensible.

Per-customer AI usage metering should make billing boring. When customer IDs, usage units, gateway records, provider costs, and billing events reconcile before invoice close, embedded AI features become easier to price, explain, and scale. Use Flatkey to simplify the model-access and provider-billing layer, then keep a customer ledger that finance and support can trust. View Pricing.