請求書のラインアイテムをグループ化する
請求書のラインアイテムに動的にフィルターを適用してグループ化します。
請求書 (PDF、オンライン請求書ページ、請求書メールなど) を顧客が理解できるようにするには、請求書のラインアイテムを分類してグループごとに表示します。また、ラインアイテムのグループを非表示にすることもできます。これは細かすぎるラインアイテムがある場合に便利で、グループレベルの小計のみが顧客に表示されるように構成できます。
このガイドでは、Stripe ダッシュボードで動的なフィルターとグループを作成して、1 回限りおよびサブスクリプションの請求書を整理する方法について説明します。
CEL 式を使用して請求書のラインアイテムを動的にグループ化します。
グループ化されていないラインアイテム
サマリー項目を使用してグループ化されたラインアイテム (折りたたまれた「Red items (赤色のアイテム)」グループ)
はじめに
ラインアイテムのグループ化を構成するには、請求書テンプレート機能を使用する必要があります。請求書テンプレートでは、Common Expression Language (CEL) 式を使用してルールとテンプレートを定義ます。CEL の詳細については、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 バージョンとプレビュー機能のサポートは自動的には行われません。
請求書のラインアイテムをグループ化する
請求書の表示テンプレートを作成する
- 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 フィールドを拡張できます。たとえば、subscription の metadata にアクセスするには、以下のようにします。
line_item.subscription.expand().metadata
よくある間違い
展開できる深さは 1 レベルのみです。たとえば、サブスクリプションの支払い方法およびタイプのフィールドを展開することはできません。line_ は現在サポートされていません。
Stripe 固有の CEL 式マクロ
In addition to the list of standard CEL expression macros, we support the following Stripe-specific function:
expand(): 一般にユーザーが展開できる API フィールドを展開します。たとえば、 CEL 式では、line_ は請求書アイテム ID を返します。line_ では、請求書アイテムオブジェクト全体を返します。
ラインアイテムのグループ化フィールド
ラインアイテムのグループ化には次の 3 つのフィールドがあります。
| フィールド | タイプ | 説明 |
|---|---|---|
グループ分け | CEL 式 | ラインアイテムのグループ化を制御します。請求書内で、フィルターで除外されていないラインアイテムごとに評価され、文字列を返します。結果の文字列が同じラインアイテムがサマリー項目のグループにまとめられ、結果の文字列はサマリー項目の種目になります。 たとえば、「PO Number」などの静的ラインアイテム名をグループ化する場合、CEL 式は ラインアイテムのメタデータからの「PO」を使用してラインアイテムを動的にグループ化する場合、CEL 式は以下のようになります。
この式では、 |
絞り込み基準 | CEL 式 | ポリシーのラインアイテムを絞り込みます。この式は、請求書のラインアイテムごとに評価されます。特定の請求書のラインアイテムがフィルターに一致すると、そのラインアイテムはこのポリシーで定義されている請求書のラインアイテムグループに追加されます。 たとえば、PO 番号が設定されたラインアイテムをグループ化する場合は、 |
| ラインアイテムを非表示 | 切り替え | 請求書のラインアイテムのグループ化ポリシーによって構成されたサマリー項目を折りたたむか、展開するかを制御します。デフォルトでは、サマリー項目が展開されます。 |
請求書の表示テンプレートを 1 回限りの請求書またはサブスクリプションに適用する
請求書のラインアイテムのグループ化ポリシーを使用するには、テンプレートを請求書またはサブスクリプションに適用します。
Stripe ダッシュボードで請求書エディターを使用して、請求書の表示テンプレートを新規請求書および下書きの請求書に適用します。
Stripe ダッシュボードのサブスクリプションエディターを使用して、請求書の表示テンプレートをサブスクリプションに適用します。そのサブスクリプションから生成される今後のすべての請求書で、その表示テンプレートの請求書のラインアイテムのグループ化ポリシーが使用されます。テンプレートの下書きをサブスクリプションの請求書に適用できます。テンプレートを確定済みの請求書に適用することはできません。
請求書の遷移と確定の詳細をご確認ください。
ユースケース
次の表では、グループ化ポリシーの一般的な例をいくつか示しています。
| ユースケース | 詳細と例 |
|---|---|
請求書のラインアイテムのメタデータでグループ化する | 「PO」という名前のメタデータを使用して各注文番号を請求書の各ラインアイテムに関連付ける営業誘導型のプロセスがあるとします。この例では、グループ分けフィールドで、各注文番号のグループを作成し、メタデータフィールドからのその PO 番号に対応するラインアイテムのリストを表示します。 グループ分け:
絞り込み基準:
|
価格のメタデータを基準にグループ化する | 価格のメタデータで請求書のラインアイテムをグループ化して、購入した価格のタイプで請求書を整理できます。請求書は、価格のメタデータで指定した グループ分け:
絞り込み基準:
|
比例配分でグループ化する | サブスクリプションの請求書に比例配分のラインアイテムが多数あり、顧客向けに請求書をシンプルにしたい場合について考えるとします。この例では、比例配分を適用した金額が 0 USD を超えているラインアイテムを「Credits」というグループに分け、マイナスのラインアイテムを「Debits」というグループに分けます。 グループ分け:
絞り込み基準:
|
説明ごとにラインアイテムをグループ化する | グループ化されていないすべてのラインアイテムは、デフォルトでサマリーのその他セクションにグループ化されます。グループ化されていないラインアイテムを説明ごとに一覧表示する場合は、サマリーの下のその他セクションを展開できます。他のグループ化ポリシーが上書きされないように、この項目はポリシーリストの最後に配置するようにしてください。 グループ分け:
|