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 :
Planifications d’abonnement dans le Dashboard
Cette page se penche en détail sur le fonctionnement des planifications d’abonnement. Pour obtenir des exemples d’utilisation, reportez-vous à 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.
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 changements de phases interviennent automatiquement, une fois que l’end_date
d’une phase est atteinte. Lorsque qu’une phase arrive à son terme, Stripe modifie l’abonnement en fonction des attributs de la phase suivante. Vous pouvez au besoin activer le calcul au prorata pour créditer l’utilisateur pour les postes ou le temps non utilisés de son plan.
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 expirent lorsque que leur dernière phase s’achève. À ce stade, l’abonnement reste en place même s’il n’est plus associé à la planification. Si vous souhaitez que l’abonnement soit annulé à l’achèvement de la dernière phase de planification, vous pouvez définir end_behavior sur cancel
.
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.
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.
Note
Contrairement aux créations directes d’abonnements, la première facture d’une planification d’abonnement, dont le paramètre collection_method
est défini sur charge_automatically
, 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 à facturation automatique avec le paramètre start_date=now
, cela génère également un abonnement et une facture à l’état draft
. Vous disposez ainsi d’une heure pour apporter des modifications à la facture. La facture bascule ensuite automatiquement sur l’étatopen
ou paid
, en fonction du résultat de la tentative de paiement asynchrone au moment de la finalisation.
Cette planification :
- Entre en application dès sa création.
- Définit l’abonnement sur une instance du produit au
price_1GqNdGAJVYItwOKqEHb
. - Effectue 12 itérations et libère ensuite l’abonnement de la planification.
Vous pouvez également créer des planifications d’abonnement en transmettant un ID d’abonnement :
Lorsque vous créez une planification de cette façon, les attributs de l’abonnement sont utilisés pour définir les attributs de la planification.
De la même façon qu’avec les autres API Stripe, vous pouvez récupérer et mettre à jour vos planifications d’abonnement. Vous pouvez également les annuler et de les libérer. L’annulation d’une planification d’abonnement entraîne également l’annulation de l’abonnement. Si vous souhaitez simplement supprimer la planification définie pour un abonnement, utilisez l’appel release.
Créer des planifications d’abonnement sans code
Vous pouvez créer des planifications d’abonnement en plusieurs phases sans utiliser de code dans l’éditeur d’abonnements de Stripe Billing. Pour ce faire, suivez les instructions suivantes :
- Dans le Dashboard, ouvrez l’éditeur d’abonnements.
- Ajoutez un client.
- Ajoutez un prix dans la liste déroulante de sélection du produit.
- Définissez une durée pour la première phase de la planification d’abonnement.
- Cliquez sur + Ajouter une phase.
- Sélectionnez la durée de votre prochaine phase, ou sélectionnez indéfiniment pour que l’abonnement se poursuive.
- Faites les modifications nécessaires pour votre nouvelle phase. Vous pouvez changer la quantité, modifier le prix, ajouter ou retirer des bons de réduction, réinitialiser la date du cycle de facturation, changer le comportement des calculs au prorata ou mettre à jour les métadonnées. Si vous modifiez les métadonnées dans une phase, les métadonnées de l’abonnement sont mises à jour lors de l’activation de cette phase.
- Enregistrez la nouvelle phase.
- Ajoutez toute phase supplémentaire nécessaire.
- Créez un abonnement.
Modifier les planifications d’abonnement
Vous ne pouvez mettre à jour que la phase actuelle et les phases futures d’une planification d’abonnement. Vous devez transmettre toutes les phases actuelles et futures lorsque vous mettez à jour une planification d’abonnement. Vous devez également transmettre les paramètres précédemment définis que vous souhaitez conserver. Tous les paramètres précédemment définis ne sont plus définis pour la phase existante, sauf si vous les transmettez dans la demande de mise à jour. Vous continuez de recevoir des informations dans la réponse sur les phases passées.
Vous pouvez inclure jusqu’à 10 phases actuelles ou futures. La mise à jour de la phase active entraîne également l’actualisation de l’abonnement sous-jacent. Par exemple, cet appel conserve les dates de début et de fin, mais redéfinit la quantity
sur deux :
Vous pouvez également mettre immédiatement fin à la phase actuelle et en initier une nouvelle. La phase active devient alors une phase du passé et la nouvelle phase est immédiatement appliquée à l’abonnement. Dans l’exemple ci-dessous, la phase actuelle est terminée et une nouvelle est initiée :
Pour ajouter de nouvelles phases à une planification d’abonnement, transmettez la phase actuelle et définissez ensuite les nouvelles phases :
Modifier des planifications d’abonnement sans code
Grâce à l’éditeur d’abonnements de Stripe Billing, vous pouvez modifier les abonnements existants pour ajouter des phases de planification d’abonnement futures. Pour ce faire, suivez les instructions suivantes :
- Dans le Dashboard, allez à la page Abonnements, sélectionnez un abonnement existant puis cliquez sur Actions > Modifier l’abonnement.
- Définissez une durée pour la phase actuelle de la planification d’abonnement en sélectionnant une date de fin.
- Cliquez sur + Ajouter une phase.
- Sélectionnez la durée de votre prochaine phase, ou sélectionnez simplement indéfiniment pour que l’abonnement se poursuive.
- Faites les modifications nécessaires pour votre nouvelle phase. Vous pouvez changer la quantité, modifier le prix, ajouter ou retirer des bons de réduction, réinitialiser la date du cycle de facturation, changer le comportement des calculs au prorata ou mettre à jour les métadonnées. Si vous modifiez les métadonnées dans une phase, les métadonnées de l’abonnement sont mises à jour lors de l’activation de cette phase.
- Enregistrez la nouvelle phase.
- Ajoutez toute phase supplémentaire nécessaire.
- Créez un abonnement.
Prévisualiser une facture
Utilisez le paramètre schedule de l’API Upcoming Invoice 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 de 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.
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