Claude API Usage-Based Billing Integration Guide

If you're charging your own customers for a product built on Claude, "usage-based billing integration" means one specific thing: turning Claude's token usage data into billable events your payment provider can meter and invoice. This isn't about Anthropic's own pricing — it's about wiring Claude's per-request usage metadata into your SaaS billing stack so you can charge per token, per request, or per seat without manually reconciling numbers at month-end.

The short answer: every Claude API response includes a usage object with input_tokens and output_tokens. You capture that on every call, convert it into a billable unit (cost, credits, or a flat metered quantity), and push it to your billing provider's metering API — usually Stripe's metered billing or usage records endpoint. The rest of this article walks through that pipeline end to end, plus where it tends to break.

Why Claude Usage Data Is Harder to Bill Than It Looks

Token counts aren't the full story. A few things complicate usage-based billing on top of Claude:

• Streaming responses split usage across multiple events — you only get the final tallies once the stream completes.
• Tool use adds extra round trips (model calls your function, you return a result, model calls again), and each round trip consumes tokens independently.
• Cache reads (prompt caching) bill differently than fresh input tokens, and if you're not tracking cache hit/miss separately, your cost model will be wrong.
• Per-key vs per-customer attribution — if multiple end-users share one API key, you need your own request-to-customer mapping before usage data is useful.

Getting billing right means solving attribution first, then metering, then invoicing.

Step 1: Capture Usage on Every Request

Every non-streaming Claude response includes usage inline. For streaming, usage arrives in the final message_delta event. Either way, log it immediately next to a customer/account identifier — don't try to reconstruct it later from logs.

const response = await fetch("https://api.anthropic.com/v1/messages", {
  method: "POST",
  headers: {
    "x-api-key": process.env.ANTHROPIC_API_KEY,
    "anthropic-version": "2023-06-01",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-opus-4-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: prompt }],
  }),
});

const data = await response.json();
const { input_tokens, output_tokens } = data.usage;

await db.usageEvents.insert({
  customerId,
  requestId: data.id,
  inputTokens: input_tokens,
  outputTokens: output_tokens,
  model: data.model,
  timestamp: new Date(),
});

This table is your source of truth. Everything downstream — invoices, dashboards, alerts — should be derived from it, not recomputed from provider logs.

Step 2: Normalize Tokens into Billable Units

Decide what you're actually charging for: raw tokens, a markup on tokens, flat per-request credits, or tiered plans with overage. Most teams land on one of two models:

Cost-plus metering — convert tokens to a dollar cost using the model's published rate, apply your margin, and bill that amount.

function computeBillableCost(usage, model) {
  const rates = { "claude-opus-4-5": { in: 15, out: 75 } }; // $ per million tokens
  const rate = rates[model];
  const cost =
    (usage.inputTokens / 1_000_000) * rate.in +
    (usage.outputTokens / 1_000_000) * rate.out;
  return cost * 1.3; // 30% margin
}

Credit-based metering — convert tokens to an internal "credit" unit, sell credit packs or subscriptions, and deduct credits per call. This is simpler for customers to understand and decouples your pricing from raw token math.

Either way, round and aggregate at the request level before sending anything to your billing provider — don't send per-token events, since most metering APIs expect periodic aggregated usage, not a firehose.

Step 3: Push Usage to Your Billing Provider

If you're using Stripe's metered billing, you report usage against a subscription item, typically on a daily or hourly batch rather than per-request.

await stripe.billing.meterEvents.create({
  event_name: "claude_tokens",
  payload: {
    stripe_customer_id: customer.stripeId,
    value: String(totalBillableUnits),
  },
});

Batch this on a cron job (hourly is usually fine) that sums unreported usage events per customer since the last sync, submits them, and marks them as reported. Idempotency matters here — use your internal requestId or a batch ID as a deduplication key so a retried job doesn't double-bill a customer.

Step 4: Reconcile Before You Trust the Numbers

Set up a weekly reconciliation job that compares your internal usage log totals against what you actually sent to Stripe (or whatever provider you use). Discrepancies usually come from:

• Failed requests that still consumed tokens (partial generation before an error)
• Retried requests counted twice
• Streaming calls where the connection dropped before the final usage event arrived

Log raw usage events immutably, and only mark them "billed" after a successful write to the billing provider — never delete or overwrite them.

Simplifying the Plumbing

If you're maintaining multiple Claude API keys across environments or team members, usage attribution gets messy fast — you end up building your own key-to-customer mapping on top of Anthropic's raw key management. This is one of the problems SubToAPI solves directly: it turns your existing Claude access into application-scoped API keys (sub_live_...) per customer or project, with usage metadata — token counts, request counts, cost — already attached to each key. You pull usage per key via the API instead of parsing it out of raw request logs yourself.

curl https://api.subtoapi.app/v1/usage \
  -H "Authorization: Bearer $SUBTOAPI_KEY"

That gives you a cleaner input into step 1 above: your usage events already arrive scoped to the right customer, so the billing pipeline in steps 2–4 has less attribution work to do. See /docs/messages for request/response shapes and /docs/streaming for how usage is reported on streamed calls. Plans start at Solo €9, with Team (€19/seat) and Scale (€49/seat) tiers adding multi-key usage views for teams — check /pricing for details, or start with a free trial at /signup.

Questions

Does Claude's API support native usage-based billing for my customers? No — Anthropic's API returns token usage per request, but it doesn't bill your end customers. You capture that usage data yourself and feed it into your own billing provider's metering system.

What's the best unit to bill on: tokens, requests, or cost? Tokens give the most accurate cost mapping but are hard for customers to reason about. Flat credits per request are simpler to sell but can misprice heavy users. Most SaaS products start with credits and expose a token-based overage tier once usage patterns are clear.

How do I handle usage from streaming or tool-use calls? Wait for the final usage totals — in streaming, that's the last message_delta event; in tool use, sum usage across every model round trip in the conversation before logging a single billable event for that interaction.