請求書のラインアイテムをグループ化する 請求書のラインアイテムに動的にフィルターを適用してグループ化します。
請求書 (PDF、オンライン請求書ページ 、請求書メールなど) を顧客に理解しやすくするには、請求書のラインアイテムを分類してグループごとに表示します。また、ラインアイテムのグループを非表示にすることもできます。これは細かすぎるラインアイテムがある場合に便利で、グループレベルの小計のみが顧客に表示されるように構成できます。
このガイドでは、Stripe ダッシュボードで動的なフィルターとグループを作成して、1 回限りおよびサブスクリプションの請求書を整理する方法について説明します。
CEL 式を使用して請求書のラインアイテムを動的にグループ化します。
グループ化されていないラインアイテム
サマリー項目を使用してグループ化されたラインアイテム (折りたたまれた「Red items (赤色のアイテム)」グループ)
はじめに この機能を使用するには、Common Expression Language (CEL) 式を使用してルールとテンプレートを定義します。CEL の詳細は、Introduction (概要) をお読みください 。このガイドでは、請求書テンプレートのコンテキストにおける例をいくつか紹介しますが、GitHub の公式の言語定義をご覧になることをお勧めします。また、一般的なユースケース から開始することもできます。
制限事項 この機能にはいくつかの制約があります。
CEL 式を適用できるのは、ダッシュボードから作成された請求書のみです。 各 CEL 式の最大文字数は 1024 文字です。 テンプレートに使用できるラインアイテムグループ化ポリシーは最大 10 個です。 各 CEL 式の展開の深さの上限は 1 です。たとえば、line_item.invoice_item.expand().description
はサポートしていますが、line_item.subscription.expand().default_payment_method.expand().type
はサポートしていません。 CEL 式は、公開 API の請求書のラインアイテムオブジェクトのすべてのフィールドをサポートしているわけではありません。 CEL 式は、基本となるリソースとして API バージョン 2022-11-15
を使用します。ベータである間は、それ以降の API バージョンとプレビュー機能のサポートが自動的には行われません。 ダッシュボードで請求書のラインアイテムをグループ化できます。API を使用する場合は、API タブでベータへの早期アクセスをリクエストできます。
請求書の表示テンプレートを作成する Stripe ダッシュボードで設定 > インボイステンプレート に移動します。 テンプレート セクションで + テンプレートを作成 をクリックします。テンプレートに名前を付けます。テンプレートの名前は、テンプレートをサブスクリプションまたは 1 回限りの請求書に適用するときに使用します。 ポリシーをテンプレートに追加する テンプレートを作成した後に、ラインアイテムのグループ化ポリシーをテンプレートに追加します。これらのポリシーは CEL で作成します。これにより、Stripe で動的にラインアイテムをフィルターで絞り込み、グループ化できます。
ベストプラクティス テンプレートを作成する際、以下に留意してください。
ポリシーの順序は重要です。たとえば、最初のポリシーでフィルター条件を満たすすべてのラインアイテムが選択された場合、2 番目のポリシーでは、最初のポリシーの適用後にグループに分類されていない残りのすべてのラインアイテムが選択されます。 expand()
は、API オブジェクトのフィールドを展開する Stripe 固有のマクロです。Stripe 固有の CEL 式マクロのセクションをご覧ください。CEL 式の作成 請求書テンプレートの CEL 式は請求書の line item オブジェクト を入力として取得します。そのオブジェクトの任意のフィールドを式で使用できます。以下に例を示します。
line_item.field_name
line_item.description
expand()
関数を使用して、subscription や subscription_item など、他の Stripe オブジェクトを指す ID フィールドを展開できます。たとえば、サブスクリプションのメタデータにアクセスするには、以下のようにします。
line_item.subscription.expand().metadata
一般的な誤り 展開できる深さは 1 レベルのみです。たとえば、サブスクリプションの決済手段およびタイプのフィールドを展開することはできません。line_item.subscription.expand().default_payment_method.expand().type
は現在サポートされていません。
Stripe 固有の CEL 式マクロ Stripe では現在、標準の CEL 式マクロのリストに加えて、以下の Stripe 固有の関数もサポートしています。
expand()
: 一般にユーザーが展開できる API フィールドを展開します。たとえば、 CEL 式では、line_item.invoice_item
は請求書アイテム ID を返します。line_item.invoice_item.expand()
では、請求書アイテムオブジェクト全体を返します。ラインアイテムのグループ化フィールド ラインアイテムのグループ化には次の 3 つのフィールドがあります。
フィールド タイプ 説明 グループ分け
CEL 式 <line_item => string>
ラインアイテムのグループ化を制御します。請求書内で、フィルターで除外されていないラインアイテムごとに評価され、文字列を返します。結果の文字列が同じラインアイテムがサマリー項目のグループにまとめられ、結果の文字列はサマリー項目の種目になります。
たとえば、「PO Number」などの静的ラインアイテム名をグループ化する場合、CEL 式は PO Number
になります。
ラインアイテムのメタデータからの「PO」を使用してラインアイテムを動的にグループ化する場合、CEL 式は以下のようになります。
'PO Number' + line_item.invoice_item.expand().metadata['PO']
この式では、metadata['PO'] = 123
が設定されているラインアイテムが「PO Number: 123」として評価されます。複数のラインアイテムが厳密に同じ文字列として評価される場合は、「PO Number: 123」という種目のサマリー項目でグループ化されます。
絞り込み基準
CEL 式 <line_item => boolean>
ポリシーのラインアイテムを絞り込みます。この式は、請求書のラインアイテムごとに評価されます。特定の請求書のラインアイテムがフィルターに一致すると、そのラインアイテムはこのポリシーで定義されている請求書のラインアイテムグループに追加されます。
たとえば、PO 番号が設定されたラインアイテムをグループ化する場合は、has(line_item.invoice_item.expand().metadata.PO)
を使用します。ラインアイテムの請求書アイテムリソースにメタデータフィールド PO
が存在する場合は、式によって true
が返されます。それ以外の場合は、false
が返されます。
ラインアイテムを非表示 切り替え 請求書のラインアイテムのグループ化ポリシーによって構成されたサマリー項目を折りたたむか、展開するかを制御します。デフォルトでは、サマリー項目が展開されます。
請求書の表示テンプレートを 1 回限りの請求書またはサブスクリプションに適用する 請求書のラインアイテムのグループ化ポリシーを使用するには、テンプレートを請求書またはサブスクリプションに適用します。
Stripe ダッシュボードで請求書エディター を使用して、請求書の表示テンプレートを新規請求書および下書きの請求書に適用します。
Stripe ダッシュボードのサブスクリプションエディター を使用して、請求書の表示テンプレートをサブスクリプションに適用します。そのサブスクリプションから生成される今後のすべての請求書で、その表示テンプレートの請求書のラインアイテムのグループ化ポリシーが使用されます。テンプレートの下書きをサブスクリプションの請求書に適用できます。テンプレートを確定済みの請求書に適用することはできません。
請求書の遷移と確定 の詳細をご確認ください。
次の表では、グループ化ポリシーの一般的な例をいくつか示しています。
ユースケース 詳細と例 請求書のラインアイテムのメタデータでグループ化する
「PO」という名前のメタデータを使用して各注文番号を請求書の各ラインアイテムに関連付ける営業誘導型のプロセスがあるとします。この例では、グループ分け フィールドで、各注文番号のグループを作成し、メタデータフィールドからのその PO 番号に対応するラインアイテムのリストを表示します。
グループ分け:
'PO - ' + line_item.invoice_item.expand().metadata.purchase_order_number
絞り込み基準:
has(line_item.invoice_item.expand().metadata.purchase_order_number)
価格のメタデータを基準にグループ化する
価格のメタデータで請求書のラインアイテムをグループ化して、購入した価格のタイプで請求書を整理できます。請求書は、価格のメタデータで指定した section
文字列に従って分類されます。
グループ分け:
line_item.price.metadata.section
絞り込み基準:
has(line_item.price.metadata.section)
比例配分でグループ化する
サブスクリプションの請求書に比例配分のラインアイテムが多数あり、顧客向けに請求書をシンプルにしたい場合について考えるとします。この例では、比例配分を適用した金額が 0 USD を超えているラインアイテムを「Credits」というグループに分け、マイナスのラインアイテムを「Debits」というグループに分けます。
グループ分け:
'Proration ' + (line_item.amount > 0 ? 'Debits' : 'Credits')
絞り込み基準:
説明ごとにラインアイテムをグループ化する
グループ化されていないすべてのラインアイテムは、デフォルトでサマリーのその他 セクションにグループ化されます。グループ化されていないラインアイテムを説明ごとに一覧表示する場合は、サマリーの下のその他 セクションを展開できます。他のグループ化ポリシーが上書きされないように、この項目はポリシーリストの最後に配置するようにしてください。
グループ分け: