# 請求書のラインアイテムをグループ化する 請求書のラインアイテムに動的にフィルターを適用してグループ化します。 請求書 (PDF、[オンライン請求書ページ](https://docs.stripe.com/invoicing/hosted-invoice-page.md)、請求書メールなど) を顧客が理解できるようにするには、請求書のラインアイテムを分類してグループごとに表示します。また、ラインアイテムのグループを非表示にすることもできます。これは細かすぎるラインアイテムがある場合に便利で、グループレベルの小計のみが顧客に表示されるように構成できます。 このガイドでは、Stripe ダッシュボードで動的なフィルターとグループを作成して、1 回限りおよびサブスクリプションの請求書を整理する方法について説明します。 ![](https://d37ugbyn3rpeym.cloudfront.net/videos/invoice-line-item-grouping-final.mp4)![サマリー項目がない請求書 PDF](https://b.stripecdn.com/docs-statics-srv/assets/summary-items-ungrouped.aebd6d3acceb95a1dcc27f4cb5f0e1ab.png) グループ化されていないラインアイテム ![サマリー項目が含まれる請求書 PDF](https://b.stripecdn.com/docs-statics-srv/assets/summary-items-grouped.101c38cbe8b978d59a1eb9a59abe5005.png) サマリー項目を使用してグループ化されたラインアイテム (折りたたまれた「Red items (赤色のアイテム)」グループ) ## はじめに 項目のグループ化を設定するには、Invoice Templates 機能を使用する必要があります。Invoice Templates では、Common Expression Language (CEL) の式を使用してルールとテンプレートを定義します。CEL の詳細については、[GitHub の言語定義をご覧ください](https://github.com/google/cel-spec/blob/master/doc/intro.md)。請求書テンプレートの文脈でいくつかの例を示していますが、まずは言語定義を読んで理解することをお勧めします。一般的な[ユースケース](https://docs.stripe.com/invoicing/group-line-items.md#use-cases)から始めることもできます。 ### 制限事項 この機能にはいくつかの制約があります。 - 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 バージョン](https://docs.stripe.com/upgrades.md) `2022-11-15` を使用します。ベータの期間中、それ以降の API バージョンとプレビュー機能のサポートは自動的には行われません。 ## 請求書のラインアイテムをグループ化する ### 請求書の表示テンプレートを作成する 1. Stripe ダッシュボードで**設定 > 請求書テンプレート** に移動します。 1. **テンプレート** セクションで **+ テンプレートを作成** をクリックします。 1. テンプレートに名前を付けます。テンプレートの名前は、テンプレートをサブスクリプションまたは 1 回限りの請求書に適用するときに使用します。 ### ポリシーをテンプレートに追加する テンプレートを作成した後に、ラインアイテムのグループ化ポリシーをテンプレートに追加します。これらのポリシーは CEL で作成します。これにより、Stripe で動的にラインアイテムをフィルターで絞り込み、グループ化できます。 #### ベストプラクティス テンプレートを作成する際、以下に留意してください。 - ポリシーの順序は重要です。たとえば、最初のポリシーでフィルター条件を満たすすべてのラインアイテムが選択された場合、2 番目のポリシーでは、最初のポリシーの適用後にグループに分類されていない残りのすべてのラインアイテムが選択されます。 - `expand()` は、API オブジェクトのフィールドを展開する Stripe 固有のマクロです。Stripe 固有の CEL 式マクロのセクションをご覧ください。 #### CEL 式の作成 請求書テンプレートの CEL 式は、請求書の[項目オブジェクト](https://docs.stripe.com/api/invoice-line-item/object.md)を入力として受け取ります。そのオブジェクトの任意のフィールドを式で使用できます。以下に例を示します。 ```cel line_item.field_name line_item.description ``` `expand()` 関数を使用して、[subscription](https://docs.stripe.com/api/subscriptions/object.md) や [subscription_item](https://docs.stripe.com/api/subscription_items/object.md) など、他の Stripe オブジェクトを指す ID フィールドを拡張できます。たとえば、subscription の metadata にアクセスするには、以下のようにします。 ```cel line_item.subscription.expand().metadata ``` > 展開できる深さは 1 レベルのみです。たとえば、サブスクリプションの決済手段およびタイプのフィールドを展開することはできません。`line_item.subscription.expand().default_payment_method.expand().type` は現在サポートされていません。 ##### Stripe 固有の CEL 式マクロ 標準の CEL 式マクロのリストに加えて、以下の Stripe 固有の関数がサポートされています。 `expand()`: 一般にユーザーが展開できる API フィールドを展開します。たとえば、 CEL 式では、`line_item.invoice_item` は請求書アイテム ID を返します。`line_item.invoice_item.expand()` では、請求書アイテムオブジェクト全体を返します。 #### ラインアイテムのグループ化フィールド ラインアイテムのグループ化には次の 3 つのフィールドがあります。 | フィールド | タイプ | 説明 | | --------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **グループ分け** | CEL 式 ` 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 式 ` boolean>` | ポリシーのラインアイテムを絞り込みます。この式は、請求書のラインアイテムごとに評価されます。特定の請求書のラインアイテムがフィルターに一致すると、そのラインアイテムはこのポリシーで定義されている請求書のラインアイテムグループに追加されます。 たとえば、PO 番号が設定されたラインアイテムをグループ化する場合は、`has(line_item.invoice_item.expand().metadata.PO)` を使用します。ラインアイテムの請求書アイテムリソースにメタデータフィールド `PO` が存在する場合は、式によって `true` が返されます。それ以外の場合は、`false` が返されます。 | | **ラインアイテムを非表示** | 切り替え | 請求書のラインアイテムのグループ化ポリシーによって構成されたサマリー項目を折りたたむか、展開するかを制御します。デフォルトでは、サマリー項目が展開されます。 | ### 請求書の表示テンプレートを 1 回限りの請求書またはサブスクリプションに適用する 請求書のラインアイテムのグループ化ポリシーを使用するには、テンプレートを請求書またはサブスクリプションに適用します。 Stripe ダッシュボードで[請求書エディター](https://dashboard.stripe.com/invoices/create)を使用して、請求書の表示テンプレートを新規請求書および下書きの請求書に適用します。 Stripe ダッシュボードの[サブスクリプションエディター](https://dashboard.stripe.com/subscriptions?create=subscription)を使用して、請求書の表示テンプレートをサブスクリプションに適用します。そのサブスクリプションから生成される今後のすべての請求書で、その表示テンプレートの請求書のラインアイテムのグループ化ポリシーが使用されます。テンプレートの下書きをサブスクリプションの請求書に適用できます。テンプレートを確定済みの請求書に適用することはできません。 [請求書の遷移と確定](https://docs.stripe.com/invoicing/integration/workflow-transitions.md)の詳細をご確認ください。 ## ユースケース 次の表では、グループ化ポリシーの一般的な例をいくつか示しています。 | ユースケース | 詳細と例 | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 請求書のラインアイテムのメタデータでグループ化する | 「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') ``` **絞り込み基準:** ``` line_item.proration ``` | | 説明ごとにラインアイテムをグループ化する | グループ化されていないすべてのラインアイテムは、デフォルトでサマリーの**その他**セクションにグループ化されます。グループ化されていないラインアイテムを説明ごとに一覧表示する場合は、サマリーの下の**その他**セクションを展開できます。他のグループ化ポリシーが上書きされないように、この項目はポリシーリストの最後に配置するようにしてください。 **グループ分け:** ``` line_item.description ``` |