Planifications d'abonnement
Découvrez les planifications d'abonnements et apprenez à les utiliser.
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. Cette vidéo présente le fonctionnement des planifications d’abonnement dans le Dashboard :
Planifications d’abonnement dans le Dashboard
Pour découvrir comment utiliser les planifications d’abonnement, consultez la section Cas d’usage.
Phases
Lorsque vous créez une planification d’abonnement, utilisez l’attribut phases pour définir à quel moment les changements doivent avoir lieu et quelles propriétés de l’abonnement doivent être modifiées. Par exemple, vous pouvez offrir un bon de réduction de 50 % les trois premiers mois d’un abonnement. Dans ce scénario, vous créez une planification d’abonnement dont la première phase s’étend sur trois mois et contient le bon de réduction de 50 %. Dans un deuxième temps, l’abonnement revient au coût normal et le bon de réduction est supprimé. Les phases doivent être séquentielles, c’est-à-dire qu’une seule phase peut être active à un moment donné. Vous pouvez avoir jusqu’à 10 phases.
Définir la durée d’une phase
Vous pouvez définir la durée d’une phase à l’aide de l’API ou du tableau de bord.
Passer à la phase suivante
Les transitions de phase se produisent automatiquement une fois que le end_
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 :
Comportement des calculs au prorata pour la mise à jour d’une planification d’abonnement : Le paramètre proration_behavior de niveau supérieur 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).
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_
, vous pouvez contrôler la manière dont les calculs au prorata sont traités à l’aide du paramètre proration_
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_
(par défaut) : Générez des réajustements au prorata pour les changements de facturation.prorations none
: Aucun calcul au prorata n’est créé pour la mise à jour.always_
: Générez des calculs au prorata et finalisez immédiatement une facture.invoice
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_
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_
sur phases[1]
détermine comment ces calculs au prorata sont gérés lors du passage de phases[0]
à phases[1]
:
create_
(par défaut) : Générez des postes de facture en attente pour les modifications de facturation.prorations none
: Aucun calcul au prorata n’est créé au début de cette phase.always_
: Générez des calculs au prorata et créez immédiatement une facture lorsque vous entrez dans cette phase.invoice
Si vous devez modifier le traitement au prorata d’une transition de phase future, mettez à jour le paramètre proration_
de la phase future avant qu’elle ne devienne active.
Utiliser des périodes d’essai
Vous pouvez ajouter une période d’essai à la première phase d’un abonnement en utilisant l’API ou le tableau de bord.
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 :
Attribut de planification présent | Attribut de phase présent | Résultat |
---|---|---|
Non | Non | Utilisation des paramètres par défaut du client ou du compte |
Oui | Non | Utilisation de l’attribut de planification défini |
Oui | Oui | Utilisation de l’attribut de phase défini |
Non | Oui | Utilisation de l’attribut de phase défini |
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.
Apprenez comment copier des métadonnées d’abonnement sur des factures d’abonnement.
Créer des planifications d’abonnement
Cet exemple illustre comment créer une planification d’abonnement à l’aide d’un client. Lorsque vous créez une planification de cette manière, l’abonnement est automatiquement créé du même coup.
Remarque
Contrairement aux créations directes d’abonnements, la première facture d’une planification d’abonnement, dont le paramètre collection_
est défini sur charge_
, se comporte de la même manière qu’une facture récurrente et n’est pas immédiatement finalisée au moment de la création de l’abonnement planifié. La facture est d’abord à l’état draft
, puis est finalisée par Stripe environ une heure après sa création.
Par exemple, lorsque vous créez une planification d’abonnement dont la méthode d’encaissement est définie sur la facturation automatique et avec start_
, un abonnement et une facture à l’état draft
sont également créés. Vous disposez d’une heure pour modifier la facture. Par la suite, la facture passe automatiquement à l’état open
ou paid
, en fonction du résultat de la tentative de paiement asynchrone au moment de la finalisation.
Modifier les planifications d’abonnement
Vous ne pouvez mettre à jour que la phase actuelle et les phases futures des planifications d’abonnement.
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.
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.
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 suivent également les mêmes restrictions que les abonnements lors de la création de phases de planification d’abonnement avec plusieurs éléments.
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 :
- La phase qui vient de s’achever et qui comportait deux éléments d’abonnement
- 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_
:
Attribut d’abonnement | Copié dans la nouvelle phase de planification d’abonnement | Copié dans les paramètres default_ de la planification d’abonnement |
---|---|---|
coupon | ||
trial_ | ||
tax_ | ||
application_ | ||
discounts | ||
collection_ | ||
invoice_ | ||
default_ | ||
default_ | ||
transfer_ | ||
on_ | ||
currency | ||
add_ | ||
automatic_ | ||
items. | ||
billing_ |
Les mises à jour des metadata
d’un abonnement ne sont pas propagées vers une planification d’abonnement associée.
Cas d’utilisation
Pour comprendre comment fonctionnent les planifications d’abonnement, prenons l’exemple d’un acteur fictif de la presse nommé The Pacific, qui propose deux options d’abonnement :
- L’option Print, qui abonne le client à la version papier du journal
- l’option Numérique, qui donne accès au contenu exclusif du site web de The Pacific
Les deux types d’abonnement déclenchent une facturation mensuelle. Découvrez ci-après les possibilités de planification qui s’offrent au journal.
Démarrer un abonnement à une date future
Par défaut, les nouveaux abonnements à la version papier commencent le premier jour du mois suivant. Pour ce faire, réglez la start_
sur une date future. Le code ci-dessous crée un abonnement qui débute dans le futur :
Antidater un abonnement
Lorsque les clients s’abonnent à la version numérique, leur abonnement est antidaté par The Pacific au premier jour du mois en cours. L’antidatage vous permet de facturer au prorata le temps passé et permet aux abonnés numériques d’accéder directement au site web.
Ajouter une planification à un abonnement existant
The Pacific peut réaliser que certains de ses clients d’origine sont abonnés sans planification. Puisque ces abonnements existent déjà, vous pouvez transmettre les ID d’abonnement dans l’attribut from_
pour leur ajouter une planification. La transmission des ID d’abonnement de cette façon crée une planification qui comporte une phase unique basée sur la période de facturation actuelle de l’abonnement.
Lors de l’ajout de ces planifications, certains clients décident de s’abonner à la version imprimée. The Pacific ajoute alors une seconde phase à la planification pour faire débuter cet abonnement papier un mois plus tard. Voici un exemple illustrant le processus dans le cas d’usage Passer à une offre supérieure.
Passer à une offre supérieure
The Pacific offre la possibilité de débuter avec un abonnement papier pendant un mois, puis d’y ajouter ensuite automatiquement l’option numérique. Certains clients préfèrent cette approche, car elle leur permet dans un premier temps de tester la publication imprimée, avant de décider s’ils veulent poursuivre ou annuler leur abonnement.
Passer à une offre inférieure
The Pacific propose par ailleurs une option qui permet de profiter initialement des deux types de publication, imprimée et numérique, avant de rebasculer automatiquement sur un abonnement papier uniquement pour le reste de l’abonnement. Les clients utilisent cette option pour tester les deux possibilités et identifier ce qui leur convient le mieux.
Modifier les abonnements
The Pacific propose deux options d’abonnement papier : une option de base avec publicités ou une option premium sans publicités. Certains clients de l’option premium souhaitent passer à l’option de base lors de la prochaine période de facturation. Vous pouvez créer une planification à l’aide de l’abonnement existant, puis mettre à jour la planification avec l’option de base avec publicités comme nouvelle phase.
Augmenter la quantité
Il est également possible de planifier des augmentations de quantité sur un abonnement. L’abonnement ci-dessous débute avec une instance de la publication numérique sur un mois. Au cours de la seconde phase, la quantité est portée à 2 pendant 11 mois supplémentaires.
Utiliser des bons de réduction
Parfois, The Pacific propose des offres spéciales d’abonnement. La planification ci-dessous propose au client une réduction de 50 % sur les publications papier pendant six mois. La planification retire ensuite le bon de réduction de l’abonnement dans la deuxième phase pour les six mois restants.
Modifier les taux de taxe
The Pacific est présent dans plusieurs juridictions, et certaines d’entre elles appliquent des taux de taxe particuliers pour les entreprises qui proposent des abonnements. Une de ces juridictions prévoit deux taux de taxe : un pour le premier mois lorsque le client s’abonne initialement et un autre pour les facturations récurrentes.
Séparer un abonnement d’une planification
Vous pouvez séparer un abonnement d’une planification dont l’état est not_
ou active
. Lorsque vous séparez un abonnement, il reste en place, mais la planification et toutes les phases restantes sont supprimées.
Annuler une planification et un abonnement
Si une planification d’abonnement comporte un abonnement actif, vous pouvez l’annuler immédiatement, ainsi que l’abonnement associé. Vous pouvez uniquement annuler une planification d’abonnement si son état est not_
ou active
.
Réinitialiser la date de début du cycle de facturation
The Pacific facture les clients de longue date de ses publications papier le jour du mois où ils se sont initialement abonnés. Cette date correspond à la date de début du cycle de facturation du client.
Si ces clients font le choix de passer à l’édition numérique, The Pacific planifie leur date de transition au premier jour du mois suivant, et réinitialise également la date de début du cycle de facturation à la même date.
Vous pouvez vérifier que la date de début du cycle de facturation est bien réinitialisée en créant un abonnement à l’aide de l’exemple de code ci-dessous. Examinez l’abonnement dans le Dashboard et notez que la facture à venir est planifiée pour facturer le client dès que l’abonnement numérique prend effet, le 1er du mois.
Pour voir ce qu’il se passera si vous ne réinitialisez pas la date de début, exécutez à nouveau l’exemple de code, mais supprimez cette fois-ci la ligne qui définit la date de début du cycle de facturation sur phase_
. Sans cette ligne, la fonction Facture à venir du Dashboard attendra un mois complet, à compter de la date du jour, avant de facturer le client et ce, malgré la transition en date du 1er.
Plans de versements échelonnés
Les plans de paiement échelonné permettent aux clients d’effectuer des paiements partiels sur une période déterminée jusqu’à ce que le montant total ait été acquitté. Par exemple, lorsque The Pacific achète de nouvelles presses, elle vend ses anciennes presses à d’autres journaux. Les petits journaux ne disposant généralement pas des fonds suffisants pour régler en une seule fois, un plan de paiement échelonné leur est proposé.
Pour la plupart des presses, The Pacific facture 1 000 € par mois. Un tarif réutilisable est par conséquent créé :
Selon la marque, le modèle et l’âge de la presse, The Pacific facture des montants différents. Dans cet exemple, 1 000 USD sont facturés mensuellement pendant six mois, pour un montant total est de 6 000 USD.
Le nombre d’iterations
est multiplié par la période du tarif, qui est égale à 6 paiements mensuels dans cet exemple, pour déterminer le nombre de facturations. Le end_
détermine ce qu’il advient de l’abonnement au terme de la dernière itération. Dans un plan de paiement échelonné, l’abonnement n’est alors plus pertinent, et le end_
est donc défini sur cancel
.
Dans des cas plus rares, The Pacific facture moins que les 1 000 USD habituels par mois. Dans ce cas-là, le service comptable utilise price_
pour créer un tarif à usage unique. Cet exemple crée un tarif de 500 USD avec facturation mensuelle pendant six mois :