Stripe のサブスク更新で月次レポートを自動で届ける【2026年11月】— invoice.paid の見分け方と請求書 ID の冪等化

「月額の顧客には、毎月の更新に合わせてレポートを自動で送りたい。Stripe の Webhook で動かせるはずなので Claude Code に書かせたい」。この構成は、単発の決済から納品メールを送る仕組みより一段むずかしくなります。更新は毎月くり返し、支払いが失敗する月があり、途中で一時停止や解約が入り、同じ請求書に対して複数のイベントが届くからです。

この記事では、Stripe の公式ドキュメントで確かめられる仕様だけをもとに、定期課金の更新を起点に月次の納品物（レポート・集計・データの書き出しなど）を自動で届ける設計を整理します。単発の決済から納品メールまでの基本（署名検証・即時応答・イベント ID の記録）は「Stripe 決済から納品メールまでを自動化する」で扱ったので、ここでは定期課金に固有の部分に絞ります。

1. 起点は invoice.paid に絞り、billing_reason で「新規」「更新」「変更」を分ける。 subscription_cycle が毎月の更新です。新規契約時や途中変更時の請求書に同じ処理を走らせると、納品が月に2回になります
2. 納品の記録は請求書 ID（in_ で始まる）で一意にする。 イベント ID の記録だけでは、別のイベントが同じ請求書で届いたときに防げません
3. 「払われた」と「購読が有効」は別。 Stripe は、invoice.paid を受け取ったら購読を取得し、status が active であることを確かめてからアクセスを延長するよう求めています
4. 送らない条件を先に決める。 支払い失敗（past_due）、支払い回収の一時停止、解約済み、金額のない請求書。どれも仕様上は請求書が生まれ続けるので、条件を書かないと送ってしまいます
5. 月末更新の集中とテストはサンドボックスのテストクロックで。 本番で初回の更新日を待つ必要はありません

定期課金では、Stripe が各請求期間の終わりに請求書を自動で作り、支払いを試み、購読の status を更新します。設計の前に、どの順で何が届くかを押さえます。 ※ 出典: Stripe Docs — How subscriptions work（取得 2026-11）

※ 出典: Stripe Docs — Using webhooks with subscriptions（取得 2026-11）／Stripe Docs — Subscription invoices（取得 2026-11）／Stripe Docs — Types of events（取得 2026-11）

押さえておきたい仕様が3つあります。

• invoice.created への応答は確定を左右する。 自動回収の請求書は、invoice.created に対して成功応答を受け取れない場合、確定が最大72時間遅れます。応答があっても、Stripe は約1時間待ってから支払いを試みます。Webhook の受け口が落ちていると、納品どころか課金そのものが遅れます
• invoice.upcoming は自動課金のときだけ。 請求書をメールで送る方式（collection_method=send_invoice）では届きません
• イベントの順序は保証されない。 公式の例では、購読の作成時に customer.subscription.created・invoice.created・invoice.paid・charge.created が生成順と違う順で届きうると書かれています。invoice.paid を先に受け取っても、必要な情報は API で取り直せます

※ 出典: Stripe Docs — Using webhooks with subscriptions（取得 2026-11）／Stripe Docs — Receive Stripe events in your webhook endpoint（取得 2026-11）

似た名前のイベントがあります。公式の説明は次のとおりです。

※ 出典: Stripe Docs — Types of events（取得 2026-11）

月次の納品に使うのは invoice.paid です。銀行振込など Stripe の外で入金を受けて手動で「支払い済み」にした月も、同じ経路で納品できます。両方を購読すると、同じ請求書に対して2つのイベントが届くので、片方だけにします。公式も、購読するイベント種別は必要なものだけに絞るよう求めています。

Invoice オブジェクトの billing_reason は、その請求書がなぜ作られたかを示します。月次の納品で見分けが必要な値は次のとおりです。

※ 出典: Stripe Docs — The Invoice object（取得 2026-11）

billing_reason には subscription（2018年5月より前の購読向けで、現在は使われていない）や quote_accept、automatic_pending_invoice_item_invoice もあります。扱わない値はすべて「記録して何もしない」に落とし、未知の値が来ても落ちないようにします。 ※ 出典: Stripe Docs — The Invoice object（取得 2026-11）

「何月分のレポートか」は、請求書の period_start と period_end から決めたくなりますが、公式の定義はそれぞれ「この請求書に項目を関連付けられる最も早い／遅い時刻」です。各価格のサービス期間は、明細（line item）の period を使うよう書かれています。月次レポートの対象期間は、購読の明細行の period.start と period.end から取り、請求書本体の値は補助にします。 ※ 出典: Stripe Docs — The Invoice object（取得 2026-11）

レポートの宛先や契約の種別を購読の metadata に持たせている場合、請求書の subscription_details.metadata には請求書作成時点の購読 metadata が常に入ります。あとから購読側を書き換えても、その請求書の値は変わりません。「この月はどの契約内容で納品したか」の記録として使えます。購読オブジェクト全体が必要なら、API バージョン 2025-03-31.basil 以降は parent.subscription_details.subscription を expand で展開します。 ※ 出典: Stripe Docs — Subscription invoices（取得 2026-11）

単発決済の記事では、イベント ID・セッション ID・メール送信の3層で冪等化しました。定期課金では、真ん中の層の鍵が請求書 IDに変わります。

Stripe は、重複の検出にはイベント ID を記録し、別々の Event オブジェクトとして送られる場合には data.object の ID と event.type を組み合わせて見分けるよう書いています。invoice.paid と invoice.payment_succeeded を両方購読していた場合や、ダッシュボードからの手動再送（イベント作成から15日間可能）がこれに当たります。第2層の「請求書 ID に一意制約を付けた納品記録を先に取る」で吸収します。 ※ 出典: Stripe Docs — Receive Stripe events in your webhook endpoint（取得 2026-11）

再送の仕様も単発決済と同じです。本番では最大3日間、間隔を広げながら再送されます。サンドボックスでは数時間のうちに3回です。再送のたびに署名と時刻は新しく生成されます。 ※ 出典: Stripe Docs — Receive Stripe events in your webhook endpoint（取得 2026-11）

公式は、Webhook の処理を非同期のキューに回すことを勧めています。理由として挙げられているのが、月初にすべての購読が更新されるときの急増です。月次レポートの生成が重い場合、Webhook の応答より先に生成を始めると、タイムアウトから再送が始まり、再送のたびに生成が走ります。受け口は「署名検証 → イベント ID の記録 → キュー投入 → 2xx」で終え、生成はワーカーで行います。 ※ 出典: Stripe Docs — Receive Stripe events in your webhook endpoint（取得 2026-11）

納品の過程で Stripe の API に書き込む処理（請求書へのメモ追加、顧客情報の更新など）があるなら、Idempotency-Key を付けます。キーは255文字まで、V4 UUID などの十分にランダムな値が推奨され、メールアドレスのような個人情報は使わないよう書かれています。API v1 では24時間以上たったキーは自動で削除されます。鍵は「請求書 ID ＋ 操作名」から導出した UUID にすると、再実行しても同じ操作になります。 ※ 出典: Stripe Docs — Idempotent requests（取得 2026-11）

請求書は、支払いが止まっても生まれ続けます。「invoice.paid が来たら送る」だけでは足りず、次の4つを設計に入れます。

更新の支払いが失敗すると invoice.payment_failed が届き、自動課金の購読は past_due になります。Stripe は再試行の設定に従って支払いを試み続け、再試行が尽きたあとは、ダッシュボードの「失敗した支払い」の設定で canceled・unpaid・past_due のまま・paused のいずれかに移ります。

再試行の既定は Smart Retries で、新しいアカウントでは「2週間以内に最大8回」に設定されています。期間は1週間から2か月の範囲で選べ、独自の規則にする場合は最大3回の再試行を日数指定で組めます。請求書の attempt_count に試行回数、next_payment_attempt に次回の試行時刻が入ります。 ※ 出典: Stripe Docs — Automate payment retries（取得 2026-11）／Stripe Docs — How subscriptions work（取得 2026-11）

この間にレポートを送るかどうかは契約の話です。既定にしやすいのは「past_due の間は送らず、再試行で invoice.paid が来た時点で、その請求書の期間分を送る」です。この形なら、新しいコードは要りません。第2層の記録が請求書 ID なので、遅れて届いた invoice.paid も該当する月の納品として一度だけ処理されます。

Stripe は、invoice.paid を受け取ったら購読を取得して status が active であることを確認してから、アクセスの期限を延ばすよう求めています。購読の状態を「すべての請求書」で判定する設定にしている場合、ある請求書が払われても、別の未払い請求書が残っていれば購読は active になりません。この設定では、Stripe は過去37か月分の該当する請求書を確認します。 ※ 出典: Stripe Docs — Using webhooks with subscriptions（取得 2026-11）／Stripe Docs — How subscriptions work（取得 2026-11）

納品の判定も同じにします。invoice.paid → 請求書の billing_reason が subscription_cycle → 購読を取得して status が active（契約によっては trialing も）→ 納品、の順です。

顧客に猶予を与えるために「支払い回収の一時停止」を使うと、購読は active のまま請求書は作られ続け、支払いだけが止まります。このとき請求書の扱いは次のとおりです。

※ 出典: Stripe Docs — Pause payment collection（取得 2026-11）

一時停止中は、これらの請求書について「次回請求のメールも Webhook も送らない」と書かれています。一時停止中もレポートだけは届けたい契約なら、invoice.paid を待たずに、invoice.created や自前のスケジュールで送る別経路が要ります。逆に止めたいなら、購読の pause_collection が設定されているかを納品前に見ます。

購読そのものを paused にする機能（トライアル終了時に支払い方法が無い場合など）は別物で、こちらは請求書が作られなくなります。 ※ 出典: Stripe Docs — Using webhooks with subscriptions（取得 2026-11）

• 解約（canceled）: 新しい請求書は作られず、未払い請求書の自動回収も止まります（auto_advance=false）。終端の状態で、metadata と cancellation_details 以外は更新できません。解約後に届く invoice.paid は、最後の請求書の遅延入金の可能性があるので、期間分を送るか契約で決めます
• unpaid: 再試行が尽きたあとこの状態を選んだ場合、請求書は作られ続けますが draft のまま支払いは試みられません。Stripe はこの状態でアクセスを止めるよう勧めています
• 0円の請求書: トライアル付きの購読は開始時に0円の請求書を生成します。金額で納品の要否を判断するのではなく、billing_reason と購読の status で判断します

※ 出典: Stripe Docs — How subscriptions work（取得 2026-11）／Stripe Docs — Test your Billing integration（取得 2026-11）

「全顧客に月末締めのレポートを月初に送る」なら、更新日を月末にそろえると設計が単純になります。購読の請求期間は、価格の間隔と請求サイクルのアンカーで決まります。月次・年次なら billing_cycle_anchor_config を使い、day_of_month を 31 にすると、31日が無い月は最終日に更新されます。アンカーの日付が1月31日なら、2月28日（うるう年は29日）、3月31日、4月30日と続きます。 ※ 出典: Stripe Docs — Set the subscription billing renewal date（取得 2026-11）

注意点が2つあります。アンカーの時刻は UTC で記録されるので、日本時間の「月末」にしたいなら時・分・秒も指定します。また、契約日から最初の更新日までの期間は、既定では日割りの請求書が即時に作られます。初月を無料にしたいなら proration_behavior を none にします。 ※ 出典: Stripe Docs — Set the subscription billing renewal date（取得 2026-11）

ここまでの設計は、公式ドキュメントが具体的でテスト用の仕組みもそろっているので、Claude Code に実装させるのは現実的です。任せるのは「コードを書く」「サンドボックスで動かして直す」まで。鍵と本番の操作、送る・送らないの契約判断は人が持ちます。

鍵を見せない設定は単発決済の記事と同じです。チームで共有する .claude/settings.json の permissions.deny に Read(./.env) と Read(./.env.*) を書きます。公式ドキュメントでは、deny と ask の規則は各メンバーがフォルダを信頼する前から効くと書かれています。 ※ 出典: Claude Code Docs — Settings files and precedence（取得 2026-11）

Stripe の定期課金で、毎月の更新が成功したときに月次レポートを生成して送付する仕組みを実装してください。

前提:
- 鍵と署名シークレットは環境変数 STRIPE_API_KEY / STRIPE_WEBHOOK_SECRET から読む。値は参照しない。
- サンドボックスのみで動作確認する。本番モードと再試行の設定には触らない。
- 購読するイベントは invoice.paid / invoice.payment_failed / customer.subscription.updated / customer.subscription.deleted だけ。

要件:
1. POST /webhook は、生のボディで署名検証 → イベント ID を processed_events に記録 → キュー投入 → 200。
   署名検証に失敗したら 400 を返し、何も処理しない。
2. ワーカーは invoice.paid の請求書を API で取り直し、billing_reason が subscription_cycle のときだけ進む。
   それ以外の billing_reason は理由を記録して終了する。
3. 購読を取得し、status が active でなければ「保留」として記録して終了する。
   pause_collection が設定されていれば「一時停止中」として記録して終了する。
4. deliveries に (invoice_id, kind) を一意制約付きで「processing」として挿入できた場合だけ、
   明細の period.start / period.end を対象期間としてレポートを生成する。
5. メール送付は email_sends に (invoice_id, kind) を「sending」と記録してから送り、送付後に「sent」とメッセージ ID を書く。
6. 同じ請求書で invoice.paid が2回届いても、生成と送付が1回になるテストを書く。
7. invoice.payment_failed は attempt_count と next_payment_attempt を記録するだけにする。

出力: 変更ファイル一覧、テスト結果、stripe listen / stripe trigger とテストクロックで確認した手順。

stripe trigger は invoice.paid・invoice.payment_failed・invoice.created・invoice.finalized・customer.subscription.updated などに対応しています。ただし trigger は実際の API オブジェクトを作って発火させる仕組みで、billing_reason が subscription_cycle の請求書を自然に作るものではありません。更新の流れを通して確かめるには、次のテストクロックを使います。 ※ 出典: Stripe CLI — trigger（取得 2026-11）

社内でこの月次納品の仕組みを自分たちで組む場合の進め方は、企業向けの有料の実務書にもまとめています。

1. サンドボックスを作り、テスト用の鍵を環境変数に置く。 本番の鍵はこの段階では触りません
2. Claude Code に上の雛形で実装させる。 .env の読み取りは deny で拒否しておきます
3. stripe listen --forward-to localhost:4242/webhook で手元に転送する。 サンドボックス用の署名シークレットがその場で表示されます
4. ダッシュボードで購読を作り、「シミュレーションを実行」で時間を進める。 一度に進められるのは購読の間隔2回分までです（月次なら2か月）。顧客に購読が3件を超えてある場合や、関連オブジェクトが25件を超える場合は、ボタンが無効になります ※ 出典: Stripe Docs — Test your Billing integration（取得 2026-11）
5. 更新の invoice.paid で、billing_reason が subscription_cycle のときだけ納品が走ることを確かめる。 初回の subscription_create では走らないことも同時に見ます
6. 同じイベントをダッシュボードから再送し、生成と送付が1回で止まることを確かめる
7. 支払い失敗を再現する。 顧客の既定の支払い方法をテスト用のカード番号 4000 0000 0000 0341 にして短いトライアル付きの購読を作ると、トライアル終了後の支払いが失敗し invoice.payment_failed が届きます。この月に納品が走らないこと、再試行で払われた時点で該当月が1回だけ送られることを見ます
8. シミュレーションを「終了」して片付け、本番の Webhook エンドポイントを登録する。 終了すると顧客と購読を含む関連オブジェクトが削除されます。本番は人が鍵と署名シークレットを入れ、最初の更新日の翌朝に記録を確認します

※ 出典: Stripe Docs — Test your Billing integration（取得 2026-11）／Stripe Docs — Receive Stripe events in your webhook endpoint（取得 2026-11）

本番に移したあとの監視は、「Claude Code で作った自動化が止まっていないか確かめる」の最小セットに乗せます。定期課金で特に効くのは、「更新日の翌日に、subscription_cycle の invoice.paid 件数と納品記録の件数が一致しているか」を毎朝1行で出す点検です。

1. invoice.paid が来たら無条件に送っている。 新規契約の請求書（subscription_create）とプラン変更の日割り請求書（subscription_update）でも走り、同じ月に2〜3通届きます。billing_reason で分けます
2. invoice.paid と invoice.payment_succeeded を両方購読している。 同じ請求書で2つのイベントが届きます。イベント ID の記録では防げず、請求書 ID の記録が要ります
3. 請求書の period_start／period_end をそのまま対象期間にしている。 公式の定義は「項目を関連付けられる最も早い／遅い時刻」で、サービス期間は明細の period です。日割りや追加項目が混ざると期間がずれます
4. 一時停止中の扱いを決めていない。 「支払い回収の一時停止」では請求書は作られ続け、mark_uncollectible でも顧客残高で払えた月は paid になります。送る・送らないを契約で決め、pause_collection を見るコードにします
5. Webhook の応答前にレポートを生成している。 月初に更新が集中するとタイムアウトし、再送のたびに生成が走ります。応答と生成を分けます

※ 出典: Stripe Docs — The Invoice object（取得 2026-11）／Stripe Docs — Pause payment collection（取得 2026-11）／Stripe Docs — Receive Stripe events in your webhook endpoint（取得 2026-11）

以下はすべて、Stripe と Claude Code の公式ドキュメントに記述がある項目です。 ※ 出典: Stripe Docs — Using webhooks with subscriptions（取得 2026-11）／Stripe Docs — Receive Stripe events in your webhook endpoint（取得 2026-11）

• 購読するイベントを invoice.paid・invoice.payment_failed・customer.subscription.updated・customer.subscription.deleted など必要なものだけに絞っている
• invoice.payment_succeeded を invoice.paid と同時に購読していない
• Webhook ハンドラは生のボディで署名を検証し、失敗時は 400 で終わる
• 署名検証の直後にイベント ID を記録し、記録済みのイベントは処理せず 200 を返す
• 納品は billing_reason が subscription_cycle の請求書だけで走る
• 納品前に購読を取得し、status が active（契約によっては trialing）であることを確かめている
• pause_collection が設定された購読の扱いを決め、コードに書いている
• 納品の記録は請求書 ID に一意制約を付け、「処理中」を先に取ってから生成に進む
• メール送付は「送信中」を書いてから送り、「送信済み」とメッセージ ID を書く
• 対象期間は明細の period から取り、請求書本体の値だけに頼っていない
• invoice.created に 2xx を返す受け口が本番で常に動いている（止まると確定が最大72時間遅れる）
• 鍵と署名シークレットはコードと設定に書かず、Claude Code の設定で .env の読み取りを拒否している

※ 出典: Stripe Docs — Using webhooks with subscriptions（取得 2026-11）／Claude Code Docs — Settings files and precedence（取得 2026-11）

invoice.paid です。公式の説明では、invoice.paid は支払いが成功したときに加えて、Stripe の外で支払い済みにした（out-of-band）ときにも発生します。銀行振込などで手動入金した月も納品したいなら invoice.paid でないと拾えません。受け取ったら billing_reason と購読の status を見てから納品します。 ※ 出典: Stripe Docs — Types of events（取得 2026-11）

仕様としては支払い失敗で invoice.payment_failed が届き、購読は past_due になります。Stripe は再試行の設定に従って支払いを試み続け、再試行が尽きたあとの状態（canceled・unpaid・past_due のまま・paused）はダッシュボードの設定で決まります。送るかどうかは契約で決める事柄なので、この記事では「past_due の間は送らず、invoice.paid が来た時点で該当期間を送る」を既定にする案を示しています。 ※ 出典: Stripe Docs — Automate payment retries（取得 2026-11）

請求書 ID（in_ で始まる値）です。イベント ID は再送のたびに同じですが、別のイベント（invoice.paid と invoice.payment_succeeded）が同じ請求書で届くことがあるため、イベント ID だけでは防げません。請求書 ID に一意制約を付けた納品記録を先に取り、取れた場合だけ生成と送付に進みます。 ※ 出典: Stripe Docs — Receive Stripe events in your webhook endpoint（取得 2026-11）

できます。サンドボックスのテストクロック（ダッシュボードでは「シミュレーション」）で時間を進めると、更新の請求書・支払い・Webhook が実際に発生します。公式ドキュメントでは、一度に進められるのは購読の間隔2回分までと書かれています。支払い失敗はテスト用カード番号で再現できます。 ※ 出典: Stripe Docs — Test your Billing integration（取得 2026-11）

起点が invoice.paid である点は同じです。違いは2つあります。invoice.upcoming が届かないこと、支払期日を過ぎて未払いのときに購読が past_due になることです。顧客が請求書ページから支払った時点で invoice.paid が届くので、納品は「払われた月に、その期間分を送る」になります。 ※ 出典: Stripe Docs — Using webhooks with subscriptions（取得 2026-11）

まず、今の購読で「送るべき月」と「送ってはいけない月」の条件を書き出してください。billing_reason の値、購読の status、一時停止の有無、解約後の扱いの順に並べます。この条件表があれば、上の指示文の雛形で Claude Code に実装させ、テストクロックで「1か月後」を再現して確かめられます。

契約や業務の都合で条件が決めきれない、既存の決済と納品の仕組みに定期課金を足したい、Claude Code での実装から運用の設計まで一緒に進めたい、という場合は お問い合わせ からどうぞ。今の購読の構成（自動課金かメール請求か、一時停止の運用があるか）を書いていただければ、書面で設計の要点と実装ステップを返します。契約前提ではありません。

Claude の法人導入全般は Claude 導入支援、業務自動化の設計は サービス一覧 にまとめています。

• 2026-11-14: 初版公開

• Stripe 決済から納品メールまでを自動化する — Webhook の署名検証・冪等化と Claude Code の分担
• Claude Code で作った自動化が止まっていないか確かめる
• Claude Code を決まった時刻に動かす — ヘッドレスモードの定期実行
• 社内で Claude Code を使うときのルールの作り方
• 業務自動化の効果の測り方 — 記録表テンプレ
• Claude 導入支援