0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Stripe の従量課金(Billing Meters)に API 利用量を送るときの注意点:identifier の重複排除、タイムスタンプ、締め日のずれ

0
Posted at

API の利用量を Stripe の Billing Meters に送って請求する仕組みを作ってみると、ドキュメントを一度読んだだけでは気づかない落とし穴がいくつかありました。「送った」「Stripe が受け付けた」「請求書に載った」の三つは、それぞれ別の話です。この記事では、その間で数字がずれたり消えたりするパターンと、それを避ける送り方をまとめます。

私は開発者が自分の Stripe アカウントで API の従量課金 を回すためのサービス、UsageRail を作っています。この記事はその実装で調べたこと、確かめたことをもとにしています。公式ドキュメントは 2026 年 11 月 15 日時点のものを参照しました。一部、公式ドキュメントに書かれておらず、サンドボックスのテストクロックで確認した挙動も含みます。その箇所には毎回そう書いておきます。

その前に:Stripe は新規には Metronome を勧めている

いまの Stripe のドキュメントでは、新しく従量課金を組むなら Metronome(Stripe の一部になった従量課金の製品)を使うよう案内されています。Meters API は「既存の連携向けに引き続き完全サポート」という位置づけです。一方で、Checkout、Connect、Adaptive Pricing との互換性は Meters 側のほうが高いとも書かれています。Checkout でそのままサブスクリプションを売りたいなら、いまも Meters は現実的な選択肢です。以下は Meters を使う前提の話です。

メーターの設定はあとから変えられない

メーターを作って設定すると、変えられるのは表示名だけになります。最初に決めるべき項目は次の二つです。

  • 集計方法(default_aggregation.formula):sum(値の合計)、count(イベント数)、last(期間内で最後の値)。
  • 取り込み方(Event ingestion):Raw(デフォルト)と Pre-aggregated。Raw では同じ時刻のイベントも全部足し込まれます。Pre-aggregated では 1 時間または 1 日の区切りごとに最後に受け取ったイベントだけが使われ、新しいイベントが前のものを上書きします。区切りは UTC です。

Pre-aggregated は再送に強いのが利点です。「この 1 時間の合計」を毎回丸ごと送る形にしておけば、同じものを何度送っても上書きされるだけで二重には数えられません。逆に、差分(前回からの増分)を送る作りでこれを選ぶと、最後の差分しか残りません。

値は小数も受け付けます。負の値も送れますが、期間全体の合計がマイナスになった場合、請求書の数量は 0 になります。

identifier による重複排除は「少なくとも 24 時間」

meter event には identifier を付けられます。付けなければ Stripe が自動で生成します。API リファレンスの説明はこうです。

Stripe enforces uniqueness within a rolling period of at least 24 hours.

続けて、これは主に短時間の誤った再送への対策だと書かれています。言い換えると、24 時間を過ぎてから同じ identifier で送った場合に弾いてくれる保証はありません。そこで新しいイベントとして受け付けられれば、その分は二重に計上されます。

サンドボックスで同じ identifier のイベントを続けて送ったところ、2 回目は HTTP 400 で、メッセージに An event already exists with identifier を含むエラーが返りました。集計にも 1 回分しか入りませんでした。ここで大事なのは、このエラーを失敗ではなく「送信済み」として扱うことです。1 回目がタイムアウトしたけれど実は Stripe に届いていた、というのはまさにこのケースだからです。

Idempotency-Key だけに頼らない

Stripe API 全般の Idempotency-Key ヘッダーも 24 時間以上たつと削除対象になります。それに加えて、v1 API では最初のリクエストのステータスとボディが保存され、同じキーで再送すると、500 エラーであってもそのまま同じレスポンスが返ります。同じ Idempotency-Key で 500 を受けたリクエストを何度再送しても、その間ずっと同じ 500 が返ってくることになります。

meter event の重複排除は、ヘッダーではなく identifier に任せるほうが素直です。

identifier は「中身」から決める

UUID を毎回生成すると、再送のたびに別のイベントになってしまいます。identifier は送る内容から決まる値にします。たとえば期間ごとに 1 件だけ送る設計なら、次のようにします。

import { createHash } from "node:crypto";

// 同じ顧客・同じメーター・同じ期間なら、何度計算しても同じ値になる(64 文字。identifier の上限は 100 文字)
function identifierFor(customerId: string, meterId: string, periodStart: Date, periodEnd: Date) {
  return createHash("sha256")
    .update([customerId, meterId, periodStart.toISOString(), periodEnd.toISOString()].join("|"))
    .digest("hex");
}

200 が返っても、集計に入ったとは限らない

meter event の処理は非同期です。作成 API が成功を返しても、存在しない顧客 ID だった、ペイロードに値のキーがなかった、タイムスタンプが古すぎた、といったエラーはあとから見つかります。その場合は v1.billing.meter.error_report_triggered(イベント名に合うメーターがなければ v1.billing.meter.no_meter_found)という thin event で通知されます。

この 2 つを購読しないまま運用していると、顧客 ID の取り違えなどで黙って請求漏れが起きます。thin event の購読は Workbench を有効にしたうえでイベント送信先を作る必要があり、通常の webhook とは設定場所が違うので見落としやすいところです。

タイムスタンプ:受け付けられることと、請求されることは別

timestamp に指定できるのは、過去 35 日以内から未来 5 分までです。ただしドキュメントには、35 日の範囲は「Stripe がイベントを受け付けるかどうか」を決めるだけで、請求書に入るかどうかは保証しない、とはっきり書かれています。

請求書に載せるには、その期間の請求書が確定(finalize)する前に送る必要があります。

  • 請求書には確定までの猶予(invoice finalization grace period)があり、デフォルトは 1 時間です。ダッシュボードの請求書設定で最大 72 時間まで延ばせます。
  • 猶予中に報告した前期間の利用量が反映されるのは、サブスクリプションの周期請求書と、従量アイテムを変更する Subscription Schedule のフェーズ切り替え請求書だけです。しきい値請求書(threshold invoice)は作成時点までの利用量しか含みません。
  • 期間の途中で価格を変えた(アップグレードなど)サブスクリプションでは、猶予中に送った利用量は今回の請求書にも次の請求書にも入りません。
  • invoice.created の webhook に Stripe が成功レスポンスを受け取れなかった場合、自動回収の請求書の確定は最大 72 時間遅れます。

確定後に届いたイベントも受け付けられて集計(meter event summary)には入ります。しかし確定済みの請求書は更新されず、次の請求書に回されることもありません。ダッシュボードの数字は合っているのに請求額が足りない、という状態になります。

期間の境目は分単位だった

ここからはサンドボックスで確認した挙動で、ドキュメントには書かれていません。

サブスクリプションを 11:17:15 に開始すると、請求書の従量行の期間は 11:17:00 から始まっていました。期間の開始が分単位に切り下げられています。そのため「期間終了の 1 秒前」をタイムスタンプにすると、期間終了が分の途中(xx:17:15 など)のとき、その時刻が請求の集計窓の外に出てしまい、その期間の利用量がまるごと 0 になりました。

期間終了を分単位に切り下げてから 1 秒引いた時刻を使うと、正しく請求書に入りました。meter event summary の API も start_time と end_time を分の境目に揃えるよう求めているので、Stripe 側の集計は分単位で動いていると考えておくのが安全です。

// 期間終了を分に切り下げてから 1 秒引く。終了がちょうど分の境目なら「終了の 1 秒前」と同じになる
function eventTimestamp(periodEnd: Date) {
  const flooredToMinute = Math.floor(periodEnd.getTime() / 60_000) * 60;
  return flooredToMinute - 1; // Unix 秒
}

どの単位で送るか

選択肢は大きく三つあります。

  1. リクエストごとに 1 イベント:自前で集計する処理がいらないので、いちばん単純です。ただし本番の meter event API は Stripe アカウントあたり毎秒 1,000 コールまでで、加えて同じ顧客・同じメーターへの同時呼び出しは 1 本に制限されています。サンドボックスではこの呼び出しがアカウント全体のレート制限に数えられるので、負荷試験の結果は本番と同じになりません。それ以上が必要なら、API v2 の meter event stream(毎秒 10,000 件、本番のみ)を使います。
  2. 1 時間ごとなどにまとめて 1 イベント:コール数が減ります。前述の Pre-aggregated と組み合わせれば再送にも強くなります。
  3. 期間の終わりに顧客ごとに 1 イベント:コール数は最小で、identifier も「顧客 + 期間」で一意に決まります。代わりに、期間の途中は Stripe の upcoming invoice に利用量が出ません。また、送るのは期間終了後なので、前述の確定猶予に間に合わせる必要があります。

ディメンション(ペイロードに追加したキー)を使う場合は、メーターごとに 1 時間あたり 10,000 通り、顧客ごとに累計 100 通りまでという上限もあります。エンドポイント名をそのままディメンションにすると、すぐに当たる数字です。

失敗したときの再送

ここまでを踏まえて、送信側は次のような状態を持つ台帳を作り、台帳に書いてから送るようにしました。送ったあとに書く順番だと、送信直後にプロセスが落ちたとき、送ったことが記録に残りません。

import Stripe from "stripe";

type SendResult = "sent" | "failed" | "retry_later" | "check_summary";

const DAY_MS = 24 * 60 * 60 * 1000;

async function sendPeriodUsage(
  stripe: Stripe,
  report: { identifier: string; eventName: string; stripeCustomerId: string; total: number; periodEnd: Date; firstAttemptAt: Date },
): Promise<SendResult> {
  try {
    await stripe.billing.meterEvents.create({
      event_name: report.eventName,
      identifier: report.identifier,
      timestamp: eventTimestamp(report.periodEnd),
      payload: { stripe_customer_id: report.stripeCustomerId, value: String(report.total) },
    });
    return "sent";
  } catch (error) {
    if (!(error instanceof Stripe.errors.StripeError)) throw error;
    // 前回タイムアウトしたが実は届いていた:送信済みとして扱う
    if (error.statusCode === 400 && /already exists/i.test(error.message)) return "sent";
    // 顧客がいない、権限がないなど。同じものを送り直しても直らないので人が見る
    if (error.statusCode && error.statusCode >= 400 && error.statusCode < 500 && error.statusCode !== 429) return "failed";
    // 5xx、429、タイムアウト:同じ identifier で再送してよいのは最初の送信から 24 時間以内まで
    if (Date.now() - report.firstAttemptAt.getTime() > DAY_MS) return "check_summary";
    return "retry_later";
  }
}

ポイントは check_summary です。24 時間を過ぎたら、もう identifier で重複を防げるとは限りません。闇雲に再送せず、meter event summary を読んで Stripe がすでに受け取っているかを確かめます。

async function stripeTotalFor(stripe: Stripe, meterId: string, stripeCustomerId: string, start: Date, end: Date) {
  const summaries = await stripe.billing.meters.listEventSummaries(meterId, {
    customer: stripeCustomerId,
    start_time: Math.floor(start.getTime() / 60_000) * 60,
    end_time: Math.floor(end.getTime() / 60_000) * 60,
  });
  return summaries.data.reduce((sum, summary) => sum + summary.aggregated_value, 0);
}

こちらの合計と一致していれば、届いています。0 のときは、集計が非同期で遅れることもあるので一度では判断しません。時間をおいて読み直し、それでも 0 なら送ります。それ以外の値なら人が確認します。ただしこの判定は、そのメーターに自分しか書き込んでいないことが前提です。別のシステムも同じメーターに送っているなら、合計が一致しても何の証明にもなりません。

再送の間隔は 5 分から倍々に伸ばし、上限を 2 時間にしました。これで 24 時間のうちに何度か試せます。ただ、確定猶予がデフォルトの 1 時間のままでは、再送が間に合う前に請求書が確定してしまいます。UsageRail では invoice.created を受け取った時点で、その請求書の確定を作成から 72 時間後に延ばして、再送の時間を確保しています。

締め日のずれ

自前で数えている利用量と、Stripe が請求する期間がずれることがあります。

  • 期間は暦月ではなく、サブスクリプションの開始日が基準です。17 日に契約した顧客の期間は毎月 17 日から翌月 17 日までで、自分のデータベースで「11 月分」を JST の暦月で集計していると合いません。
  • 期間の情報はサブスクリプションアイテムにあります。API バージョン 2025-03-31.basil 以降、current_period_start と current_period_end はサブスクリプションから消え、items.data[].current_period_start / current_period_end に移りました。古いコードをバージョンだけ上げると、ここで undefined になります。
  • 境目のリクエストをどちらの期間に入れるかを決めておきます。分単位で集計しているなら、「期間終了を含む 1 分」をどちらに入れるかを、上のタイムスタンプの規則と揃えておく必要があります。

間違えて送ったとき

meter event adjustment で identifier を指定してイベントを取り消せます。ただし対象は、Stripe に送ってから 24 時間以内のイベントだけです。確定済みの請求書に含まれる利用量を取り消しても、請求書は修正されません。それより後に間違いに気づいた場合は、マイナスの値を送って打ち消すか、請求書の外(クレジットノートや返金)で調整することになります。

最後に突き合わせる

送ったあとは、二段階で突き合わせると安心です。

  1. 送ってから少し時間をおいて(非同期なので)meter event summary を読み、自分の合計と一致するか確かめる。
  2. 請求書が確定したら、その従量価格の明細行の数量と金額が自分の計算と合っているか確かめる。段階料金では 1 段ごとに 1 行ずつ出たので(サンドボックスで確認)、全行を足してから比べます。

1 が合っていて 2 が合わないときは、利用量を送った時刻と請求書が確定した時刻、それに期間途中の価格変更がなかったかを確認します。

期間ごとに 1 件だけ送る形、内容から決める identifier、2 段階の突き合わせは、UsageRail で実際にこの順番で実装しています。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?