API Billing: How to Meter and Charge for API Calls

TL;DR

• API billing is the pipeline that turns API calls into revenue: meter every request, aggregate usage per customer, and invoice automatically. A billing API handles this so your product code only reports events.
• Four pricing models cover almost every API: per-call (pay per request), tiered plans (included allowance + overage), credits (prepaid blocks), and prepaid balance (dollar wallet). The comparison table below tells you when to use each.
• Integration is three calls with the @commet/node SDK: create a customer, create a subscription, and track a usage event per request with an idempotency key.
• Build vs buy is really a question of scope: metering alone is a weekend project, but aggregation, invoicing, payments, taxes, and edge cases are a permanent team. Most API companies should buy the billing layer and keep their engineering on the product.

What is API billing?

API billing is the system that measures what each customer consumes through your API and charges them for it. It has three jobs: metering (count every call or unit of work), rating (apply a price to that usage), and invoicing (turn the priced usage into a bill and collect payment).

The reason APIs need dedicated billing infrastructure is that usage is the product. A SaaS dashboard can charge a flat $49/month because serving one more login costs nothing. An API serving 10 million requests costs meaningfully more than one serving 10 thousand — compute, bandwidth, and often per-unit upstream costs (LLM tokens, SMS fees, data lookups) scale with every call. Flat pricing either overcharges small customers or lets large ones destroy your margin.

An API billing platform sits between your request handlers and your revenue: your code reports usage events, the platform aggregates them per customer per billing period, applies your pricing model, generates invoices, and charges the card on file. The alternative — counting requests in your own database and reconciling them into invoices by hand — works until the first retry double-counts an event or the first pricing change requires a migration.

How does API metering and billing work?

The pipeline is the same regardless of vendor: events → aggregation → invoice.

1. Events. Every billable request emits a usage event: an event code (api_calls), the customer who consumed it, a value (how many units), and an idempotency key so retries never double-bill. Events are timestamped, so late delivery does not corrupt the period they belong to.
2. Aggregation. The billing engine sums events per customer, per feature, per billing period. This is where included allowances are netted out, credit balances are decremented, and overage is computed.
3. Invoice. At the end of the period (or in real time, for prepaid models), aggregated usage becomes invoice line items: base price, included usage, overage at the configured rate. The invoice is finalized, the customer is charged, and the cycle resets.

In Commet this maps to a plan-first model: you define a feature with an event code, bundle it into a plan with a pricing model, and assign the plan to a customer. From that point your only runtime responsibility is reporting events — aggregation, invoicing, and payment collection run automatically. The same pipeline powers token metering for AI products; the usage-based billing for AI guide covers that variant in depth.

Two properties matter more than anything else in this pipeline:

• Idempotency. Networks fail and queues redeliver. If your metering pipeline counts the same request twice, you are silently overcharging customers. Every event needs an idempotency key, and the ingestion API must reject duplicates.
• Auditability. When a customer asks "why was I charged $312 this month?", you need the raw event log, not just the aggregate. Disputes are won or lost on whether you can show every counted call.

Which pricing model should you use for your API?

Four models cover almost every API business. In Commet, the consumption side maps to three plan models — metered, credits, or balance — and they are mutually exclusive per plan: each plan uses exactly one. Tiered pricing is a packaging layer on top of metered plans rather than a fourth consumption model.

Some practical guidance on choosing:

• Per-call is the purest form of usage pricing: set a price per unit (for example $0.001 per call on a balance plan with fixed pricing, or a pure overage rate on a metered plan) and every request bills at that rate. It converts well for developer self-serve because there is nothing to size up front.
• Tiered plans are what most API companies converge on. A metered plan includes 10,000 calls/month for a base price; overage bills at $0.01 per call at period end. Stack three or four plans with growing allowances and you get predictable revenue plus usage expansion. More on the mechanics in the metered billing glossary entry.
• Credits shine when one API call is not one unit of cost — an OCR page costs more than a status check. Pricing operations in credits (1 credit per lookup, 20 per document) keeps your margin stable while customers reason in a single currency. In Commet, plan credits reset each billing period, while credits bought as packs never expire. See credits billing.
• Prepaid balance is the cloud-provider model: the plan's base price becomes a spending balance and each event deducts its actual dollar cost. Balance plans support fixed per-unit pricing or AI-model pricing, where the cost is computed from current token prices plus your margin. See balance billing.

One constraint worth designing around early: free plans cannot run overage — usage is blocked at the included limit. That is a feature, not a limitation; a free tier that silently bills overage is a support disaster.

How do you integrate API billing?

With Commet the integration is three SDK calls. Install the SDK:

npm install @commet/node

First, create a customer and a subscription. Customer creation is idempotent on your own user ID, so you can call it from your signup flow without checking for existence first. Creating the subscription returns a checkout URL where the customer enters payment details:

import { Commet } from "@commet/node";

const commet = new Commet({ apiKey: process.env.COMMET_API_KEY! });

await commet.customers.create({
  email: "billing@acme.com",
  id: "user_123",
});

const subscription = await commet.subscriptions.create({
  customerId: "user_123",
  planCode: "pro",
});

redirect(subscription.data.checkoutUrl);

From then on, billing an API call is one track() call in your request handler. You can pass your own user ID as customerId — no need to store or look up the Commet ID:

app.post("/v1/convert", async (request, response) => {
  const conversion = await convertDocument(request.body);

  await commet.usage.track({
    customerId: request.userId,
    feature: "api_calls",
    value: 1,
    idempotencyKey: request.id,
  });

  response.json(conversion);
});

The parameters that matter:

• feature is the event code of a metered feature you defined in the dashboard (api_calls, documents_processed, compute_minutes — snake_case, descriptive).
• value is the quantity consumed and defaults to 1. Use fractional values for units like gigabytes or minutes.
• idempotencyKey makes retries safe: Commet rejects an event whose key was already recorded for that customer. Use your request ID, job ID, or any identifier unique to the unit of work. This is optional in the API and non-negotiable in practice.

That is the whole runtime integration. Aggregation, allowances, overage, invoicing, and payment collection happen on the platform side. If your API fronts LLMs, you can skip manual counting entirely and pass the model plus token counts — Commet prices them from a catalog of 180+ AI models, as covered in the usage-based billing for AI guide. For a full end-to-end walkthrough in your framework, start with the Next.js quickstart or the usage tracking docs.

What should an API billing dashboard show?

Once events flow, the dashboard becomes your revenue console. Whatever platform you choose, these are the views that matter for an API business — all of them ship in Commet's dashboard:

• Usage events. The raw feed of every tracked event with its customer, feature, value, and timestamp. This is your audit trail for billing disputes and your debugging tool when an integration double-reports.
• Customers and subscriptions. Who is on which plan, current period consumption against allowances, and subscription state. The "customer asks what they owe" question should be answerable in one click.
• Invoices. Every generated invoice with line items separating base price from overage, its payment status, and the transactions behind it.
• AI costs (if you bill tokens). Per-request model usage, token breakdown, and the margin applied — so you can see your spread between provider cost and customer price.

Your customers need the mirror image: a self-serve portal where they see current usage, remaining credits or balance, invoices, and can top up or buy credit packs without emailing support. Commet's Customer Portal handles upgrades, credit pack purchases, and balance top-ups out of the box — every "why was I charged this?" ticket the portal absorbs is support time you keep.

Should you build or buy API billing?

Honest answer: metering is easy to start and brutal to finish, and metering is the smallest part of the problem.

Building it yourself makes sense when billing logic is genuinely your differentiator or your pricing is so unusual that no platform models it. A counter in Redis and a monthly cron job will work for your first ten customers. What gets you is everything after: idempotent ingestion under retries, late and out-of-order events, aggregation that survives a pricing change mid-period, proration on plan changes, invoice generation, failed payments, refunds — and then the non-engineering half: sales tax and VAT registration, collection, and remittance in every jurisdiction where your customers live. Each piece is tractable; the sum is a permanent billing team.

Buying the metering layer only (a usage-based billing engine) solves events, aggregation, and rating, but leaves you as the seller: you still assemble a payment processor, a tax solution, and compliance on top.

Buying the full stack means one vendor owns events through money in the bank. Commet does this as a Merchant of Record: it is the legal seller, so taxes are calculated, collected, and remitted for you, refunds and compliance are handled, customers can be charged in their local currency in 20+ markets, and payouts arrive in local currency in 112 countries. The honest boundaries: payments are card-only today (no PayPal or wire), and pricing is a flat 4.5% + $0.40 per successful transaction with no monthly fee — the math is on the pricing page.

The decision heuristic: if your engineers are writing aggregation pipelines instead of your product, you chose wrong. Usage data flows out of your API either way; the question is whether turning it into revenue is your team's job or your vendor's.

Key takeaways

API billing is a pipeline — events, aggregation, invoice — and the integration surface is small: one track() call per billable request with an idempotency key. Choose the pricing model by how your costs behave: per-call for linear costs, tiered plans for predictable revenue with usage upside, credits to hide per-operation cost variance, prepaid balance for transparency and zero credit risk. In Commet, metered, credits, and balance are mutually exclusive per plan, so pick deliberately. And before building any of it in-house, price the whole iceberg — metering is the visible tip, and taxes, invoicing, and payment edge cases are the rest. Start with the quickstart and you can bill your first API call the same afternoon.