When Stripe's Bill and Your Own Ledger Drift Apart: Field Notes on Metered Billing for Claude API

One idempotency key stops both double-counting and loss

Billing accidents come in essentially two flavors: sending the same usage twice (overbilling), or thinking you sent it when you didn't (underbilling — money out of your pocket). The Billing Meters identifier field handles both with one design. Stripe ignores events that repeat an identifier, so retries become safe to fire as many times as you like.

The key is making identifier deterministic from the request's natural key. A random UUID produces a new event on every retry and double-counts. I use the internal request ID.

import { createHash } from "crypto";
 
// Deterministic idempotency key from an internal request ID — same value on every retry.
function meterIdentifier(requestId: string): string {
  return "req_" + createHash("sha256").update(requestId).digest("hex").slice(0, 32);
}
 
// Separate "write to our ledger" from "send to Stripe".
export async function recordUsage(req: {
  requestId: string;
  userId: string;
  stripeCustomerId: string;
  model: string;
  inTok: number;
  outTok: number;
}) {
  const credits = tokensToCredits(req.model, req.inTok, req.outTok);
 
  // 1) Commit to our own ledger first — this is the source of truth. Stripe is the secondary aggregator.
  await ledger.insert({
    requestId: req.requestId,
    userId: req.userId,
    credits,
    model: req.model,
    reportedToStripe: false,
    createdAt: new Date(),
  });
 
  // 2) Send to Stripe. If it fails, the ledger still has it, so we can resend later.
  try {
    await sendMeterEvent({
      stripeCustomerId: req.stripeCustomerId,
      credits,
      identifier: meterIdentifier(req.requestId),
    });
    await ledger.markReported(req.requestId);
  } catch (err) {
    // Don't swallow send failures — leave the unreported flag for a retry worker to pick up.
    console.error("[meter send failed]", req.requestId, err);
  }
}

Making your own ledger the source of truth is the load-bearing decision here. If Stripe is your source of truth, data vanishes the moment a send fails. Write to the ledger first, and the Stripe send demotes to a re-runnable derived step. Because identifier is idempotent, resending never double-counts.

With streaming, wait for the moment tokens finalize

This is what tripped me up most. While a response streams with stream: true, the token count isn't final. It's tempting to report mid-stream, but a dropped connection then underreports.

The fix is simple: only finalize and record usage on the stream-completion event. The Anthropic SDK resolves to a final message that includes usage; wait for that.

const stream = anthropic.messages.stream({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: prompt }],
});
 
for await (const event of stream) {
  // UI rendering only here — no billing yet.
}
 
// After completion, pull usage from the final message, then record.
const final = await stream.finalMessage();
await recordUsage({
  requestId,
  userId,
  stripeCustomerId,
  model: final.model,
  inTok: final.usage.input_tokens,
  outTok: final.usage.output_tokens,
});

If you want a live usage bar, optimistically bump a DB counter for display and defer the authoritative Stripe send until the stream finishes. Splitting display from billing gives you both visual immediacy and billing accuracy.

Reconcile within the month — finding out at month-end is too late

Here's the heart of it. Your ledger and Stripe's meter accumulate independently, so you must reconcile periodically and catch drift early. Discover it at month-end and the invoice is already finalizing, leaving few options. I compare, once a day per customer, the ledger's month-to-date total against Stripe's meter aggregation.

// Daily batch: reconcile our ledger against Stripe's aggregation, per customer.
async function reconcileCustomer(stripeCustomerId: string, periodStart: number, periodEnd: number) {
  const ledgerTotal = await ledger.sumCredits(stripeCustomerId, periodStart, periodEnd);
 
  // Stripe meter aggregation for the period (per-meter event summaries).
  const summaries = await stripe.billing.meters.listEventSummaries(METER_ID, {
    customer: stripeCustomerId,
    start_time: periodStart,
    end_time: periodEnd,
  });
  const stripeTotal = summaries.data.reduce((s, x) => s + x.aggregated_value, 0);
 
  const diff = ledgerTotal - stripeTotal;
  if (diff !== 0) {
    // The sign tells you the direction of the cause:
    //   diff > 0 : in our ledger but not at Stripe (failed sends piling up)
    //   diff < 0 : more at Stripe than in our ledger (double-send / broken identifier)
    await alertReconcileDrift({ stripeCustomerId, ledgerTotal, stripeTotal, diff });
  }
  return diff;
}

The sign of the difference is your triage. Ledger higher means dropped sends (recover by replaying the unreported rows); Stripe higher means double-counting (the identifier's determinism broke). Write that one-line sign rule into your runbook and you'll handle a 2 a.m. alert calmly.

When reconciliation finds diff > 0, resend the unreported ledger rows with their identifier. Idempotency means any already-delivered events won't duplicate. That's exactly where the "ledger as source of truth" design pays off.

Put the overuse safety valve on your side, not Stripe's

For users to accept usage-based billing, they need to know it isn't unbounded. Enforce the cap from your real-time ledger counter, not Stripe's aggregation. Stripe's meter rollup lags, which makes it a poor gatekeeper.

Separating the roles is the trick: gate = your ledger, billing = Stripe, audit = the difference. Mix these three and lag and rounding all collect in one place, beyond untangling.

The design calls that quietly pay off

I run Stripe memberships across several sites under Dolice Labs, and the part of billing that takes the most care isn't dramatic outages — it's the class of issue that drifts a little at a time without anyone noticing. Once I moved to a ledger-as-source-of-truth setup with daily reconciliation, month-end finalization stopped being a scramble. Even when drift appears, knowing I can read the sign and replay unreported events to converge takes a surprising amount of weight off the operational mind.

Usage-based billing isn't done when it's "implemented correctly." It's only operable once you've designed for drift as a given and kept that drift explainable. A good next step is recording the reconciliation diff as a time-series metric, so you can spot a single user who drifts persistently — that's usually where a hole in your identifier design is hiding.

I hope this gives you solid footing if you're wrestling with the same reconciliation problem.