# API et utilisation avancée Découvrez des stratégies avancées d'utilisation des horloges de simulation dans le Dashboard et l'API. Vous pouvez exécuter une simulation indépendamment d’un abonnement pour effectuer des simulations avancées. Dans ce scénario, vous créez d’abord la simulation, puis vous y ajoutez différents cas de test. Vous n’êtes pas prêt(e) à tester une intégration complète ? Consultez [notre guide](https://docs.stripe.com/billing/testing/test-clocks/simulate-subscriptions.md) pour effectuer des simulations sur des abonnements. Suivez ces étapes pour commencer à utiliser des horloges de simulation : 1. [Créer une simulation](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#create-clock) 1. [Configurer votre simulation](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#setup-simulation) 1. [Avancer la date et l’heure](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#advance-clock) 1. [Observez et traitez les modifications](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#monitor-changes) 1. [Modifiez la simulation](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#update-simulation) 1. [Supprimer la simulation](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#delete-clock) Vous pouvez avancer la date et l’heure, observer les changements et mettre à jour la simulation autant que nécessaire pour tester différents cas. ## Créer une simulation et définir sa date et son heure Une simulation repose sur une horloge comme objet, vous permettant de vous référer à l’heure de cette horloge de simulation. Pour lancer une simulation, créez une horloge et définissez la date figée, qui sert de point de départ à vos tests. La date figée peut être positionnée dans le passé ou dans le futur, mais une fois configurée, elle ne peut évoluer que vers l’avant. #### Dashboard [Créez un environnement de test](https://docs.stripe.com/sandboxes/dashboard/manage.md) pour commencer la simulation. 1. Dans l’onglet **Facturation**, accédez à la [section](https://dashboard.stripe.com/test/subscriptions) **Abonnements**. 1. Cliquez sur le lien [Simulations](https://dashboard.stripe.com/test/test-clocks) dans la bannière. 1. Cliquez sur **Nouvelle simulation**. 1. Dans la fenêtre modale **Créer une simulation**, donnez un nom à votre simulation. Il peut s’agir d’un nom résumant l’objectif de la simulation, par exemple `Annual renewal` (renouvellement annuel) ou `Free trial` (essai gratuit). 1. Définissez la date figée pour la simulation. #### API Avec l’API, définissez l’heure au format Epoch Unix dans le champ [frozen_time](https://docs.stripe.com/api/test_clocks/object.md#test_clock_object-frozen_time). Dans cet exemple, le point de départ de l’horloge `Annual renewal` est défini au 1er novembre 2021 à 7:00:00 GMT (`1635750000` au format Unix). ```curl curl https://api.stripe.com/v1/test_helpers/test_clocks \ -u "<>:" \ -d frozen_time=1635750000 \ -d "name=Annual renewal" ``` Notez l’`id` de l’horloge de simulation créée (par exemple, `clock_1JGWQvIyEfDZOm8cxyhPwsoc`). Il vous servira au moment de créer un client et de faire avancer l’horloge. ## Configurer votre simulation Ensuite, configurez le cas de test à simuler. Vous devez d’abord créer un client, puis son abonnement. #### Dashboard Afin de créer un client pour votre simulation via le Dashboard : 1. Accédez à la page [Simulations](https://dashboard.stripe.com/test/test-clocks) et recherchez votre simulation. 1. Cliquez sur **Ajouter** > **Ajouter un client**. Vous ne pouvez pas sélectionner des clients existants pendant les simulations. Vous pouvez ajouter jusqu’à trois nouveaux clients à chaque simulation. Vous pouvez éventuellement renseigner d’autres propriétés disponibles pour le client, comme son nom, son e-mail et ses informations de facturation, mais aucune n’est obligatoire. Pour certaines simulations, comme le test des périodes d’essai gratuites, vous pouvez choisir de ne pas collecter d’informations de facturation au préalable. Vous pouvez ensuite créer jusqu’à trois abonnements ou planifications d’abonnement pour votre client. Pour créer un abonnement au nom de votre client via le Dashboard : 1. Accédez à la page [Simulations](https://dashboard.stripe.com/test/test-clocks) et recherchez la simulation. 1. Cliquez sur **Ajouter** > **Ajouter un abonnement**. Sélectionnez votre client ou recherchez-le à l’aide du menu déroulant. Vous pouvez également ajouter le client à un abonnement via la page du client, en cliquant sur **Actions** > **Créer un abonnement**. 1. Sélectionnez un produit et un tarif récurrents dans la section **Tarifs**. 1. Pour la **Planification d’abonnement**, définissez la date de début et de fin de l’abonnement et le moment où la période de facturation doit commencer. 1. Choisissez une méthode d’encaissement : - Sélectionnez **Débiter automatiquement un moyen de paiement enregistré** si vous souhaitez débiter votre client au début de la période de facturation. - Sélectionnez **Envoyer la facture au client par e-mail pour paiement manuel** si vous souhaitez facturer votre client à terme échu. 1. Cliquez sur **Démarrer l’abonnement test** pour démarrer l’abonnement et la période de facturation. #### API > #### Utiliser l’API Accounts v2 pour représenter les clients > > L’API Accounts v2 est disponible en version générale pour les utilisateurs Connect, et en version bêta publique pour les autres utilisateurs Stripe. Tous les utilisateurs Stripe peuvent activer Accounts v2 [dans leur Dashboard](https://dashboard.stripe.com/settings/connect/platform-setup). Cependant, lorsqu’ils effectuent des appels à l’API Accounts v2, les utilisateurs de la version bêta doivent [indiquer une version bêta](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning). > > Dans la plupart des cas d’usage, nous vous recommandons de [modéliser vos clients en tant qu’objets Account configurés par le client](https://docs.stripe.com/connect/use-accounts-as-customers.md), plutôt que d’utiliser des objets [Customer](https://docs.stripe.com/api/customers.md). Utilisez l’exemple de code suivant pour créer un client et l’associer à l’horloge de simulation. Pensez à définir un moyen de paiement par défaut pour le client (sauf si vous souhaitez tester un essai gratuit ou une simulation similaire). Vous pouvez utiliser une [carte bancaire de test](https://docs.stripe.com/testing.md#cards) pour cela. #### Accounts v2 Pour créer un objet `Account` configuré par le client avec un moyen de paiement par défaut, vous devez d’abord créer l’objet `Account`, puis associer le moyen de paiement à l’objet `Account`. Vous ne pouvez pas définir de moyen de paiement par défaut lors de la création d’un objet `Account`. Pour utiliser un `Account` v2 avec une horloge de simulation, vous devez définir l’ID de l’horloge de test lorsque vous ajoutez pour la première fois la configuration `customer` au `Account`. Vous pouvez ajouter cette configuration lors de la création ou de la mise à jour du `Account`, mais vous ne pouvez pas l’ajouter ni définir l’ID de l’horloge de test ultérieurement. Pour générer un objet `PaymentMethod` et l’associer à l’objet `Account`, utilisez les informations du moyen de paiement pour créer un [SetupIntent](https://docs.stripe.com/api/setup_intents/create.md) ou un [PaymentIntent](https://docs.stripe.com/api/payment_intents/create.md) et fournissez l’ID du `Account` dans le paramètre `customer_account` : ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d confirm=true \ -d customer_account=acct_1234 \ -d "mandate_data[customer_acceptance][accepted_at]=1678942624" \ -d "mandate_data[customer_acceptance][type]=offline" \ -d "payment_method_data[billing_details][address][line1]=234 Oak Street" \ -d "payment_method_data[billing_details][address][postal_code]=12345" \ --data-urlencode "payment_method_data[billing_details][email]=jenny.rosen@example.com" \ -d "payment_method_data[billing_details][name]=Jenny Rosen" \ -d "payment_method_data[type]=us_bank_account" \ -d "payment_method_data[us_bank_account][account_holder_type]=individual" \ --data-urlencode "payment_method_data[us_bank_account][account_number]=********6789" \ -d "payment_method_data[us_bank_account][routing_number]=110000000" \ -d "payment_method_options[us_bank_account][verification_method]=automatic" \ -d "payment_method_types[]=us_bank_account" \ --data-urlencode "return_url=https://www.stripe.com" ``` Le `SetupIntent` ou `PaymentIntent` renvoyé contient l’ID de l’objet `PaymentMethod` généré dans la propriété [payment_method](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-payment_method). Ensuite, mettez à jour l’objet `Account` configuré par le client et fournissez l’ID du `PaymentMethod` dans le paramètre [default_payment_method](https://docs.stripe.com/api/v2/core/accounts/update.md#v2_update_accounts-configuration-customer-billing-default_payment_method) : ```curl curl -X POST https://api.stripe.com/v2/core/accounts/acct_1234 \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "configuration": { "customer": { "billing": { "default_payment_method": "pm_1234" } } }, "include": [ "configuration.customer" ] }' ``` #### Customers v1 [Créer un objet Customer](https://docs.stripe.com/api/customers/create.md), définissez le paramètre `test_clock` avec l’ID de l’horloge de simulation, et définissez les paramètres `payment_method` et `invoice_settings.default_payment_method` avec l’ID du `PaymentMethod` : ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ --data-urlencode "email=jenny.rosen@example.com" \ -d test_clock={{CLOCK_ID}} \ -d payment_method=pm_1234 \ -d "invoice_settings[default_payment_method]=pm_1234" ``` L’endpoint [Lister tous les clients](https://docs.stripe.com/api/customers/list.md) ne renvoie pas les clients associés aux horloges de simulation, sauf si vous spécifiez un ID d’horloge de simulation dans le paramètre [test_clock](https://docs.stripe.com/api/customers/list.md#list_customers-test_clock). Utilisez le client que vous avez créé pour [créer un objet Subscription](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md). L’abonnement sera associé à l’horloge via le client, il n’est donc pas nécessaire de transmettre l’ID de l’horloge à la création de l’abonnement. #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{RECURRING_PRICE_ID}}" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{RECURRING_PRICE_ID}}" ``` Le client et l’abonnement sont associés à la simulation que vous avez créée à la [première étape](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#create-clock). ## Avancer la date et l'heure de la simulation Après avoir créé une simulation et configuré votre cas de test, avancez le temps simulé. La première fois, le temps avance à partir de la date initiale figée définie au départ. L’avancement du temps permet d’observer le fonctionnement de votre intégration lorsque des abonnements se terminent, se renouvellent ou changent d’état, par exemple lors du passage d’une période d’essai gratuite à un abonnement payant. Configurez l’avancement du temps par intervalles de deux unités au maximum. La longueur de l’intervalle dépend de la période de service la plus courte associée à l’abonnement, définie par le tarif récurrent. Par exemple, pour un abonnement mensuel, l’avancement peut être effectué sur deux mois au maximum à chaque fois. Si vous n’avez pas configuré d’abonnements ou de planifications d’abonnement, vous pouvez avancer le temps jusqu’à deux ans à partir de la date initiale figée. #### Dashboard Pour avancer la date et l’heure via le Dashboard : 1. Accédez à la page [Simulations](https://dashboard.stripe.com/test/test-clocks) et recherchez votre simulation. 1. Cliquez sur **Avancer la date et l’heure**. 1. Utilisez la fenêtre modale du calendrier pour sélectionner la date à laquelle avancer l’horloge. 1. Cliquez sur **Avancer**. #### API Pour avancer l’horloge via l’API, changez le paramètre `frozen_time`. Par exemple, avancez-l’horloge au 1er novembre 2022 pour tester un renouvellement annuel : ```curl curl https://api.stripe.com/v1/test_helpers/test_clocks/{{CLOCK_ID}}/advance \ -u "<>:" \ -d frozen_time=1667286000 ``` ## Surveiller et gérer les modifications Après une requête API ou une opération effectuée dans le Dashboard, l’avancement jusqu’à l’heure définie peut prendre quelques secondes. Pour détecter le changement d’état de la simulation, vous pouvez écouter les notifications d’événements via des webhooks ou interroger l’objet horloge de simulation. Le Dashboard reflète également les changements. Par exemple, vous pouvez consulter la [page Factures](https://dashboard.stripe.com/test/invoices) pour vérifier si une facture a été créée ou réglée pour votre abonnement. Si vous utilisez des [webhooks](https://docs.stripe.com/webhooks.md), écoutez les notifications d’événements suivantes. Avant de passer au mode production, pensez à vérifier que votre intégration est capable de gérer les [notifications d’événements de facturation](https://docs.stripe.com/billing/subscriptions/webhooks.md) autres que celles listées ci-dessous. | Événement | Description | | ----------------------------------- | ---------------------------------------------------------------------------------- | | `test_helpers.test_clock.advancing` | L’horloge a commencé à avancer mais n’a pas atteint la date et l’heure spécifiées. | | `test_helpers.test_clock.ready` | L’horloge a atteint à la date et à l’heure spécifiées. | Pour interroger l’état de horloge de simulation, [récupérez](https://docs.stripe.com/api/test_clocks/retrieve.md)-la par ID afin d’examiner son `status`. ```curl curl https://api.stripe.com/v1/test_helpers/test_clocks/{{CLOCK_ID}} \ -u "<>:" ``` ## Modifier la simulation Vous pouvez continuer à apporter des changements à votre simulation et à [avancer l’horloge](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#advance-clock) pour différentes simulations, par exemple pour : - Ajout d’un [solde client](https://docs.stripe.com/billing/customer/balance.md). - Changer d’abonnement en milieu de cycle. - [Ajout de postes de facture ponctuels](https://docs.stripe.com/billing/invoices/subscription.md#adding-upcoming-invoice-items). Après chaque modifications, [observez à nouveau les changements](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#monitor-changes) survenus. Réitérez l’opération autant de fois que votre cas de test l’exige. ## Supprimer une simulation Les simulations sont automatiquement supprimées 30 jours après leur création. Vous pouvez également les supprimer lorsque vos tests sont terminés pour garder un environnement de test propre. #### Dashboard Pour supprimer une simulation ainsi que l’ensemble de ses objets de test associés via le Dashboard : 1. Accédez à la page [simulations](https://dashboard.stripe.com/test/test-clocks) et recherchez votre simulation. 1. Cliquez sur **Terminer la simulation**. 1. Dans la fenêtre modale de confirmation, cliquez sur **Terminer**. #### API Pour supprimer l’horloge et tous ses objets de test associés via l’API : ```curl curl -X DELETE https://api.stripe.com/v1/test_helpers/test_clocks/{{CLOCK_ID}} \ -u "<>:" ``` La suppression de la simulation supprime aussi les clients de test associés à l’horloge de simulation et annule leurs abonnements. Les simulations sont uniquement disponibles dans l’environnement de test, vous ne pouvez pas supprimer d’objets en production lorsque vous supprimez une horloge de simulation. ## Cas d’usage Dans chaque cas, commencez par créer une nouvelle simulation : 1. [Créer une simulation](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#create-clock) 1. [Configurer votre simulation](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#setup-simulation) 1. [Avancer la date et l’heure](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#advance-clock) 1. [Observez et traitez les modifications](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#monitor-changes) 1. [Modifiez la simulation](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#update-simulation) ### Tester les renouvellements d’abonnements Imaginons que vous souhaitiez vérifier le renouvellement correct d’un abonnement à 50 USD par mois : - Créez une nouvelle simulation et définissez son paramètre `frozen_time` sur le 1er janvier. - Ajoutez un client et associez-y un moyen de paiement : #### Dashboard Pour associer un moyen de paiement à un client dans le Dashboard : 1. Depuis la page de compte du client, cliquez sur **Ajouter > Ajouter une carte ** dans la section **Moyens de paiement**. 1. Saisissez les informations de paiement. Dans ce cas, utilisez la [carte de test](https://docs.stripe.com/testing.md#cards) 4242424242424242. 1. Dans la boîte de dialogue, cliquez sur **Ajouter une carte**. #### API #### Accounts v2 Pour créer un objet `Account` configuré par le client avec un moyen de paiement par défaut, vous devez d’abord créer l’objet `Account`, puis associer le moyen de paiement à l’objet `Account`. Vous ne pouvez pas définir de moyen de paiement par défaut lors de la création d’un objet `Account`. Pour utiliser un `Account` v2 avec une horloge de simulation, vous devez définir l’ID de l’horloge de test lorsque vous ajoutez pour la première fois la configuration `customer` au `Account`. Vous pouvez ajouter cette configuration lors de la création ou de la mise à jour du `Account`, mais vous ne pouvez pas l’ajouter ni définir l’ID de l’horloge de test ultérieurement. Pour générer un objet `PaymentMethod` et l’associer à l’objet `Account`, utilisez les informations du moyen de paiement pour créer un [SetupIntent](https://docs.stripe.com/api/setup_intents/create.md) ou un [PaymentIntent](https://docs.stripe.com/api/payment_intents/create.md) et fournissez l’ID du `Account` dans le paramètre `customer_account` : ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d confirm=true \ -d customer_account=acct_1234 \ -d "mandate_data[customer_acceptance][accepted_at]=1678942624" \ -d "mandate_data[customer_acceptance][type]=offline" \ -d "payment_method_data[billing_details][address][line1]=234 Oak Street" \ -d "payment_method_data[billing_details][address][postal_code]=12345" \ --data-urlencode "payment_method_data[billing_details][email]=jenny.rosen@example.com" \ -d "payment_method_data[billing_details][name]=Jenny Rosen" \ -d "payment_method_data[type]=us_bank_account" \ -d "payment_method_data[us_bank_account][account_holder_type]=individual" \ --data-urlencode "payment_method_data[us_bank_account][account_number]=********6789" \ -d "payment_method_data[us_bank_account][routing_number]=110000000" \ -d "payment_method_options[us_bank_account][verification_method]=automatic" \ -d "payment_method_types[]=us_bank_account" \ --data-urlencode "return_url=https://www.stripe.com" ``` Le `SetupIntent` ou `PaymentIntent` renvoyé contient l’ID de l’objet `PaymentMethod` généré dans la propriété [payment_method](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-payment_method). Ensuite, mettez à jour l’objet `Account` configuré par le client et fournissez l’ID du `PaymentMethod` dans le paramètre [default_payment_method](https://docs.stripe.com/api/v2/core/accounts/update.md#v2_update_accounts-configuration-customer-billing-default_payment_method) : ```curl curl -X POST https://api.stripe.com/v2/core/accounts/acct_1234 \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "configuration": { "customer": { "billing": { "default_payment_method": "pm_1234" } } }, "include": [ "configuration.customer" ] }' ``` #### Customers v1 [Créer un objet Customer](https://docs.stripe.com/api/customers/create.md), définissez le paramètre `test_clock` avec l’ID de l’horloge de simulation, et définissez les paramètres `payment_method` et `invoice_settings.default_payment_method` avec l’ID du `PaymentMethod` : ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ --data-urlencode "email=jenny.rosen@example.com" \ -d test_clock={{CLOCK_ID}} \ -d payment_method=pm_1234 \ -d "invoice_settings[default_payment_method]=pm_1234" ``` L’endpoint [Lister tous les clients](https://docs.stripe.com/api/customers/list.md) ne renvoie pas les clients associés aux horloges de simulation, sauf si vous spécifiez un ID d’horloge de simulation dans le paramètre [test_clock](https://docs.stripe.com/api/customers/list.md#list_customers-test_clock). - Quand vous avez ajouté un moyen de paiement à votre client, créez-lui un abonnement de 50 USD/mois. Ce faisant, la facture de 50 USD est payée automatiquement et l’abonnement passe à l’état `active`. - Avancez la date au 1er février pour voir qu’une facture de 50 USD est créée. Par défaut, la facture à l’état de `draft` pendant [une heure](https://docs.stripe.com/billing/invoices/subscription.md#adding-draft-invoice-items). - Avancez l’horloge d’une heure pour vérifier que la facture a bien été finalisée et payée automatiquement. ### Tester un changement d’abonnement en cours de cycle avec calcul au prorata Imaginons que vous disposiez de deux produits. L’un coûte 50 USD par mois (offre de base) et l’autre 100 USD par mois (offre premium). Vous pouvez tester les proratas lorsqu’un client met à niveau son offre de base vers l’offre premium en cours de période de facturation. Pour simuler cette situation : - Créez une simulation et définissez le paramètre `frozen_time` sur le 1er janvier. - Créez un client et ajoutez son moyen de paiement. Ici, utilisez la [carte de test](https://docs.stripe.com/testing.md#cards) 4242424242424242. - Créez un abonnement à ‘basic plan’ pour 50 USD/mois. Vous pourrez alors observer qu’une facture de 50 USD/mois a été créée, finalisée et payée automatiquement. - Avancez la date de deux semaines. Ici, nous définirons la date sur le 16 janvier. - Passez à l’abonnement ‘premium plan’, de 100 USD/mois : #### Dashboard Pour passer à un abonnement supérieur via le Dashboard : 1. Depuis la page de compte du client ou la page des détails de l’abonnement, cliquez sur le menu déroulant (⋯) associé à un abonnement, puis sur **Mettre à jour l’abonnement**. 1. Effectuez les modifications souhaitées. 1. Cliquez sur **Mettre à jour l’abonnement** dans le coin supérieur droit pour appliquer les modifications. #### API Vous pouvez mettre des mises à jour en attente avec les appels de [modification d’abonnement](https://docs.stripe.com/api/subscriptions/update.md), de [création de poste d’abonnement](https://docs.stripe.com/api/subscription_items/create.md) et de [modification de poste d’abonnement](https://docs.stripe.com/api/subscription_items/update.md). Lorsque vous effectuez la mise à jour, définissez le paramétrage `payment_behavior=pending_if_incomplete`. L’exemple ci-dessous illustre l’ajout d’un nouveau tarif à un abonnement. Puisque `proration_behavior=always_invoice` est spécifié, une facture est créée et le paiement est tenté lors de la mise à jour. #### curl ```bash curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \ -u <>: \ -d "payment_behavior"="pending_if_incomplete" \ -d "proration_behavior"="always_invoice" \ -d "items[0][id]"="si_09IkI4u3ZypJUk5onGUZpe8O" \ -d "items[0][price]"="price_CBb6IXqvTLXp3f" ``` - Après le passage à un abonnement supérieur, l’événement webhook [customer.subscription.updated](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.updated) est créé. - Les postes de facture en attente sont aussi créés pour les calculs au prorata. Vous remarquerez un prorata négatif de -25 USD correspondant à la période non-consommée du ‘basic plan’, et un prorata positif de 50 USD pour la consommation du ‘premium plan’ correspondant à la moitié du mois restant. À ce stade, aucune facture n’a été générée. - Avancez la date de deux semaines. Dans ce cas, nous réglerons la date au 1er février. Vous remarquerez que l’abonnement a effectué son cycle. Une facture a été générée à l’état `draft`. Elle inclut les postes de poste de facture, y compris un prorata négatif, un prorata positif et le paiement complet pour le mois de février, qui s’élève à 125 USD. Par défaut, la facture apparaît à l’état `draft` pendant environ [une heure](https://docs.stripe.com/billing/invoices/subscription.md#adding-draft-invoice-items)). - Avancez l’horloge d’une heure afin de finaliser la facture. ### Périodes d’essai Imaginons que vous souhaitiez permettre à vos clients de tester votre produit gratuitement pendant sept jours avant le début de la facturation et que vous vouliez collecter les informations de paiement à l’avance. Pour simuler cette situation avec les horloges de simulation, suivez les étapes suivantes : - Créez une nouvelle simulation et définissez le paramètre `frozen_time` sur le 1er janvier. - Ajoutez un client et spécifiez son moyen de paiement. Dans ce cas, utilisez une 4242424242424242[carte de test](https://docs.stripe.com/testing.md#cards). - Créez un abonnement et ajoutez une période d’essai gratuit de sept jours : #### Dashboard Pour ajouter une période d’essai à un abonnement existant via le Dashboard : Recherchez l’abonnement que vous souhaitez modifier. 1. Cliquez sur **Actions**. 1. Cliquez sur **Mettre à jour l’abonnement**. 1. Cliquez sur **Ajouter une période d’essai** et saisissez sept dans le champ **Nombre de jours de l’essai gratuit**. 1. Cliquez sur **Mettre à jour l’abonnement**. #### API Vous pouvez démarrer l’abonnement d’un client avec une période d’essai gratuite en spécifiant l’argument `trial_period_days=7` lors de la création de l’abonnement : #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d trial_end=1610403705 ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d trial_end=1610403705 ``` - Après la création d’un abonnement avec une période d’essai gratuite de sept jours, l’abonnement est créé avec l’état `trialing`. Une facture de 0,00 USD est générée en raison de la période d’essai gratuite. - Avancez la date au 5 janvier pour recevoir la notification d’événement [customer.subscription.trial_will_end](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.trial_will_end). Stripe envoie la notification trois jours avant la fin de la période d’essai. Vous pouvez utiliser cet événement webhook pour informer vos clients que la période d’essai arrive bientôt à son terme. - Avancez la date au 8 janvier pour vérifier que l’abonnement est désormais à l’état `paid` et qu’une facture de 50 USD a été créée. - Avancez la date d’un cycle (par exemple, au 8 février pour un abonnement mensuel) pour constater le renouvellement. ## Limites Vous pouvez simuler jusqu’à : - Trois clients - Trois abonnements (qui peuvent être des [abonnements planifiés](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md)) par client - Dix devis non associés à des clients ### Objets de l’horloge de simulation omis dans la liste de tous les résultats Les méthodes de type liste de l’API (comme [List Invoices](https://docs.stripe.com/api/invoices/list.md)) ne renvoient pas les objets générés par des horloges de simulation, sauf si vous spécifiez une clause de requête. Les paramètres de requête requis varient selon la ressource, consultez donc l’entrée correspondante dans la documentation de l’API. Par exemple, `GET /v1/invoices` ne renvoie pas les factures générées par des horloges de simulation, mais `GET /v1/invoices` avec une clause de requête comme `customer :"cus_123"` renvoie toutes les factures de ce client, y compris celles générées par des horloges de simulation. De même, vous pouvez spécifier un identifiant d’horloge de simulation dans cet exemple pour obtenir toutes les factures liées à cette horloge, ou spécifier un identifiant d’abonnement pour obtenir toutes les factures relatives à cet abonnement, y compris les factures générées par l’horloge de simulation. ### Erreurs de limite de taux Si vous effectuez plusieurs mises à jour d’un abonnement associé à une horloge de simulation, Stripe peut renvoyer une erreur de limite de taux. Étant donné que l’abonnement est gelé à l’heure de l’horloge de simulation, toutes les requêtes API comptent pour cette heure, ce qui peut déclencher la limite de taux. Pour éviter cela, avancez l’heure simulée de l’horloge de quelques minutes avant d’effectuer des demandes d’API supplémentaires sur l’abonnement. L’API Subscriptions limite le nombre maximal de requêtes comme suit : - 10 nouvelles factures par abonnement, par minute - 20 nouvelles factures par abonnement et par jour - 200 mises à jour de quantité par abonnement et par heure ### Mises en garde concernant le traitement des paiements L’avancement de l’horloge de simulation ne prend pas encore en charge la collecte des paiements par prélèvement bancaire (comme les types de moyen de paiement `us_bank_account`). Stripe encaisse les paiements après avancement de l’horloge de simulation. Pour tester les échecs de paiement : 1. Sélectionnez le paramètre **Annuler l’abonnement après l’échec de toutes les relances de paiement**. 1. Associez un moyen de paiement de type `us_bank_account`à un client dont les paiements échouent. 1. Créez un abonnement pour le client. 1. Faites avancer l’horloge de simulation pour collecter le paiement d’un abonnement. Une fois l’horloge de test avancée, l’abonnement reste `active`. Cela indique que le prélèvement n’a pas été tenté pendant l’avancement de l’horloge de test et que l’abonnement n’est pas passé à l’état `canceled` en raison d’un `payment_failed`. Écoutez l’événement `invoice.payment_failed` pour surveiller l’état de l’abonnement en retard de paiement et le paiement de la facture. L’événement `customer.subscription.deleted` indique que l’abonnement est à l’état `canceled`.