Stripeで請求内容(Invoice)を更新する

案外整理できてなかったので、自分で振り返るのも兼ねて。

1: Finalizedすると更新できないデータが有る

invoices.updateは下書き状態のものにしか実行できない項目がいくつかあります。

Draft invoices are fully editable. Once an invoice is finalized, monetary values, as well as collection_method, become uneditable.

If you would like to stop the Stripe Billing engine from automatically finalizing, reattempting payments on, sending reminders for, or automatically reconcilinginvoices, pass auto_advance=false.

https://stripe.com/docs/api/invoices/update

金額及びcollection_method以外はfinalized後も編集できる様子ですが、invoice.createdのWebhookで更新処理を実行し、invoice.finalizedされる前に処理した方が機能追加などでトラブルことも少ないかなと思います。

2: Descriptionは請求書・領収書に記載される

Descriptionを利用することで、請求・領収書に任意のテキストを追加できます。

Stripe.invoices.update(
  'in_xxxxx',
  {
    description: 'Description'
  })
  .then(result => {
    console.log(result)
  })

明細のDescriptionではなく、請求・領収書全体のDescriptionであることに注意しましょう。

また、請求・領収書どちらにも表示されることに注意して文言を考える必要がありそうです。

3: Custom Fieldsは請求・領収書右上に

Custom Fieldsという若干謎の項目も存在します。

Stripe.invoices.update(
  'in_xxxxx',
  {
    custom_fields: [{
      name: "Test",
      value: 'Test value'
    }, {
      name: 'Server ID',
      value: 'server XL'
    }]
  })
  .then(result => {
    console.log(result)
  })

これは請求・領収書の右上に請求番号などと一緒に表示されます。

独自の番号（発送番号・サービスIDなど）を各請求に割り当てたい時はこちらを使うと良さそうです。

ただし４つまでしか追加できません。

4: Statement_descriptorは請求の方でみれる

カードの明細にはstatement_descriptorの値が表示されます。

Stripe.invoices.update(
  'in_xxxxx',
  {
    statement_descriptor: 'statement descriptor'
  })
  .then(result => {
    console.log(result)
  })

ダッシュボードではPayment(支払い)の方に出ますので、デバッグ時は見る場所に注意です。

5: 明細そのものは変えれない

各行のテキストについては変更できません。

なのでSubscription時にプラン名などで調整するか、上記のdescription / custom_fields / statement_descriptorを使って表記することになりそうです。

情報元

UPDATE AN INVOICE

https://stripe.com/docs/api/invoices/update