Claude API の従量課金で、Stripe の請求額と自分の帳簿がズレるとき — 使用量イベントの突合運用メモ

import { createHash } from "crypto";
 
// 内部のリクエストIDから決定的に冪等キーを作る。リトライしても同じ値になる
function meterIdentifier(requestId: string): string {
  return "req_" + createHash("sha256").update(requestId).digest("hex").slice(0, 32);
}
 
// 使用量の記録は「自前台帳への書き込み」と「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) まず自前台帳に確定で書く（これが一次情報。Stripeは二次的な集計先）
  await ledger.insert({
    requestId: req.requestId,
    userId: req.userId,
    credits,
    model: req.model,
    reportedToStripe: false,
    createdAt: new Date(),
  });
 
  // 2) Stripe へ送る。失敗しても台帳には残っているので後で再送できる
  try {
    await sendMeterEvent({
      stripeCustomerId: req.stripeCustomerId,
      credits,
      identifier: meterIdentifier(req.requestId),
    });
    await ledger.markReported(req.requestId);
  } catch (err) {
    // 送信失敗は握りつぶさず、未送信フラグのまま残す。リトライワーカーが拾う
    console.error("[meter send failed]", req.requestId, err);
  }
}

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表示だけ。課金記録はまだしない
}
 
// ストリーム完了後に最終メッセージから usage を取り出して初めて記録する
const final = await stream.finalMessage();
await recordUsage({
  requestId,
  userId,
  stripeCustomerId,
  model: final.model,
  inTok: final.usage.input_tokens,
  outTok: final.usage.output_tokens,
});

// 日次バッチ: 顧客ごとに自前台帳とStripe集計を突合する
async function reconcileCustomer(stripeCustomerId: string, periodStart: number, periodEnd: number) {
  // 自前台帳の当月クレジット合計
  const ledgerTotal = await ledger.sumCredits(stripeCustomerId, periodStart, periodEnd);
 
  // Stripe meter の当月集計（meter ごとの event summary を取得）
  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) {
    // ズレあり。符号で原因の方向がわかる
    //   diff > 0 : 台帳にあるのにStripeに届いていない（送信失敗の積み残し）
    //   diff < 0 : Stripeに多く積まれている（二重送信 or identifier設計ミス）
    await alertReconcileDrift({ stripeCustomerId, ledgerTotal, stripeTotal, diff });
  }
  return diff;
}