Invoices API の更新
Stripe API の以前のバージョンでは、Invoice (インボイス) にステータスがなく、代わりに、closed
、paid
、forgiven
などの一連のブール値がありました。
Stripe のインボイスと財務ワークフローをより適切に関連付けるために、インボイスにステータスを導入しました。これにより、すべての Invoice (インボイス) オブジェクトに status
プロパティが含まれます。status
フィールドの値は、draft
、open
、paid
、void
、および uncollectible
のいずれかです。
draft
ステータスは、インボイスが変更可能であることを示します。open
ステータスは、インボイスが確定されて変更できなくなり、支払いの準備ができていることを示します。paid
ステータスは、インボイスが全額支払われたことを示します。void
ステータスは、インボイスが無効になったことを示します。uncollectible
ステータスは、インボイスが支払われる可能性が非常に低く、不良債権と見なされる可能性があることを示します。
これらのステータスとステータス間の移行の詳細については、請求処理ガイドを参照してください。
インボイスのタイムラインの例
このセクションでは、1 回限りのインボイスとサブスクリプションのインボイスのタイムラインのサンプルを提示し、両タイプのインボイスの進行段階でのステータスを紹介します。
1 回限りのインボイスの例
これは、1 回限りのインボイスが経るタイムラインの一例です。このイベントシーケンスは、既存のインボイスタイムラインと同じです。唯一の違いは、Stripe がインボイスのステータスをより明確に示すために status
を公開するようになったことです。
- 11 月 16 日: API を使用して、12 個の部品を顧客に出荷することを示すインボイスを作成したとします。Stripe は
invoice.created
Webhook を送信して、このインボイスの作成をお客様に通知します。API を見ると、インボイスがstatus='draft'
であることがわかります。 - 11 月 26 日: インボイスの確認後、会計士は Stripe ダッシュボードを使用してインボイスを確定します。インボイスの確定中に、そのステータスが
status='open'
に更新され、finalized_at
フィールドが設定されます。Stripe はinvoice.finalized
Webhook を送信し、インボイスが確定されたことを通知します。 - 11 月 26 日: 数秒後、Stripe はインボイスをメールで送信し、再試行を開始します。CRM システムがインボイスの送信時期を追跡できるように、インボイスが送信されるたびに Stripe は
invoice.sent
Webhook を送信します。 - 12 月 1 日: 顧客はメールのリンクをクリックし、オンライン請求書の支払いページを使用してインボイスを支払います。残念ながら、顧客は有効期限切れのクレジットカードで支払います。支払いは失敗し、Stripe はこの失敗を通知する
invoice.payment_failed
Webhook をお客様に送信します。 - 12 月 3 日: 更新されたクレジットカードを使用して、顧客が再試行します。今回は支払いが成功しました。Stripe は、この成功を通知する
invoice.paid
Webhook をお客様に送信し、カードを保存して、インボイスをstatus='paid'
に設定します。設定されている場合、Stripe はインボイスが支払われたことを示す領収書もすぐに顧客にメールで送信します。
サブスクリプションのインボイス例
サブスクリプションで生成されたインボイスのタイムライン例を次に示します。
- 11 月 13 日: ダッシュボードを通じ、自動請求を設定した顧客の継続的なサブスクリプションを作成します。このサブスクリプションには、20 日間のトライアルがあるため、初回のインボイスは 20 日後 (12 月 3 日) です。Stripe は
customer.subscription.created
Webhook を送信します。
- 11 月 30 日: トライアルが終了する 3 日前に、Stripe は
customer.subscription.trial_will_end
Webhook を送信します。クレジットカードに請求する 3 日前に、トライアルに関するリマインドメールを送信することをお勧めします。
- 12 月 3 日: トライアルの終了時に
status='draft'
インボイスが作成されます。Stripe はinvoice.created
Webhook を送信して、このインボイスの作成をお客様に通知します。 - 12 月 3 日: 約 1 時間後、インボイスは自動的に確定されます。この結果、
status
が'open'
に更新され、finalized_at
が設定され、invoice.finalized
Webhook が送信されます。 - 12 月 3 日: その後すぐに、Stripe は登録されている顧客のカードに請求し、支払いは成功します。Stripeは、この成功を通知するために
invoice.paid
Webhook を送信し、インボイスをstatus='paid'
に設定します。
新しい API メソッド
Stripe は、インボイスのステータスを管理するための一連の新しい API をリリースしました。以下のアップグレードチェックリストで詳しく説明されている新しいオプションは次のとおりです。
- インボイスの送信: Stripe は、インボイスをメールで自動的に送信および再送信します。Stripe API で利用できるこのエンドポイントを使用すると、いつでもインボイスを顧客に送信できます。
- インボイスの確定: 上記の例では、会計担当者は Stripe ダッシュボードを使用してインボイスを確定しました。この機能は、Stripe API でも利用できます。
- インボイスの無効化: インボイスがいったん確定されると、削除することはできません。「無効化」は、インボイスが誤って発行されたことを示すために使用されます。たとえば、会社名に誤りがあるインボイスを無効にしてから、新しいインボイスを作成して置き換えることができます。
- ドラフトインボイスの削除: このアクションはドラフトインボイスにのみ適用されます。削除されたインボイスは、ダッシュボードまたは API に表示されません。また、削除は取り消すことができません。
- インボイスを回収不可能としてマーク: 経理部門で「貸倒れ」の記録を管理することをお勧めします。貸倒れの記録とは、回収不可能と思われるインボイスのリストを示します。この API を使用して、該当するインボイスにタグを付けることができます。
アップグレードのチェックリスト
次のセクションでは、Invoice
オブジェクトの機能変更とインボイスに関連する Webhook の機能変更を示します。
Invoice
オブジェクト
ステータスと動作をユーザが理解しやすいように、Invoice
オブジェクトにいくつかのフィールドを追加しました。
finalized_at
新しい finalized_at
フィールドは、インボイスが確定した時刻を示します。これは、すべての API バージョンで行われたリクエストで利用できます。
status
新しい status
フィールドは、すべての API バージョンで行われたリクエストに使用できます。これにより、次のようなインボイスの多くのブール値が置き換えられます。
- 2018-11-08 バージョン以降で作成されたリクエストでは、
paid=true
ブールが削除されました。その代わりに、それに対応するstatus='paid'
を確認してください。 - 2018-11-08 以降のバージョンで行われたリクエストの場合、
forgiven=true
ブール値は削除されます。代わりに、等価のstatus='uncollectible'
を確認します。
auto_advance
新しい auto_advance
フィールドは、自動回収が有効かどうかを示します。'draft'
および 'open'
ステータスの場合、auto_advance
フィールドを更新できます。それ以外の場合、 auto_advance
は常に false
です。
auto_advance=false
の場合、Stripe は以下を 「行いません」:
- ドラフトインボイスの自動発行
collection_method='send_invoice'
インボイスの最初の (またはリマインダー) メールの自動送信collection_method='charge_automatically'
インボイスの初めての (または再試行の) 支払いを自動で試行する
auto_advance=false
が指定されていても、Stripe はインバウンドの銀行振込を自動的に消し込みます。振込がインボイスを参照している場合、銀行振込はそのインボイスに対して消し込まれます。インボイスが指定されていない場合、Stripe は未払いのインボイスを検索してその支払いを試みます。
ステータスが 'uncollectible'
、'void'
、および 'paid'
のインボイスの場合、auto_advance
フィールドは常に false
です。
2018-11-08 以前のバージョンでは、closed
フィールドがまだ存在し、これは auto_advance
の逆に等しくなります。たとえば、auto_advance=true
は closed=false
と同等です (この逆も成り立ちます)。以前の API バージョンを使用して作成されたインボイスは、引き続きデフォルトで closed=false
になります。
Webhook
この更新では、次の 3 点の新しい Webhook が導入されました。
invoice.finalized
: インボイスが確定された際に送信されます。invoice.voided
: インボイスが無効になった際に送信されます。invoice.marked_uncollectible
: インボイスが回収不能とマークされた際に送信されます。
インボイスを作成すると、既存の invoice.created
Webhook が送信されます。お客様の Webhook ハンドラーで 1 回限りのインボイスとサブスクリプションで生成されたインボイスを区別する必要がある場合には、Webhook の本文に invoice.subscription
プロパティがあるかかどうかを確認します。
以下の既存の Webhook には変更はありません: