Ajoute la possibilité de détailler les montants des réductions au prorata

Nouveautés

Ajoute la possibilité de détailler les montants des remises au prorata, afin que les montants au prorata et les montants des remises soient affichés de manière cohérente avec les montants non calculés au prorata. Lorsque cette option est activée, les propriétés du montant au prorata affichent les montants bruts avant que les remises ne soient appliquées, et les montants des remises incluent les montants réels des remises appliquées. Lorsque cette option est désactivée, les propriétés des remises au prorata incluent les identifiants des remises, mais les montants des remises sont égaux à 0.

Impact

Vous pouvez désormais détailler les montants des réductions au prorata en définissant le paramètre proration_discounts sur itemized lors de la création d’abonnements, de planifications d’abonnement, de devis, de sessions Checkout ou de factures préliminaires. Vous pouvez également définir ce paramètre sur itemized pour un abonnement existant en le migrant. Cependant, vous ne pouvez pas migrer un abonnement de itemized à included.

Récapitulatif des modifications

Exemple : prorata d’un d bit brut de 10 USD avec une réduction de 10 % au niveau de l’élément et une réduction de 2 USD au niveau du groupe.

Inclus :

L’exemple suivant illustre le comportement existant, avec des réductions déjà appliquées :

Réponse :

// 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
}

Détaillé :

Demande :

// 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 ...
}

Réponse :

// 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
}

Considérations de mise à niveau

• Portée : cette fonctionnalité est uniquement disponible pour les abonnements avec un mode de facturation flexible.
• Migration unidirectionnelle : une fois que vous avez activé les montants de réduction détaillés pour un abonnement, vous ne pouvez pas le reconfigurer sur « inclus ».
• Modifications de code requises : si votre intégration lit les propriétés relatives au montant au prorata en attente de valeurs nettes, mettez-la à jour pour utiliser plutôt la nouvelle propriété net_amount.
• Factures historiques : les factures existantes reflètent le comportement actif lorsque vous les avez créées.
• Service de support facture mixte : les factures uniques peuvent contenir à la fois des postes de facture au prorata inclus et détaillés si vous migrez un abonnement entre deux créations de prorata.

Modifications

Mise à niveau