Accéder directement au contenu
Créez un compte
 ou
connecter-vous
Logo de la documentation Stripe
/
Créez un compte
Connectez-vous
Aperçu
Billing

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. Voici une courte vidéo décrivant le fonctionnement des planifications d’abonnement dans le Dashboard :

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 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 :

Attribut de planificationAttribut de phase
default_settings.billing_thresholdsphases.billing_thresholds
default_settings.collection_methodphases.collection_method
default_settings.default_payment_methodphases.default_payment_method
default_settings.invoice_settingsphases.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ésentAttribut de phase présentRésultat
NonNonUtilisation des paramètres par défaut du client ou du compte
OuiNonUtilisation de l’attribut de planification défini
OuiOuiUtilisation de l’attribut de phase défini
NonOuiUtilisation 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.

Pour utiliser les métadonnées de phase avec l’API, définissez des métadonnées 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 :

{
  ...
  "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 1possède les métadonnées suivantes :

{
  ...
  "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 :

{
  ...
  "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.

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.

Command Line
curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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

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 :

Command Line
curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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.

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

Modifier les planifications d’abonnement

Vous ne pouvez mettre à jour que la phase actuelle et les phases futures des planifications 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 :

Command Line
curl https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}}
 \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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 :

Command Line
curl https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}}
 \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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 :

Command Line
curl https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}}
 \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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.

Command Line
curl https://api.stripe.com/v1/invoices/create_preview \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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.

Command Line
curl https://api.stripe.com/v1/invoices/create_preview \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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 :

Attribut d’abonnementCopié dans la nouvelle phase de planification d’abonnementCopié dans les paramètres default_settings de la planification d’abonnement
couponX
trial_endX
tax_ratesX
application_fee_percentXX
discountsX
collection_methodXX
invoice_settingsXX
default_payment_methodXX
default_sourceXX
transfer_dataXX
on_behalf_ofXX
billing_thresholdsXX
currencyX
add_invoice_itemsX
automatic_taxXX
items.pricesX

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

Voir aussi

Cette page vous a-t-elle été utile ?
OuiNon
Besoin d'aide ? Contactez le service d'assistance.
Rejoignez notre programme d'accès anticipé.
Consultez notre journal des modifications des produits.
Des questions ? Contactez l'équipe commerciale.
Propulsé par Markdoc
Sur cette page
Phases
Définir la durée d’une phase
Passer à la phase suivante
Utiliser des périodes d’essai
Réaliser une planification
Héritage des attributs de phase
Utiliser des métadonnées de phase
Créer des planifications d’abonnement
Modifier les planifications d’abonnement
Prévisualiser une facture
Aperçu de la création et des mises à jour de planifications
Autres considérations
Restrictions
Limites du Dashboard
Mises à jour d’un abonnement associé à une planification
Voir aussi
Produits utilisés
Billing