請求書のサマリー項目ベータ

Invoicing API を使用して、請求書のラインアイテムをまとめる方法と非表示にする方法をご紹介します。

このガイドでは、基礎となる API (請求書のサマリー項目) を使用して、請求書のラインアイテムをグループ化する方法について説明します。サマリー項目機能を使用することで、API で請求書のラインアイテムをグループ化できます。

請求書のラインアイテムを動的に分類して表示する場合は、請求書のラインアイテムをグループ化するをご覧ください。

サマリー項目を作成する

既存の下書きの請求書で、下記の説明に従って請求書のサマリー項目を作成します。サマリー項目は、ラインアイテムを割り当てることができるグループを表し、サマリー項目の description フィールドはそれらのラインアイテムのグループヘッダーとして表示されます。

デフォルトでは、Stripe は、サマリー項目に割り当てられているすべてのラインアイテムを表示します。サマリー項目のパラメーターに display_items=none を設定することで、サマリー項目に割り当てられているすべてのラインアイテムを非表示にして、グループヘッダーのみを表示することもできます。display_items=none を設定すると、サマリー項目に割り当てられているすべてのラインアイテムが非表示になります。一部のラインアイテムを選択して非表示にし、その他のラインアイテムを非表示にしないことはできません。ただし、値が 0 USD のラインアイテムは例外です ($0 の個別ラインアイテムを非表示にするセクションをご覧ください)。

Command Line
curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}}
/summary_items \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d description="Summary item 1" \
  -d display_items="none"

サマリー項目を 1 つずつ作成するのではなく、請求書の作成または請求書の更新エンドポイントを使用して一括で作成することもできます。次のコードサンプルでは、2 つのサマリー項目が空になっている下書きの請求書を作成しています。

Command Line
curl https://api.stripe.com/v1/invoices \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "rendering[summary_items_data][0][description]"="Summary item 1" \
  -d "rendering[summary_items_data][0][display_items]"="none" \
  -d "rendering[summary_items_data][1][description]"="Summary item 2" \
  -d "expand[]"="rendering.summary_items"

レスポンスでサマリー項目のリストが表示されるように、必ず、rendering.summary_items を展開してください。

サマリー項目を割り当てる

これで、請求書に空のサマリー項目が含まれるため (請求書にすでにラインアイテムが含まれていることを想定しています)、サマリー項目をラインアイテムに割り当てることができます。

Command Line
curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}}
/lines/{{INVOICE_LINE_ITEM_ID}} \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "rendering[summary_item]"={{SUMMARY_ITEM_ID}}

同じエンドポイントを使用して、ラインアイテムが属するサマリー項目を更新したり、ラインアイテムのグループ化を解除したりできます。

サマリー項目を更新する

請求書の更新エンドポイントを使用すると、サマリー項目の並べ替え、削除、更新を行うことができます。たとえば、次のコードでは、最初と 2 番目のサマリー項目の順序が反転されています。

Command Line
curl https://api.stripe.com/v1/invoices \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "rendering[summary_items_data][0][id]"="{{SUMMARY_ITEM_2_ID}}" \
  -d "rendering[summary_items_data][1][id]"="{{SUMMARY_ITEM_1_ID}}" \
  -d "expand[]"="rendering.summary_items"

請求書からすべてのサマリー項目を削除するには、同じエンドポイントを使用して、次のように rendering[summary_items_data] フィールドの設定を解除します。

Command Line
curl https://api.stripe.com/v1/invoices \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "rendering[summary_items_data]"="" \
  -d "expand[]"="rendering.summary_items"

サマリー項目を削除すると、関連付けられているラインアイテムすべてのグループ化が行われないことになります。

また、以下のように 1 つのサマリー項目を削除することができます。

Command Line
curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}}
/summary_items/{{SUMARY_ITEM_ID}} \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -x DELETE

$0 の個別ラインアイテムを非表示にする

API は、0 USD の個別ラインアイテムの非表示化もサポートしています。請求書の特定のラインアイテムに対して、次のように rendering[display]=hidden_if_zero を設定することができます。

Command Line
curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}}
/lines/{{INVOICE_LINE_ITEM_ID}} \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "rendering[display]"= "hidden_if_zero"

このようにすると、ラインアイテムが 0 USD である場合は、顧客が請求書を確認するすべての場所で自動的に非表示になります。