比例配分割引額を明細化する機能を追加
新機能
比例配分割引額を明細化する機能が追加され、比例配分金額と割引額が非比例配分と一貫して表示されます。有効にすると、比例配分 金額 プロパティには割引が適用される前の総金額が表示され、割引金額 には、実際に適用された割引金額が含まれます。無効にすると、比例配分割引プロパティには割引 ID が含まれますが、割引額は 0 です。
影響
サブスクリプション、サブスクリプションスケジュール、見積もり、Checkout Sessions、またはプレビュー請求書を作成する際に、proration_discounts パラメーターを itemized に設定することで、比例配分割引額を項目別に表示できるようになりました。また、移行することで、既存のサブスクリプションに対してこのパラメーターを itemized に設定することもできます。ただし、サブスクリプションを itemized から included に移行することはできません。
変更の概要
| オブジェクト | プロパティ | 含まれる機能 | 項目別 (新しい動作) |
|---|---|---|---|
| 比例配分項目 | amount | 正味金額 (割引後) | 総額 (割引前) |
discount_ | 商品レベルの割引の不足。グループレベルの割引は、amount=0 を表示 | 正確な金額に含まれるすべての割引 | |
| インボイスアイテム | amount | 正味金額 | 総額 |
net_ (新しいプロパティ) | 割引不可のインボイスアイテムの正味金額。それ以外の場合は null | 割引不可のインボイスアイテムの正味金額。それ以外の場合は null | |
proration_ (新しいプロパティ) | amount=0 に含まれるすべての割引 | 正確な金額に含まれるすべての割引 | |
| 請求書 | total_ | 比例配分割引を除く | 比例配分割引あり |
subtotal | 正味の比例配分金額を含みます (割引はすでに適用されています) | 項目別割引後の比例配分金額あり (グループ別割引は別途適用) |
例: 10 USD の総借方比例配分、10% の項目レベル割引と 2 USD のグループレベルの割引
あり:
次の例は、割引が既に適用されている既存の動作を示しています。
レスポンス:
// Line Item { "proration": true, "amount": 700, // Net: 7 USD after discounts (10 USD - 1 USD item - 2 USD group) "discount_amounts": [ // Item-level discount missing entirely {"amount": 0, "discount": "di_group_2off"} // Group-level shows ID but no amount ] } // Invoice Item { "proration": true, "amount": 700 // Net amount only } // Invoice { "total_discount_amounts": [ {"amount": 0, "discount": "di_group_2off"} // Missing item-level proration discount ], "subtotal": 700 // Adds proration amount after all discounts }
項目別:
リクエスト:
// POST /v1/subscriptions { // ... omitting irrelevant fields ... billing_mode: { type: "flexible", flexible: { // New parameter: only available when billing mode type is flexible proration_discounts: "itemized" // Default value is "included" } } // ... omitting irrelevant fields ... }
レスポンス:
// Line Item { "proration": true, "amount": 1000, // Gross: 10 USD before discounts "discount_amounts": [ {"amount": 100, "discount": "di_item_10pct"}, // Item-level discount now visible {"amount": 200, "discount": "di_group_2off"} // Group-level with actual amount ] } // Invoice Item { "proration": true, "amount": 1000, // Gross amount "net_amount": 700, // New property: net amount after both discounts "proration_details": { // New property: populated when the invoice item is a proration "discount_amounts": [ {"amount": 100, "discount": "di_item_10pct"}, {"amount": 200, "discount": "di_group_2off"} ] } } // Invoice { "total_discount_amounts": [ {"amount": 100, "discount": "di_item_10pct"}, // Now includes item-level proration discount {"amount": 200, "discount": "di_group_2off"} // Now includes group-level proration discount ], "subtotal": 9000 // Includes proration amount after item-level discounts }
アップグレードに関する考慮事項
- 範囲: この機能は、柔軟な課金モードのサブスクリプションでのみ使用できます。
- 一方向の移行: サブスクリプションの項目別割引金額を有効にした後は、含まれる割引額に戻すことはできません。
- コードの変更が必要: 統合により、正味値を期待する比例配分 金額プロパティが読み取られる場合は、代わりに新しい net_amount プロパティを使用するように更新します。
- 過去の請求書: 既存の請求書には、請求書の作成時にアクティブであった動作が反映されます。
- 混合請求書のサポート: 比例配分の作成の間にサブスクリプションを移行する場合、1つの請求書には、含まれる比例配分明細項目と項目別の比例配分明細項目の両方を含めることができます。