Planifications d'abonnement

Utilisez les planifications d’abonnement pour automatiser les modifications apportées aux abonnements au fil du temps. Vous pouvez créer directement un abonnement en même temps que vous créez votre planification ou bien ajouter une planification à un abonnement déjà existant. Utilisez l’attribut phases pour définir les modifications que vous souhaitez apporter à l’abonnement. Une fois toutes ses phases achevées, une planification expire en mettant en œuvre son paramètre end_behavior.

Voici quelques exemples de modifications que vous pouvez planifier :

• Démarrage d’un abonnement à une date ultérieure
• Antidatage d’un abonnement à une date antérieure
• Passage à un abonnement supérieur ou inférieur

Les planifications d’abonnement sont disponibles dans le Dashboard Stripe Billing et dans l’API. Voici une courte vidéo décrivant le fonctionnement des planifications d’abonnement dans le Dashboard :

Cette page aborde en détail le fonctionnement des planifications d’abonnement. Pour obtenir des exemples d’utilisation, veuillez vous reporter à la page Cas d’usage.

Phases

Lorsque vous créez une planification d’abonnements, utilisez l’attribut phases pour définir à quel moment les modifications doivent entrer en application ainsi que les propriétés de l’abonnement qui doivent être modifiées. Imaginons par exemple que vous avez décidé de proposer un bon de réduction de 50 % sur les trois premiers mois d’un abonnement. Dans un scénario de ce type, il vous suffit dès lors de créer une planification d’abonnement avec une première phrase de trois mois appliquant votre bon de réduction de 50 %. Au passage à la seconde phase, l’abonnement retrouvera son coût normal et le bon de réduction sera supprimé. Les phases doivent être séquentielles, ce qui signifie qu’une seule phase peut être active à la fois. Vous pouvez avoir jusqu’à 10 phases.

Définir la durée d’une phase

La période définie pour un tarif détermine la fréquence de facturation d’un abonnement. Par exemple, avec une période mensuelle, une facture est émise chaque mois. Les phases possèdent un attribut itérations que vous pouvez utiliser pour spécifier la durée d’une phase. Multipliez cette valeur par la période pour obtenir la durée d’une phase. Si une planification d’abonnement utilise un tarif avec une période mensuelle et que vous définissez iterations=2, la phase durera deux mois.

L’end_date d’une phase doit correspondre à la start_date de la phase suivante. L’utilisation de iterations vous permet de définir automatiquement vos start_date et end_date de manière appropriée. Vous pouvez définir ces valeurs manuellement, mais Stripe vous recommande d’utiliser iterations. L’introduction d’erreurs étant toujours possible avec une saisie manuelle, il est préférable de ne définir manuellement les dates de début et de fin que dans les cas d’usage complexes.

Passer à la phase suivante

Les transitions de phase se produisent automatiquement une fois que le end_date d’une phase est atteint. Lorsque qu’une phase arrive à son terme, Stripe modifie l’abonnement en fonction des attributs de la phase suivante. Vous pouvez éventuellement activer les calculs au prorata afin de créditer l’utilisateur pour les postes ou le temps non utilisés dans le cadre de l’abonnement.

Comportement des calculs au prorata

Il existe deux paramètres différents de comportement des calculs au prorata qui contrôlent la manière dont Stripe traite les réajustements de facturation lors des modifications de la planification d’un abonnement :

1. Comportement des calculs au prorata pour la mise à jour d’une planification d’abonnement : Le paramètre proration_behavior de premier niveau contrôle la manière de gérer les calculs au prorata lors de la mise à jour d’une planification d’abonnement d’une manière qui affecte la configuration de facturation de la phase en cours (par exemple, la modification des prix ou des quantités).

2. Comportement des calculs au prorata pendant la transition de phase : Chaque phase possède son propre attribut proration_behavior qui contrôle la manière dont Stripe gère les calculs au prorata lors de la transition vers cette phase.

Comportement des calculs au prorata pour la mise à jour d’une planification d’abonnement

Lorsque vous mettez à jour une planification d’abonnement et modifiez la configuration de facturation de current_phase, vous pouvez contrôler la manière dont les calculs au prorata sont traités à l’aide du paramètre proration_behavior de premier niveau.

Ce paramètre fonctionne de manière similaire à celui de l’API pour la mise à jour des abonnements et accepte les valeurs suivantes :

• create_prorations (par défaut) : Générez des réajustements au prorata pour les changements de facturation.
• none : Aucun calcul au prorata n’est créé pour la mise à jour.
• always_invoice : Générez des calculs au prorata et finalisez immédiatement une facture.

Les modifications apportées à des champs autres que la facturation (comme les métadonnées) ne généreront pas de calcul au prorata, quel que soit ce paramètre.

Comportement des calculs au prorata pendant la transition de phase

Chaque phase peut définir son propre proration_behavior pour contrôler ce qui se passe lorsque l’abonnement entre dans cette phase. Ce paramètre s’applique spécifiquement aux calculs au prorata générés pendant les transitions de phase et est enregistré en tant que champ sur la phase.

Par exemple, si phases[1] augmente la quantité de 1 à 3 au début, le proration_behavior sur phases[1] détermine comment ces calculs au prorata sont gérés lors du passage de phases[0] à phases[1] :

• create_prorations (par défaut) : Générez des postes de facture en attente pour les modifications de facturation.
• none : Aucun calcul au prorata n’est créé au début de cette phase.
• always_invoice : Générez des calculs au prorata et créez immédiatement une facture lorsque vous entrez dans cette phase.

Si vous devez modifier le traitement au prorata d’une transition de phase future, mettez à jour le paramètre proration_behavior de la phase future avant qu’elle ne devienne active.

Utiliser des périodes d’essai

Vous pouvez ajouter une période d’essai sur une phase en définissant une date de fin de la période d’essai. Si vous souhaitez que la période d’essai s’étale sur l’intégralité de la phase, définissez une valeur trial_end identique à la end_date de la phase. Vous pouvez aussi définir trial_end sur une date antérieure à la end_date si vous souhaitez que la période d’essai ne couvre qu’une partie de la phase. Lorsque vous planifiez des mises à jour, vous devez spécifier la nouvelle trial_end pour chaque phase.

Réaliser une planification

Les planifications d’abonnement prennent fin une fois la dernière phase terminée. À ce stade, l’abonnement est laissé tel quel et n’est plus associé à la planification. Si vous souhaitez annuler un abonnement après la dernière phase de planification, vous pouvez définir le paramètre end_behavior sur cancel. L’attribut cancel_on_date de l’abonnement n’est défini que lorsque l’abonnement débute sa phase finale.

Héritage des attributs de phase

Lorsqu’une phase est active, tous les attributs définis sur la phase sont aussi définis sur l’abonnement. À l’issue de la phase, les attributs restent les mêmes, à moins que la phase suivante ne les modifie ou que la planification ne possède pas de paramètres par défaut. Un certain nombre d’attributs peuvent être définis sur les planifications et sur les phases. Ces attributs sont les suivants :

Lorsque l’un de ces attributs est défini sur la planification, il est utilisé par défaut par toutes les phases. Lorsqu’une même propriété est définie sur la planification et sur la phase, l’attribut de phase remplace l’attribut de planification. Les règles comportementales appliquées sont les suivantes :

Utiliser des métadonnées de phase

Vous pouvez utiliser les phases de planification d’abonnement pour définir les métadonnées de l’abonnement sous-jacent. Cela vous permet de contrôler les métadonnées d’un abonnement avec des mises à jour planifiées.

{
  ...
  "object": "subscription_schedule",
  "phases": [
    { // Phase 1
      ...
      "metadata": {
        "channel": "self-serve",
        "region": "apac",
        "upsell-products": "alpha"
      },
    },
    { // Phase 2
      ...
      "metadata": {
        "channel": "sales",
        "churn-risk": "high",
        "upsell-products": ""
      },
    }
  ],
}

{
  ...
  "object": "subscription",
  "metadata": {
    "channel": "self-serve",
    "region": "apac",
    "upsell-products": "alpha"
  },
}

{
  ...
  "object": "subscription",
  "metadata": {
    "channel": "sales",
    "region": "apac",
    "churn-risk": "high"
  }
}

Apprenez comment copier des métadonnées d’abonnement sur des factures d’abonnement.

Créer des planifications d’abonnement

Des exemples plus complets sont disponibles à la page des cas d’usage, mais voici d’ores et déjà une première illustration simple de la façon de créer une planification d’abonnement avec un client. Lorsque vous créez une planification de cette manière, l’abonnement est automatiquement créé du même coup.

curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=cus_GBHHxuvBvO26Ea \
  -d start_date=now \
  -d end_behavior=release \
  -d "phases[0][items][0][price]"=price_1GqNdGAJVYItwOKqEHb \
  -d "phases[0][items][0][quantity]"=1 \
  -d "phases[0][iterations]"=12

curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d from_subscription=sub_GB98WOvaRAWPl6

Modifier les planifications d’abonnement

Vous ne pouvez mettre à jour que la phase actuelle et les phases futures des planifications d’abonnement.

curl https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "phases[0][items][0][price]"=
{{PRICE_ID}} \
  -d "phases[0][items][0][quantity]"=2 \
  -d "phases[0][start_date]"=1577865600 \
  -d "phases[0][end_date]"=1580544000

curl https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "phases[0][items][0][price]"=
{{PRICE_ID}} \
  -d "phases[0][items][0][quantity]"=1 \
  -d "phases[0][start_date]"=1577865600 \
  -d "phases[0][end_date]"=now \
  -d "phases[1][items][0][price]"=
{{PRICE_ID}} \
  -d "phases[1][items][0][quantity]"=2 \
  -d "phases[1][start_date]"=now \
  -d "phases[1][end_date]"=1580544000

curl https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "phases[0][items][0][price]"=
{{PRICE_ID}} \
  -d "phases[0][items][0][quantity]"=1 \
  -d "phases[0][start_date]"=1577865600 \
  -d "phases[0][end_date]"=1580544000 \
  -d "phases[1][items][0][price]"=
{{PRICE_ID}} \
  -d "phases[1][items][0][quantity]"=2 \
  -d "phases[1][iterations]"=1

Prévisualiser une facture

Utilisez le paramètre planification dans l’aperçu de création pour prévisualiser la facture suivante d’une planification d’abonnement.

curl https://api.stripe.com/v1/invoices/create_preview \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d schedule=
{{SUBSCRIPTION_SCHEDULE_ID}}

Aperçu de la création et des mises à jour de planifications

Utilisez les paramètres dans schedule_details pour prévisualiser la création ou la mise à jour d’une planification d’abonnement. Transmettez une planification existante pour indiquer à Stripe s’il s’agit d’une création ou d’une mise à jour.

Transmettez toutes les phases actuelles et futures que vous prévisualisez.

Par exemple, le code suivant affiche un aperçu de la première facture d’une planification d’abonnement avec une phase 1 qui s’étend sur 12 périodes de facturation.

curl https://api.stripe.com/v1/invoices/create_preview \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "customer_details[address][line1]"="920 5th Ave" \
  -d "customer_details[address][city]"=Seattle \
  -d "customer_details[address][state]"=WA \
  -d "customer_details[address][postal_code]"=98104 \
  -d "customer_details[address][country]"=US \
  -d "schedule_details[phases][0][start_date]"=now \
  -d "schedule_details[phases][0][items][0][price]"=
{{PRICE_ID}} \
  -d "schedule_details[phases][0][items][0][quantity]"=1 \
  -d "schedule_details[phases][0][iterations]"=12

Autres considérations

Les planifications d’abonnement présentent généralement les mêmes restrictions que les abonnements, mais ont également leurs propres restrictions. De plus, l’interaction entre les planifications d’abonnement et les abonnements peut produire un comportement inattendu. Consultez les sections suivantes pour comprendre les limitations, le comportement des produits et les bonnes pratiques générales d’utilisation de planifications d’abonnement.

Restrictions

• Vous ne pouvez définir que 10 phases actuelles ou futures à la fois sur une planification d’abonnement. Les phases passées ne sont pas prises en compte dans cette limite.
• Les phases de planification d’abonnement présentent également les mêmes restrictions que les abonnements lors de la création de phases de planification d’abonnement avec plusieurs postes.

Limites du Dashboard

Vous pouvez créer ou modifier des planifications d’abonnement sans code dans le Dashboard.

Le Dashboard vous permet de définir les paramètres suivants pour l’ensemble des phases, mais pas pour des phases individuelles :

• Seuils de facturation
• Moyens de paiement
• Paramètres de facturation
• Description de l’abonnement
• Période d’essai (disponible uniquement pour la première phase)

Les paramètres suivants ne sont pas pris en charge dans le Dashboard :

• Métadonnées de planification d’abonnement
• Métadonnées du poste de phase
• Devise
• Tous les paramètres Connect

Mises à jour d’un abonnement associé à une planification

Utilisez les planifications d’abonnement pour modifier automatiquement les abonnements au fil du temps et au passage à la phase suivante de l’abonnement. Certaines modifications que vous apportez directement à l’abonnement se propagent aux phases de la planification d’abonnement, mais pas toutes. Cela signifie que toute modification apportée directement à l’abonnement peut être remplacée par la planification d’abonnement lors du passage à la phase suivante.

Lorsque vous prévoyez de modifier un abonnement, suivez ces bonnes pratiques :

• Si un abonnement est associé à une planification d’abonnement, utilisez l’API Subscription Schedule pour modifier l’abonnement, au lieu de l’API Subscriptions.
• Enregistrez les ID de planification d’abonnement avec l’ID d’abonnement pour les futures mises à jour de l’API. L’ID de planification d’abonnement est renvoyé lorsque vous utilisez l’API pour le créer ou via le webhook subscription_schedule.created lorsque Stripe le crée automatiquement, par exemple lorsqu’un client a planifié un passage à une offre inférieure dans le portail client.
• Supprimez les identifiants de la planification d’abonnement lorsqu’une planification d’abonnement est publiée. Vous pouvez modifier les abonnements directement ou créer une nouvelle planification d’abonnement. L’identifiant de la planification d’abonnement est renvoyé lorsqu’il est publié avec l’API ou via l’événement de webhook subscription_schedule.released lorsque la planification d’abonnement est publiée.
• Utilisez le Dashboard pour modifier les abonnements, si possible, ce qui met automatiquement à jour toute planification d’abonnement associée.

Plus précisément, lorsque vous modifiez l’un des attributs d’abonnement suivants directement sur un abonnement, cette action peut créer automatiquement une nouvelle phase de planification d’abonnement :

• discounts
• tax_rates
• items
• trial_end, trial_settings, trial_start
• application_fee_percent
• add_invoice_items
• automatic_tax

Prenons l’exemple d’un abonnement comportant deux éléments. L’abonnement a une planification d’abonnement associée avec une phase unique, reflétant l’état actuel de l’abonnement. Si vous utilisez l’API pour supprimer l’un des éléments, la phase de la planification d’abonnement associée est automatiquement divisée en deux phases :

1. La phase qui vient de s’achever et qui comportait deux éléments d’abonnement
2. La nouvelle phase qui n’a qu’un seul élément à l’abonnement

Lorsque les phases de la planification d’abonnement se divisent automatiquement, les propriétés suivantes sont copiées de la phase en cours vers la nouvelle phase :

• proration_behavior
• billing_cycle_anchor
• cancel_at_period_end
• description
• metadata
• pause_collection

En outre, Stripe peut copier les attributs d’abonnement généraux suivants dans la planification d’abonnement ou ses default_settings :

Les mises à jour des metadata d’un abonnement ne sont pas propagées vers une planification d’abonnement associée.