# Planifications d'abonnement Découvrez les planifications d'abonnements et apprenez à les utiliser. > Cette fonctionnalité est uniquement disponible dans la version classique de [l’éditeur d’abonnements](https://dashboard.stripe.com/subscriptions) dans le Dashboard. Vous pouvez passer de la version classique à la nouvelle version à tout moment, et votre choix sera conservé pendant 30 jours. Ceci signifie que lorsque vous rouvrirez l’éditeur, il reprendra par défaut la dernière version que vous aviez sélectionnée. Utilisez les [planifications d’abonnement](https://docs.stripe.com/api/subscription_schedules.md) pour automatiser les modifications apportées aux abonnements au fil du temps. Vous pouvez [créer](https://docs.stripe.com/api/subscription_schedules/create.md) 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](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-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](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-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 à la fois dans le Dashboard Stripe Billing et dans l’API. Pour découvrir comment utiliser les planifications d’abonnement, consultez la section [Cas d’usage](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md#use-cases). ## Phases Lorsque vous créez une planification d’abonnement, utilisez l’attribut [phases](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-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. #### API Les phases disposent d’un attribut [duration](https://docs.stripe.com/api/subscription_schedules/update.md#update_subscription_schedule-phases-duration) qui permet d’indiquer la durée d’une phase. Le paramètre `duration` accepte les valeurs suivantes : `week`, `month` ou `year`. la `end_date` d’une phase doit correspondre à la `start_date` de la phase suivante. l’utilisation du paramètre `duration` définit automatiquement les valeurs `start_date` et `end_date`. vous pouvez définir ces valeurs manuellement, mais Stripe recommande d’utiliser `duration`, car la définition manuelle des dates de début et de fin peut générer des erreurs. à réserver aux cas d’usage avancés. #### Dashboard Pour définir la longueur d’une phase : 1. Dans le Dashboard, ouvrez l’[éditeur d’abonnements](https://dashboard.stripe.com/subscriptions?create=subscription). 1. Ajoutez un nouveau client ou trouvez un client existant. 1. Ajoutez un nouveau produit ou recherchez un produit existant. 1. Cliquez sur **+ Ajouter une phase**. 1. Sélectionnez la durée de la phase. Vous pouvez également sélectionner **Pour toujours** pour que l’abonnement reste actif indéfiniment. ### 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](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-proration_behavior) 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](https://docs.stripe.com/api/subscription_schedules/update.md#update_subscription_schedule-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). 1. **Comportement des calculs au prorata pendant la transition de phase** : Chaque phase possède son propre attribut [proration_behavior](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-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](https://docs.stripe.com/api/subscriptions/update.md#update_subscription-proration_behavior) 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 à la première phase d’un abonnement en utilisant l’API ou le tableau de bord. #### API Vous pouvez ajouter une période d’essai sur une phase en définissant une [date de fin de la période d’essai](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-trial_end). 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. #### Dashboard Pour ajouter une période d’essai à la première phase d’un nouvel abonnement : 1. Dans le Dashboard, ouvrez la page [Éditeur d’abonnements](https://dashboard.stripe.com/subscriptions?create=subscription). 1. Ajoutez un nouveau client ou trouvez un client existant. 1. Ajoutez un nouveau produit ou recherchez un produit existant. 1. Sous **Jours d’essai gratuit**, définissez la durée de la période d’essai gratuit. - Si vous souhaitez que la phase entière soit un essai, fixez la durée de l’essai à la même valeur que la durée de la phase. - Si vous souhaitez que seule une partie de la phase soit un essai, définissez une durée d’essai inférieure à la durée de la phase. 1. Cliquez sur **Créer un abonnement**. Pour ajouter une période d’essai à la première phase d’un abonnement existant : 1. Dans le Dashboard, allez à la page [Abonnements](https://dashboard.stripe.com/subscriptions), sélectionnez un abonnement existant puis cliquez sur **Actions** > **Modifier l’abonnement**. 1. Dans l’abonnement, cliquez sur **Editer** pour la première phase. 1. Sous **Jours d’essai gratuit**, définissez la durée de la période d’essai gratuit. - Si vous souhaitez que la phase entière soit un essai, fixez la durée de l’essai à la même valeur que la durée de la phase. - Si vous souhaitez que seule une partie de la phase soit un essai, définissez une durée d’essai inférieure à la durée de la phase. 1. Cliquez sur **Mettre à jour l’abonnement**. ### 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](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-end_behavior) sur `cancel`. L’attribut [cancel_on_date](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-cancel_at) 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 : | Attribut de planification | Attribut de phase | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | [default_settings.billing_thresholds](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-default_settings-billing_thresholds) | [phases.billing_thresholds](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-billing_thresholds) | | [default_settings.collection_method](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-default_settings-collection_method) | [phases.collection_method](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-collection_method) | | [default_settings.default_payment_method](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-default_settings-default_payment_method) | [phases.default_payment_method](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-default_payment_method) | | [default_settings.invoice_settings](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-default_settings-invoice_settings) | [phases.invoice_settings](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-invoice_settings) | 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. #### API Pour utiliser les métadonnées de phase avec l’API, définissez des [métadonnées](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-metadata) pour les phases d’une planification d’abonnement. Lorsque l’abonnement sous-jacent entre dans une phase : - Si la phase contient des métadonnées, les valeurs correspondantes sont *ajoutées* aux métadonnées de l’abonnement, à condition que les clés *ne soient pas* déjà présentes dans ce dernier. - Les métadonnées de la phase ayant des valeurs non-vides sont utilisées pour *mettre à jour* les métadonnées de l’abonnement si les clés *sont* déjà présentes dans ce dernier. - Les métadonnées de la phase ayant des *valeurs vides* sont utilisées pour *désactiver* les clés correspondantes dans les métadonnées de l’abonnement. Afin de désactiver toutes les clés des métadonnées de l’abonnement, mettez l’abonnement à jour directement ou désactivez chaque clé individuellement depuis les métadonnées de la phase. La mise à jour directe des métadonnées de l’abonnement sous-jacent n’affecte pas les métadonnées de la phase en cours. L’exemple suivant illustre une planification d’abonnement à deux phases, où chacune a ses propres métadonnées : ```json { ... "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": "" } } ] } ``` Lorsque cette planification crée un nouvel abonnement et que ce dernier entre dans la `Phase 1`, les trois clés des métadonnées de la `Phase 1` sont ajoutées aux métadonnées de l’abonnement. Par conséquent, l’abonnement en `Phase 1`possède les métadonnées suivantes : ```json { ... "object": "subscription", "metadata": { "channel": "self-serve", "region": "apac", "upsell-products": "alpha" } } ``` Lorsque l’abonnement entre dans la `Phase 2`, les métadonnées de l’abonnement sont mises à jour : - La valeur de `channel` est mise à jour car une valeur est spécifiée dans les métadonnées de la phase et l’abonnement dispose déjà de métadonnées avec cette clé. - La valeur de `region` ne change pas car elle n’est pas spécifiée dans la phase. - `churn-risk` est ajouté car il s’agit d’une nouvelle clé. - `upsell-products` est désactivé car une valeur vide est spécifiée dans la phase. Par conséquent, l’abonnement en `Phase 2` possède les métadonnées suivantes : ```json { ... "object": "subscription", "metadata": { "channel": "sales", "region": "apac", "churn-risk": "high" } } ``` #### Dashboard Vous pouvez ajouter, modifier et supprimer des entrées de métadonnées pour chaque phase d’une planification d’abonnement à l’aide de l’[éditeur d’abonnements du Dashboard Billing](https://dashboard.stripe.com/subscriptions?create=subscription). Lors de l’activation d’une nouvelle phase, les métadonnées de l’objet Subscription sont mises à jour pour correspondre aux métadonnées de cette phase. 1. Dans le Dashboard, ouvrez l’[éditeur d’abonnements](https://dashboard.stripe.com/subscriptions?create=subscription). 1. Ajoutez un nouveau client ou trouvez un client existant. 1. Ajoutez un nouveau produit ou recherchez un produit existant. 1. Dans une phase nouvelle ou existante, cliquez sur **+ Ajouter des métadonnées**. 1. Saisissez une **clé** et une **valeur**, puis cliquez sur **Enregistrer**. Apprenez comment [copier des métadonnées d’abonnement sur des factures d’abonnement](https://docs.stripe.com/billing/invoices/subscription.md#subscription-metadata). ## Créer des planifications d’abonnement Si votre intégration utilise des [Accounts configurés par le client](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), remplacez les références `Customer` et événement dans les exemples de code par les références équivalentes de l’API Accounts v2. Pour plus d’informations, consultez la page [Représenter des clients avec des objets Account](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md). 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. > 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](https://docs.stripe.com/billing/subscriptions/webhooks.md#understand). > > 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_date=now`, un abonnement et une facture à l’état `draft` sont également créés. Vous disposez d’une heure pour [modifier la facture](https://docs.stripe.com/api/invoices/update.md). 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. #### API ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -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][duration][interval]=month" \ -d "phases[0][duration][interval_count]=12" ``` Cette planification : - Entre en application dès sa création. - Définit l’abonnement sur une instance du produit au `price_1GqNdGAJVYItwOKqEHb`. - Effectue 12 mois et libère ensuite l’abonnement de la planification. Vous pouvez également créer des planifications d’abonnement en transmettant un ID d’abonnement : ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d from_subscription=sub_GB98WOvaRAWPl6 ``` 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. Comme pour les autres API Stripe, vous pouvez consulter et mettre à jour vos [planifications d’abonnement](https://docs.stripe.com/api/subscription_schedules.md). Il est également possible de les annuler ou de les libérer. L’annulation d’une planification d’abonnement entraîne l’annulation de l’abonnement associé. Si vous souhaitez uniquement dissocier une planification d’un abonnement, utilisez l’appel [libérer](https://docs.stripe.com/api/subscription_schedules/release.md). #### Dashboard Pour créer des planifications d’abonnement en plusieurs phases : 1. Dans le Dashboard, ouvrez l’[éditeur d’abonnements](https://dashboard.stripe.com/subscriptions?create=subscription). 1. Ajoutez un nouveau client ou trouvez un client existant. 1. Ajoutez un nouveau produit ou recherchez un produit existant. 1. Définissez une durée pour la première phase de la planification d’abonnement. 1. Cliquez sur **+ Ajouter une phase**. 1. Sélectionnez la durée de la phase. Vous pouvez également sélectionner **Pour toujours** pour que l’abonnement reste actif indéfiniment. 1. Apportez les modifications requises à votre nouvelle phase. Vous pouvez modifier la quantité, le tarif, ajouter ou supprimer des coupons, réinitialiser la date de la période de facturation, modifier le comportement du 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 lorsque cette phase est activée. 1. Enregistrez la nouvelle phase. 1. Ajoutez toute phase supplémentaire nécessaire. 1. Cliquez sur **Planifier l’abonnement**. ## Modifier les planifications d’abonnement Vous ne pouvez mettre à jour que la phase actuelle et les phases futures des planifications d’abonnement. #### API 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 met également à jour l’abonnement sous-jacent. Par exemple, cet appel met à jour la `quantity` à 2 : ```curl curl https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}} \ -u "<>:" \ -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" ``` 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 : ```curl curl https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}} \ -u "<>:" \ -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" ``` Pour ajouter de nouvelles phases à une planification d’abonnement, transmettez la phase actuelle et définissez ensuite les nouvelles phases : ```curl curl https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}} \ -u "<>:" \ -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][duration][interval]=month" \ -d "phases[1][duration][interval_count]=1" ``` #### Dashboard Pour mettre à jour les abonnements existants afin qu’ils aient des phases d’abonnement futures : 1. Dans le Dashboard, allez à la page [Abonnements](https://dashboard.stripe.com/subscriptions), sélectionnez un abonnement existant puis cliquez sur **Actions** > **Modifier l’abonnement**. 1. Définissez une durée pour la phase actuelle de la planification d’abonnement en sélectionnant une date de fin. 1. Cliquez sur **+ Ajouter une phase**. 1. Sélectionnez la durée de la phase suivante. Vous pouvez également sélectionner **Pour toujours** pour que l’abonnement reste actif indéfiniment. 1. Apportez les modifications requises à votre nouvelle phase. Vous pouvez modifier la quantité, le tarif, ajouter ou supprimer des coupons, réinitialiser la date de la période de facturation, modifier le comportement du 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 lorsque cette phase est activée. 1. Enregistrez la nouvelle phase. 1. Ajoutez toute phase supplémentaire nécessaire. 1. Cliquez sur **Planifier l’abonnement**. ## Prévisualiser une facture Utilisez le paramètre [planification](https://docs.stripe.com/api/invoices/create_preview.md#create_create_preview-schedule) dans l’[aperçu de création](https://docs.stripe.com/api/invoices/create_preview.md) pour prévisualiser la facture suivante d’une planification d’abonnement. ```curl curl https://api.stripe.com/v1/invoices/create_preview \ -u "<>:" \ -d "schedule={{SUBSCRIPTIONSCHEDULE_ID}}" ``` ### Aperçu de la création et des mises à jour de planifications Utilisez les paramètres dans [schedule_details](https://docs.stripe.com/api/invoices/create_preview.md#create_create_preview-schedule_details) pour prévisualiser la création ou la mise à jour d’une planification d’abonnement. Transmettez une [planification](https://docs.stripe.com/api/invoices/create_preview.md#create_create_preview-schedule) existante pour indiquer à Stripe s’il s’agit d’une création ou d’une mise à jour. Transmettez toutes les [phases](https://docs.stripe.com/api/invoices/create_preview.md#create_create_preview-schedule_details-phases) actuelles et futures que vous prévisualisez. Par exemple, le code suivant affiche un aperçu de la première facture d’un calendrier d’abonnement comportant `1` phase d’une durée de `12` mois. ```curl curl https://api.stripe.com/v1/invoices/create_preview \ -u "<>:" \ -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][duration][interval]=month" \ -d "schedule_details[phases][0][duration][interval_count]=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 suivent également [les mêmes restrictions que les abonnements](https://docs.stripe.com/billing/subscriptions/quantities.md#billing-periods-with-multiple-prices) 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](https://dashboard.stripe.com/test/subscriptions). 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](https://docs.stripe.com/api/subscription_schedules.md) 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](https://docs.stripe.com/api/subscription_schedules.md) pour modifier l’abonnement, au lieu de l’API [Subscriptions](https://docs.stripe.com/api/subscriptions.md#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](https://docs.stripe.com/api/subscription_schedules/create.md) ou via le webhook [subscription_schedule.created](https://docs.stripe.com/api/events/types.md#event_types-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](https://docs.stripe.com/customer-management/configure-portal.md#configure-subscription-management). - 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](https://docs.stripe.com/api/subscription_schedules/release.md) ou via l’événement de webhook [subscription_schedule.released](https://docs.stripe.com/api/events/types.md#event_types-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](https://docs.stripe.com/api/subscription_items/delete.md) 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 1. 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`](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-default_settings) : | Attribut d’abonnement | Copié dans la nouvelle phase de planification d’abonnement | Copié dans les paramètres `default_settings` de la planification d’abonnement | | ------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------- | | `coupon` | ✓ Supported | - Unsupported | | `trial_end` | ✓ Supported | - Unsupported | | `tax_rates` | ✓ Supported | - Unsupported | | `application_fee_percent` | ✓ Supported | ✓ Supported | | `discounts` | ✓ Supported | - Unsupported | | `collection_method` | ✓ Supported | ✓ Supported | | `invoice_settings` | ✓ Supported | ✓ Supported | | `default_payment_method` | ✓ Supported | ✓ Supported | | `default_source` | ✓ Supported | ✓ Supported | | `transfer_data` | ✓ Supported | ✓ Supported | | `on_behalf_of` | ✓ Supported | ✓ Supported | | `currency` | ✓ Supported | - Unsupported | | `add_invoice_items` | ✓ Supported | - Unsupported | | `automatic_tax` | ✓ Supported | ✓ Supported | | `items.prices` | ✓ Supported | - Unsupported | | `billing_thresholds` | ✓ Supported | ✓ Supported | 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_date` sur une date future. Le code ci-dessous crée un abonnement qui débute dans le futur : ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=1690873200 \ -d end_behavior=release \ -d "phases[0][items][0][price]={{PRICE_PRINT}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][duration][interval]=month" \ -d "phases[0][duration][interval_count]=12" ``` ### 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. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=1688194800 \ -d end_behavior=release \ -d "phases[0][items][0][price]={{PRICE_DIGITAL}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][duration][interval]=month" \ -d "phases[0][duration][interval_count]=12" ``` ### 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_subscription` 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. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "from_subscription={{SUBSCRIPTION_ID}}" ``` 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](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md#upgrading-subscriptions). ### 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. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=release \ -d "phases[0][items][0][price]={{PRICE_PRINT}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][duration][interval]=month" \ -d "phases[0][duration][interval_count]=1" \ -d "phases[1][items][0][price]={{PRICE_PRINT}}" \ -d "phases[1][items][0][quantity]=1" \ -d "phases[1][items][1][price]={{PRICE_DIGITAL}}" \ -d "phases[1][items][1][quantity]=1" \ -d "phases[1][duration][interval]=month" \ -d "phases[1][duration][interval_count]=11" ``` ### 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* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) utilisent cette option pour tester les deux possibilités et identifier ce qui leur convient le mieux. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=release \ -d "phases[0][items][0][price]={{PRICE_DIGITAL}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][items][1][price]={{PRICE_PRINT}}" \ -d "phases[0][items][1][quantity]=1" \ -d "phases[0][duration][interval]=month" \ -d "phases[0][duration][interval_count]=1" \ -d "phases[1][items][0][price]={{PRICE_PRINT}}" \ -d "phases[1][items][0][quantity]=1" \ -d "phases[1][duration][interval]=month" \ -d "phases[1][duration][interval_count]=11" ``` ### 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. #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. client = Stripe::StripeClient.new('<>') # Create a subscription schedule with the existing subscription schedule = client.v1.subscription_schedules.create({ from_subscription: 'sub_ERf72J8Sc7qx7D', }) # Update the schedule with the new phase client.v1.subscription_schedules.update( schedule.id, { phases: [ { items: [ { price: schedule.phases[0].items[0].price, quantity: schedule.phases[0].items[0].quantity, }, ], start_date: schedule.phases[0].start_date, end_date: schedule.phases[0].end_date, }, { items: [ { price: '{{PRICE_PRINT_BASIC}}', quantity: 1, }, ], duration: { interval: 'month', interval_count: 1, }, }, ], }, ) ``` ### 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. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=release \ -d "phases[0][items][0][price]={{PRICE_ID}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][duration][interval]=month" \ -d "phases[0][duration][interval_count]=1" \ -d "phases[1][items][0][price]={{PRICE_ID}}" \ -d "phases[1][items][0][quantity]=2" \ -d "phases[1][duration][interval]=month" \ -d "phases[1][duration][interval_count]=11" ``` ### 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. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=release \ -d "phases[0][items][0][price]={{PRICE_ID}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][duration][interval]=month" \ -d "phases[0][duration][interval_count]=6" \ -d "phases[0][discounts][0][coupon]={{COUPON_ID}}" \ -d "phases[1][items][0][price]={{PRICE_ID}}" \ -d "phases[1][items][0][quantity]=1" \ -d "phases[1][duration][interval]=month" \ -d "phases[1][duration][interval_count]=6" ``` ### 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. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=release \ -d "phases[0][items][0][price]={{PRICE_ID}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][items][0][tax_rates][0]=txr_2J8lmBBGHJYyuUJqF6QJtaAA" \ -d "phases[0][duration][interval]=month" \ -d "phases[0][duration][interval_count]=1" \ -d "phases[1][items][0][price]={{PRICE_ID}}" \ -d "phases[1][items][0][quantity]=1" \ -d "phases[1][items][0][tax_rates][0]=txr_2J8lmBBGHJYyuUJqF6QJtbBB" \ -d "phases[1][duration][interval]=month" \ -d "phases[1][duration][interval_count]=11" ``` ### Séparer un abonnement d’une planification Vous pouvez [séparer](https://docs.stripe.com/api/subscription_schedules/release.md) un abonnement d’une planification dont l’état est `not_started` ou `active`. Lorsque vous séparez un abonnement, il reste en place, mais la planification et toutes les phases restantes sont supprimées. ```curl curl -X POST https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}}/release \ -u "<>:" ``` ### 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_started` ou `active`. ```curl curl -X POST https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}}/cancel \ -u "<>:" ``` ### 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_start`. 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. ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=now \ -d "phases[0][items][0][price]={{PRICE_PRINT}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][end_date]=1690873200" \ -d "phases[1][items][0][price]={{PRICE_DIGITAL}}" \ -d "phases[1][items][0][quantity]=1" \ -d "phases[1][duration][interval]=month" \ -d "phases[1][duration][interval_count]=11" \ -d "phases[1][billing_cycle_anchor]=phase_start" ``` ### 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éé : ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d unit_amount=100000 \ -d currency=usd \ -d product=prod_Hh99apo1OViyGW \ -d "recurring[interval]=month" ``` 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. #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d start_date=now \ -d end_behavior=cancel \ -d "phases[0][items][0][price]={{PRICE_ID}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][iterations]=6" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=cancel \ -d "phases[0][items][0][price]={{PRICE_ID}}" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][iterations]=6" ``` 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_behavior` 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_behavior` 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_data` pour créer un tarif à usage unique. Cet exemple crée un tarif de 500 USD avec facturation mensuelle pendant six mois : #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d start_date=now \ -d end_behavior=cancel \ -d "phases[0][items][0][price_data][currency]=usd" \ -d "phases[0][items][0][price_data][product]=prod_Hh99apo1OViyGW" \ -d "phases[0][items][0][price_data][recurring][interval]=month" \ -d "phases[0][items][0][price_data][unit_amount]=50000" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][iterations]=6" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=cancel \ -d "phases[0][items][0][price_data][currency]=usd" \ -d "phases[0][items][0][price_data][product]=prod_Hh99apo1OViyGW" \ -d "phases[0][items][0][price_data][recurring][interval]=month" \ -d "phases[0][items][0][price_data][unit_amount]=50000" \ -d "phases[0][items][0][quantity]=1" \ -d "phases[0][iterations]=6" ```