# Mettre en place une facturation avancée à usage avec des offres tarifaires Facturez vos clients en fonction de leur utilisation et des frais récurrents. Vous pouvez regrouper différents composants tarifaires dans une même offre tarifaire afin de mettre en œuvre des modèles de tarification complexes combinant plusieurs stratégies de facturation. Par exemple, créez une offre tarifaire qui inclut , des grilles tarifaires pour la facturation à l’usage, des frais de licence pour les frais récurrents et des actions de service pour les allocations récurrentes de crédits. Lorsqu’un client s’abonne, Stripe active automatiquement tous les composants récurrents et les facture selon la cadence que vous avez configurée. Les modèles de tarification pris en charge sont les suivants : - Paiement à l’utilisation - Consommation de crédit en temps réel avec recharges - Frais de dépassement et frais forfaitaires > Les offres tarifaires sont actuellement en [version bêta privée](https://docs.stripe.com/release-phases.md) et leur fonctionnement ainsi que leur mode d’intégration peuvent évoluer avant leur mise à disposition générale pour tous les utilisateurs de Stripe. Contactez-nous pour demander l’accès. ## Before you begin - Les offres tarifaires utilisent des endpoints de l’API `/v2`. En savoir plus sur les espaces de noms [/v2 et /v1](https://docs.stripe.com/api-v2-overview.md). - Utilisez [des bacs à](https://docs.stripe.com/sandboxes.md) sable pour tester l’intégration de vos offres tarifaires. Vous ne pouvez pas utiliser le mode test avec les API `/v2`. Vous pouvez également utiliser une [version guidée de l’API (Blueprint)](https://dashboard.stripe.com/test/workbench/blueprints/usage-based-billing?code-pane-shown=true) dans le Dashboard. ## Créer un plan tarifaire Utilisez le Dashboard ou l’API Stripe pour créer une offre tarifaire qui contient toutes les composantes pertinentes de votre modèle de tarification. Pour chaque offre tarifaire, configurez : - **Devise** : indiquez la devise de tous les composants de votre offre tarifaire. - **Inclure les taxes dans le tarif** : Indiquez si vous souhaitez inclure les taxes dans votre tarif (taxes comprises) ou les ajouter au sous-total de la facture (hors taxes). En savoir plus sur les régimes [taxes comprises et hors taxes pour la facturation](https://docs.stripe.com/billing/taxes/tax-rates.md#inclusive-vs-exclusive-tax). - **Métadonnées** : ajoutez éventuellement vos propres métadonnées à l’offre tarifaire. Après avoir défini les paramètres de devise et de taxe, configurez les composants pertinents de votre offre. Les composants à inclure dépendent de votre modèle de tarification. Ce guide présente les trois composants (grilles tarifaires, frais de licence et actions de service). Par exemple, un modèle de paiement à l’usage et une consommation de crédits en temps réel avec recharges ne nécessitent qu’une grille tarifaire, un forfait fixe avec dépassements nécessite une grille tarifaire et des frais de licence, et des crédits récurrents avec dépassement nécessitent une grille tarifaire et une action de service. #### Dashboard ### Créez l’offre tarifaire 1. Sur l’onglet [Offre tarifaire](https://dashboard.stripe.com/test/pricing-plans), cliquez sur **Créer offre tarifaire**. 1. Dans l’éditeur d’offre tarifaire : - Indiquez un nom d’affichage, un devise et un comportement fiscal. - (Facultatif) Sous **Paramètres avancés**, spécifiez la description, la clé de recherche unique et les métadonnées. 1. Cliquez sur **Continuer**. ### Ajouter une carte tarifaire 1. Dans l’éditeur d’offre tarifaire, cliquez sur + et **Grille tarifaire**. 1. Dans l’éditeur de grille tarifaire : - Indiquez un nom d’affichage. - Spécifiez la période de service{ % si $features. PRICING_PLANS_API_ACCESS %} (en savoir plus sur les [intervalles de service et de facturation](https://docs.stripe.com/billing/subscriptions/usage-based/advanced/about.md#cadence-service-interval)){ % /if %}. - (Facultatif) Sous **Paramètres avancés**, fournissez une clé de recherche et des métadonnées. 1. Cliquez sur **Continuer**. ### Associer un tarif à la grille tarifaire 1. Dans l’éditeur de tarifs : - Fournissez un nom d’affichage pour l’élément comptabilisé. Par exemple, `Hypernian tokens`. - Sélectionnez un **Dispositif de mesure** existant ou créez-en un nouveau en cliquant sur +. - Sélectionnez le **Type de prix** : **Tarif fixe**, [En fonction du volume](https://docs.stripe.com/subscriptions/pricing-models/tiered-pricing.md#volume-based-pricing), ou[Progressif](https://docs.stripe.com/subscriptions/pricing-models/tiered-pricing.md#graduated-pricing). Par exemple, Hypernian utilise un tarif fixe. - Sélectionnez **Vendre sous forme** d’unités individuelles ou d’un ensemble d’unités. Par exemple, une entreprise d’IA peut vendre ses tokens sous forme de paquets de`100` unités, à`0.04 USD` par paquet. - Pour les forfaits, saisissez le **Nombre d’unités par forfait**. - Précisez si vous souhaitez arrondir à l’unité supérieure ou inférieure pour les **lots partiels**. Si vous arrondissez à l’unité supérieure, un utilisateur qui utilise 110 unités est facturé 0,08 USD. - Saisissez le **tarif par lot**. - (facultatif) Configurez les **Paramètres avancés** de votre élément mesuré, tels que la spécification d’un **Code fiscal produit** (en savoir plus sur les [codes fiscaux](https://docs.stripe.com/tax/tax-codes.md)), d’une **Étiquette d’unité**, d’une **Clé de recherche** et de **Métadonnées**. vous pouvez également ajouter des métadonnées au tarif. 1. Cliquez sur **Terminé**. 1. (Facultatif) Cliquez sur + **Ajouter un tarif** pour ajouter des tarifs supplémentaires à la grille tarifaire. ### Ajouter un droit de licence 1. Dans l’éditeur d’offre tarifaire, cliquez sur + et **Frais de licence**. 1. Dans l’éditeur de frais de licence : - Indiquez un nom d’affichage pour l’élément sous licence. - Spécifiez la période de service{ % si $features. PRICING_PLANS_API_ACCESS %} (en savoir plus sur les [intervalles de service et de facturation](https://docs.stripe.com/billing/subscriptions/usage-based/advanced/about.md#cadence-service-interval)){ % /if %}. - Sélectionnez le **Type de prix** : **Tarif fixe**, [Volume](https://docs.stripe.com/subscriptions/pricing-models/tiered-pricing.md#volume-based-pricing), ou[Gradué](https://docs.stripe.com/subscriptions/pricing-models/tiered-pricing.md#graduated-pricing). Par exemple`50,00 USD` par unité. - (facultatif) Configurez les **Paramètres avancés** pour votre élément sous licence, comme la spécification d’un **Code fiscal produit** (en savoir plus sur les [codes fiscaux](https://docs.stripe.com/tax/tax-codes.md)), d’une **Étiquette d’unité**, d’une **Clé de recherche** et de **Métadonnées**. vous pouvez également ajouter des métadonnées aux frais. 1. Cliquez sur **Terminé**. ### Ajouter une action de service 1. Dans l’éditeur d’offre tarifaire, cliquez sur + et **Octroi de crédits**. 1. Dans l’éditeur de crédits récurrents : - Fournissez un nom d’affichage pour l’octroi de crédit. - Spécifiez la période de service{ % si $features. PRICING_PLANS_API_ACCESS %} (en savoir plus sur les [intervalles de service et de facturation](https://docs.stripe.com/billing/subscriptions/usage-based/advanced/about.md#cadence-service-interval)){ % /if %}. - Fournissez un montant de crédit. - (Facultatif) Configurez les **Paramètres avancés** pour votre octroi de crédits récurrents, tels que la spécification d’une **Application** ou d’une **Clé de recherche**. 1. Cliquez sur **Terminé**. Une fois la configuration de l’offre tarifaire terminée, cliquez sur **Créer une offre tarifaire**. #### API ### Créez l’offre tarifaire Lorsque vous créez une [offre tarifaire](https://docs.stripe.com/api/v2/pricing-plans.md?api-version=preview), indiquez un nom d’affichage, une devise et précisez le comportement fiscal (en savoir plus sur le [comportement fiscal et les grilles tarifaires](https://docs.stripe.com/tax/subscriptions/rate-card-tax-codes-tax-behavior.md#set-a-default-tax-behavior-recommended)). ```curl curl -X POST https://api.stripe.com/v2/billing/pricing_plans \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "display_name": "Pro Pricing Plan", "currency": "usd", "tax_behavior": "exclusive" }' ``` Après avoir soumis la demande d’offre tarifaire, Stripe renvoie l’objet `Offre tarifaire` active. Vous ne pouvez pas souscrire de nouveaux clients à une offre tarifaire inactive. ```json { "id": "bpp_test_61SjPwyNGx88hyuOg16SjPfE4ZSQFjWjdqlzQfWMCH1E", "object": "v2.billing.pricing_plan", "active": true, "created": "2025-06-14T21:52:04.000Z", "currency": "usd", "description": null, "display_name": "Pro Pricing Plan", "latest_version": "bppv_test_123", "live_version": "bppv_test_123", "lookup_key": null, "metadata": {}, "tax_behavior": "exclusive" } ``` ### Ajouter une carte tarifaire Pour joindre une grille tarifaire à votre offre tarifaire pour facture vos clients en fonction de leur utilisation, créez une grille tarifaire et indiquez un nom d’affichage, une devise, un intervalle de service et un comportement fiscal. ```curl curl -X POST https://api.stripe.com/v2/billing/rate_cards \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "display_name": "Hypernian", "service_interval": "month", "service_interval_count": 1, "currency": "usd", "tax_behavior": "exclusive" }' ``` ### Créer un compteur ```curl curl https://api.stripe.com/v1/billing/meters \ -u "<>:" \ -d "display_name=Hypernian tokens" \ -d event_name=hypernian_tokens \ -d "default_aggregation[formula]=sum" \ -d "customer_mapping[event_payload_key]=stripe_customer_id" \ -d "customer_mapping[type]=by_id" \ -d "value_settings[event_payload_key]=value" ``` ### Créer un élément mesuré Après avoir créé un compteur, créez un élément mesuré pour représenter l’élément spécifique que le client paie, comme un modèle LLM ou un niveau d’utilisation de token. ```curl curl -X POST https://api.stripe.com/v2/billing/metered_items \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "display_name": "Hypernian tokens", "meter": "{{METER_ID}}", "lookup_key": "hypernian_tokens" }' ``` ### Associer un tarif au compteur Après avoir créé un élément mesuré, associez un tarif au compteur. ```curl curl -X POST https://api.stripe.com/v2/billing/rate_cards/{{RATE_CARD_ID}}/rates \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "metered_item": "{{METERED_ITEM_ID}}", "unit_amount": "5" }' ``` ### Associer une carte tarifaire à une offre tarifaire Une fois le tarif créé, associez la grille tarifaire à l’offre tarifaire : ```curl curl -X POST https://api.stripe.com/v2/billing/pricing_plans/{{PRICING_PLAN_ID}}/components \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "type": "rate_card", "rate_card": { "id": "{{RATE_CARD_ID}}", "version": "{{RATE_CARD_VERSION}}" }, "metadata": { "existing_key": "updated_value", "new_key": "new value" } }' ``` ### Ajouter un droit de licence Les frais de licence sont des frais fixes récurrents, que vous pouvez utiliser pour débiter des frais initiaux. Tout d’abord, créez un élément de licence : ```curl curl -X POST https://api.stripe.com/v2/billing/licensed_items \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "display_name": "Pricing Plan Licensed Item" }' ``` Ensuite, créez un droit de licence : ```curl curl -X POST https://api.stripe.com/v2/billing/license_fees \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "display_name": "E2E License", "licensed_item": "{{LICENSED_ITEM_ID}}", "unit_amount": "50000", "service_interval": "month", "service_interval_count": 1, "currency": "usd", "tax_behavior": "exclusive" }' ``` Enfin, joignez la redevance à une offre tarifaire : ```curl curl -X POST https://api.stripe.com/v2/billing/pricing_plans/{{PRICING_PLAN_ID}}/components \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "type": "license_fee", "license_fee": { "id": "{{LICENSE_FEE_ID}}", "version": "{{LICENSE_FEE_VERSION}}" }, "lookup_key": "monthly-fee-component", "metadata": { "existing_key": "updated_value", "new_key": "new value" } }' ``` ### Ajouter une action de service Vous pouvez ajouter de nouvelles composantes, y compris des subventions de crédit récurrentes, à votre offre tarifaire. Utilisez des subventions de crédit récurrentes si vous utilisez un [modèle de tarification à crédit dégressif ](https://docs.stripe.com/subscriptions/pricing-models/usage-based-pricing.md#credit-burndown). Les actions de service vous permettent d’offrir des crédits récurrents aux clients, ce qui peut compenser les frais pour des éléments facturables spécifiques, tels que les frais à l’usage. Lorsque vous créez une action de service, vous configurez : - Montant - Fréquence de facturation - Articles facturables applicables Pour créer une attribution mensuelle de crédits de 10 USD qui expire à la fin de l’intervalle de service : ```curl curl -X POST https://api.stripe.com/v2/billing/service_actions \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "service_interval": "month", "service_interval_count": 1, "type": "credit_grant", "lookup_key": "credit grant 28", "credit_grant": { "name": "Credit grant 28", "expiry_config": { "type": "end_of_service_period" }, "applicability_config": { "scope": { "price_type": "metered" } }, "amount": { "type": "monetary", "monetary": { "value": 1000, "currency": "usd" } } } }' ``` Joindre l’action de service à votre offre tarifaire : ```curl curl -X POST https://api.stripe.com/v2/billing/pricing_plans/{{PRICING_PLAN_ID}}/components \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "type": "service_action", "service_action": { "id": "{{SERVICE_ACTION_ID}}" }, "lookup_key": "credit-grant-28", "metadata": { "existing_key": "updated_value", "new_key": "new value" } }' ``` ### Activer l’offre tarifaire Une fois que vous avez ajouté les composants correspondants à votre modèle tarifaire, activez cette version de l’offre tarifaire. Une fois l’offre activée, vous pouvez [y abonner des clients](https://docs.stripe.com/billing/subscriptions/usage-based/pricing-plans.md#subscribe). ```curl curl -X POST https://api.stripe.com/v2/billing/pricing_plans/{{PRICING_PLAN_ID}} \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "live_version": "latest" }' ``` ## Souscrire votre client à une offre tarifaire Après avoir configuré une offre tarifaire, vous pouvez y abonner un client. Vous pouvez créer un abonnement en utilisant l’[API Checkout Sessions](https://docs.stripe.com/api/checkout/sessions.md) avec [une page hébergée par Stripe ou des éléments Checkout, comme l’interface utilisateur de paiement](https://docs.stripe.com/payments/checkout.md) (la session Checkout crée également un client). Vous pouvez également utiliser l’API pour créer directement un abonnement à une offre tarifaire. Si vous utilisez la méthode API directe, vous devez créer [un client](https://docs.stripe.com/api/customers/create.md), un [paramètre de recouvrement](https://docs.stripe.com/api/v2/billing-settings/collection-settings/create.md?api-version=preview), une [fréquence de facturation](https://docs.stripe.com/api/v2/billing/cadences/create.md?api-version=preview) et un [Intent de facturation](https://docs.stripe.com/api/v2/billing-intents/intents/create.md?api-version=preview), qui crée l’abonnement à l’offre tarifaire. #### Page hébergée par Stripe Utilisez l’[API Checkout Sessions](https://docs.stripe.com/api/checkout/sessions.md) pour créer une page de paiement destinée à vos clients. Lorsqu’un client clique sur **S’abonner**, la session Checkout crée un objet [Client](https://docs.stripe.com/api/customers.md) (si vous n’avez pas fourni d’identifiant client pour la session) et un abonnement à une offre tarifaire. Si plusieurs éléments figurent dans `checkout_items`, un abonnement à une offre tarifaire est créé pour chaque élément. Voici un exemple de ce à quoi ressemble une offre tarifaire complète avec Checkout. ![Exemple de offre tarifaire](https://b.stripecdn.com/docs-statics-srv/assets/checkout_pricing_plan_example.2156a15535345b113c30e7efabe72867.png) Une offre tarifaire affichée dans Stripe Checkout ### Limitations de la session Checkout dans la version bêta privée Lors de l’avant-première privée : - Vous pouvez passer un maximum de cinq [checkout_items](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-checkout_items). - Vous pouvez uniquement accepter les cartes bancaires Link, Apple Pay et Google Pay. - Vous ne pouvez pas transmettre un [début de cycle de facturation](https://docs.stripe.com/billing/subscriptions/billing-cycle.md) spécifique. - Vous ne pouvez pas utiliser les [taux de taxe](https://docs.stripe.com/billing/taxes/tax-rates.md), uniquement le calcul automatique des taxes. - Vous ne pouvez pas utiliser les réductions. - Vous ne pouvez pas [limiter les clients à un seul abonnement](https://docs.stripe.com/payments/checkout/limit-subscriptions.md). - Vous ne pouvez pas utiliser [Connect](https://docs.stripe.com/connect.md). - Vous ne pouvez pas ajouter des [articles facultatifs](https://docs.stripe.com/payments/checkout/optional-items.md) ou des [ventes croisées](https://docs.stripe.com/payments/checkout/cross-sells.md). Pour bénéficier d’un accès anticipé et faire part de vos commentaires ou requêtes sur le produit, contactez [advanced-ubb-private-preview@stripe.com](mailto:advanced-ubb-private-preview@stripe.com). Pour [créer une session Checkout](https://docs.stripe.com/api/checkout/sessions/create.md) avec les offres tarifaires, incluez dans le tableau [checkout_items](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-checkout_items) un objet dont le [type](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-checkout_items-type) est défini sur `pricing_plan_subscription_item` et qui inclut une configuration `pricing_plan_subscription_item`. Lorsque vous utilisez `checkout_items` au lieu de `line_items`, vous n’avez pas besoin de spécifier le [mode](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode). ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -H "Stripe-Version: 2025-09-30.preview;checkout_product_catalog_preview=v1" \ -d customer={{CUSTOMER_ID}} \ -d "checkout_items[0][type]=pricing_plan_subscription_item" \ -d "checkout_items[0][pricing_plan_subscription_item][pricing_plan]={{PRICING_PLAN_ID}}" \ -d success_url={{SUCCESS_URL}} ``` Si votre offre tarifaire comprend des frais de licence, vous devez indiquer la valeur des frais de licence : Obtenez l’identifiant du composant des frais de licence : ```curl curl https://api.stripe.com/v2/billing/pricing_plans/{{PRICING_PLAN_ID}}/components \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2025-09-30.preview" ``` Créez la session Checkout en utilisant l’identifiant du composant des frais de licence : ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -H "Stripe-Version: 2025-09-30.preview;checkout_product_catalog_preview=v1" \ -d customer={{CUSTOMER_ID}} \ -d "checkout_items[0][type]=pricing_plan_subscription_item" \ -d "checkout_items[0][pricing_plan_subscription_item][pricing_plan]={{PRICING_PLAN_ID}}" \ -d "checkout_items[0][pricing_plan_subscription_item][component_configurations][{{LICENSE_COMPONENT_ID}}][type]=license_fee_component" \ -d "checkout_items[0][pricing_plan_subscription_item][component_configurations][{{LICENSE_COMPONENT_ID}}][license_fee_component][quantity]=1" ``` La page affiche les détails de votre offre tarifaire et recueille les informations de paiement du client. Une fois la session terminée, l’abonnement à une offre tarifaire est créé et le client est redirigé vers l’URL que vous avez spécifiée pour `success_url`. En savoir plus sur [la personnalisation du comportement de redirection avec Checkout](https://docs.stripe.com/payments/checkout/custom-success-page.md). #### Éléments Checkout Pour mieux contrôler l’apparence de la page de paiement de votre offre tarifaire, vous pouvez utiliser les [éléments Checkout](https://docs.stripe.com/payments/quickstart-checkout-sessions.md) avec l’API Checkout Sessions. L’objet [Session](https://docs.stripe.com/js/custom_checkout/session_object) des éléments Checkout expose les détails de votre offre tarifaire dans [session.orderSummaryItems](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-orderSummaryItems), ce qui vous permet d’afficher un récapitulatif de commande pour votre offre tarifaire, les frais de licence et les grilles tarifaires. Vous devez toujours utiliser le même paramètre `checkout_items` lors de la création de la session Checkout sur votre serveur. ### Limitations de la session Checkout dans la version bêta privée Lors de l’avant-première privée : - Vous pouvez passer un maximum de cinq [checkout_items](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-checkout_items). - Vous pouvez uniquement accepter les cartes bancaires Link, Apple Pay et Google Pay. - Vous ne pouvez pas transmettre un [début de cycle de facturation](https://docs.stripe.com/billing/subscriptions/billing-cycle.md) spécifique. - Vous ne pouvez pas utiliser les [taux de taxe](https://docs.stripe.com/billing/taxes/tax-rates.md), uniquement le calcul automatique des taxes. - Vous ne pouvez pas utiliser les réductions. - Vous ne pouvez pas [limiter les clients à un seul abonnement](https://docs.stripe.com/payments/checkout/limit-subscriptions.md). - Vous ne pouvez pas utiliser [Connect](https://docs.stripe.com/connect.md). - Vous ne pouvez pas ajouter des [articles facultatifs](https://docs.stripe.com/payments/checkout/optional-items.md) ou des [ventes croisées](https://docs.stripe.com/payments/checkout/cross-sells.md). Pour bénéficier d’un accès anticipé et faire part de vos commentaires ou requêtes sur le produit, contactez [advanced-ubb-private-preview@stripe.com](mailto:advanced-ubb-private-preview@stripe.com). ### Utilisez l’en-tête bêta du catalogue de produits Lors de l’initialisation d’une instance Stripe sur votre front-end avec votre clé publiable, passez l’en-tête`custom_checkout_product_catalog_1` beta. ```js const stripe = Stripe( '<>',{betas: ['custom_checkout_product_catalog_1']}, ); ``` ```javascript import {loadStripe} from '@stripe/stripe-js'; const stripe = loadStripe("<>", {betas: ['custom_checkout_product_catalog_1'], }); ``` #### API Utilisez directement les API pour [créer un client](https://docs.stripe.com/api/customers/create.md), puis pour [créer une période de facturation](https://docs.stripe.com/api/v2/billing-cadences/cadences/create.md?api-version=preview). Vous pouvez débiter automatiquement le moyen de paiement par défaut du client ou lui envoyer la facture pour qu’il la paie manuellement. Après avoir créé un client et une période de facturation, vous pouvez [créer un abonnement à une offre tarifaire](https://docs.stripe.com/api/v2/billing-intents/intents/create.md?api-version=preview). Par défaut, nous débitons automatiquement le moyen de paiement enregistré par le client. Pour envoyer une facture, [créez un paramètre d’encaissement](https://docs.stripe.com/api/v2/billing-settings/collection-settings/create.md?api-version=preview) avec le paramètre `collection_method` défini sur `send_invoice`. Transmettez ensuite le paramètre d’encaissement lorsque vous créez la cadence. ## Enregistrer l’usage des clients Après avoir souscrit un client à une offre tarifaire composée d’une carte tarifaire, enregistrez son utilisation de votre service en envoyant les événements de compteur à un compteur. #### Dashboard 1. Allez dans l’onglet [Offres tarifaires abonnements à une offre tarifaire](https://dashboard.stripe.com/test/pricing-plans/subscriptions) . 1. Cliquez sur l’abonnement pour lequel vous souhaitez enregistrer l’utilisation. 1. Sélectionnez **Afficher** pour voir les composantes de l’offre tarifaire sous-jacente et accédez à la carte tarifaire pour laquelle vous souhaitez ajouter de l’utilisation. 1. Cliquez sur le menu de débordement (⋯) dans la ligne du poste pour lequel vous souhaitez enregistrer l’utilisation, puis cliquez sur **Afficher les détails du dispositif de mesure**. 1. Sur la page d’informations du dispositif de mesure, cliquez sur **+ Ajouter une utilisation**, puis sélectionnez **Saisir manuellement l’utilisation**. 1. Dans la boîte de dialogue **Ajouter une utilisation** : - Sélectionnez un client. - Saisissez une **valeur** pour l’utilisation. - Sélectionnez une date pour **Horodatage**. 1. Cliquez sur **Envoyer**. #### API Utilisez les [événements du compteur](https://docs.stripe.com/api/billing/meter-event.md) pour [comptabiliser la consommations de vos clients](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage.md). À la fin de la période de facturation, Stripe facture l’utilisation déclarée. Pour tester la facturation à l’usage, envoyez des événements de compteur via le Dashboard ou l’API Stripe. Lorsque vous utilisez l’API, spécifiez l’ID client et la valeur d’utilisation de la `charge utile`. En savoir plus sur [l’intégration](https://docs.stripe.com/billing/subscriptions/usage-based/pricing-plans.md#test-the-integration) de offres tarifaires. ```curl curl https://api.stripe.com/v1/billing/meter_events \ -u "<>:" \ -d event_name=hypernian_tokens \ -d "payload[stripe_customer_id]={{CUSTOMER_ID}}" \ -d "payload[value]=25" ``` ## Créer un aperçu de la facture Créez un aperçu de la facture pour afficher un aperçu de la facture d’un client. L’aperçu comprend les éléments d’exécution pertinents des différents composants du offre tarifaire. #### Dashboard 1. Allez dans l’onglet [Offres tarifaires abonnements à une offre tarifaire](https://dashboard.stripe.com/test/pricing-plan/subscriptions) . 1. Cliquez sur l’abonnement pour lequel vous souhaitez afficher l’aperçu d’une facture. 1. Faites défiler jusqu’à la section **Facture à venir**. La facture d’aperçu indique le montant de l’abonnement à facturer au client à la date spécifiée, et reflète les articles compteurs, les articles de licence et les crédits correspondants. #### API ```curl curl https://api.stripe.com/v1/invoices/create_preview \ -u "<>:" \ -H "Stripe-Version: 2025-12-15.clover" \ -d billing_cadence=bc_test_61SrjnScUwT6mNskZ16SjPfE4ZSQFjWjdqlzQfWMCVnM ``` ```json {"hosted_invoice_url": "example.com/invoice", "invoice_pdf": null, "billing_reason": "manual", "collection_method": "charge_automatically", "created": 1680644467, "currency": "usd", "custom_fields": null, "customer": "cus_NeZwdNtLEOXuvB", "customer_address": null, "customer_email": "jennyrosen@example.com", "customer_name": "Jenny Rosen", "customer_phone": null, "customer_shipping": null, "customer_tax_exempt": "none", "customer_tax_ids": [], "default_payment_method": null, "default_source": null, "default_tax_rates": [], "description": null, "discounts": [], "due_date": null, "ending_balance": null, "footer": null, "from_invoice": null, "last_finalization_error": null, "latest_revision": null, "lines": { "object": "list", "data": [], "has_more": false, "total_count": 0, "url": "/v1/invoices/in_1MtHbELkdIwHu7ixl4OzzPMv/lines" }, "id": "upcoming_in_1MtHbELkdIwHu7ixl4OzzPMv", "object": "invoice", "account_country": "US", "account_name": "Stripe Docs", "account_tax_ids": null, "amount_due": 0, "amount_paid": 0, "amount_overpaid": 0, "amount_remaining": 0, "amount_shipping": 0, "application": null, "application_fee_amount": null, "attempt_count": 0, "attempted": false, "auto_advance": false, "automatic_tax": { "enabled": false, "status": null }, "livemode": false, "metadata": {}, "next_payment_attempt": null, "number": null, "on_behalf_of": null, "parent": null, "payment_settings": { "default_mandate": null, "payment_method_options": null, "payment_method_types": null }, "period_end": 1680644467, "period_start": 1680644467, "post_payment_credit_notes_amount": 0, "pre_payment_credit_notes_amount": 0, "receipt_number": null, "shipping_cost": null, "shipping_details": null, "starting_balance": 0, "statement_descriptor": null, "status": "draft", "status_transitions": { "finalized_at": null, "marked_uncollectible_at": null, "paid_at": null, "voided_at": null }, "subtotal": 0, "subtotal_excluding_tax": 0, "test_clock": null, "total": 0, "total_discount_amounts": [], "total_excluding_tax": 0, "total_taxes": [], "webhooks_delivered_at": 1680644467 } ``` ## Surveiller les événements de service Les abonnements à l’offre tarifaire envoient des notifications d’événement chaque fois que les états de service et recouvrement changent. Écoutez ces événements et utilisez-les pour construire votre logique métier : | Événement | Description | | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `v2.billing.pricing_plan_subscription.servicing_activated` | Envoyé lorsque le service de l’abonnement devient actif, soit au début de la première période de service, soit lors de la reprise d’un abonnement en pause. | | `v2.billing.pricing_plan_subscription.servicing_paused` | Envoyé lorsque Stripe suspend la gestion de l’abonnement. | | `v2.billing.pricing_plan_subscription.servicing_canceled` | Envoyé lors de l’annulation de la gestion de l’abonnement, soit par le client, soit par Stripe | | `v2.billing.pricing_plan_subscription.collection_current` | Envoyé lorsque le recouvrement du paiement de l’abonnement est à jour et que tous les paiements ont été traités. | | `v2.billing.pricing_plan_subscription.collection_awaiting_customer_action` | Envoyé lorsque le recouvrement du paiement nécessite une action de la part du client (par exemple, l’authentification 3DS) | | `v2.billing.pricing_plan_subscription.collection_paused` | Envoyé lorsque Stripe suspend le recouvrement des paiements de l’abonnement. | Pour traiter ces événements [v2](https://docs.stripe.com/api/v2/core/events.md?api-version=preview), configurez une [destination d’événement ](https://docs.stripe.com/api/v2/core/event_destinations.md?api-version=preview) et dirigez-la vers votre endpoint webhook. Vous pouvez soit : - Créer la destination d’événement à partir de [Workbench](https://docs.stripe.com/workbench/event-destinations.md). - Créez la destination de l’événement [via l’API Stripe](https://docs.stripe.com/api/v2/core/event_destinations.md?api-version=preview). Une fois que vous avez créé une destination, vous pouvez configurer votre endpoint de webhook pour qu’il gère les événements suivants : ```ruby require 'stripe' post '/v2_webhook_endpoint' do payload = request.body.read sig_header = request.env['HTTP_STRIPE_SIGNATURE'] event = nil begin event = Stripe::Webhook.construct_event( payload, sig_header, endpoint_secret ) rescue JSON::ParserError => e status 400 return rescue Stripe::SignatureVerificationError => e status 400 return end client = Stripe::StripeClient.new("<>") case event.type when 'v2.billing.pricing_plan_subscription.servicing_activated' # Servicing becomes active, either when the first service period starts # or when a paused subscription resumes. subscription_id = event.related_object.id subscription = client.v2.billing.pricing_plan_subscriptions .retrieve(subscription_id) # Look up your user in the database using the metadata passed into # Checkout Session create user_id = subscription.metadata["my_user_id"] user = User.find_by_id(user_id) # Fill in your logic here: mark_subscription_active(user, subscription) when 'v2.billing.pricing_plan_subscription.servicing_paused' # Stripe pauses the subscription's servicing. subscription_id = event.related_object.id subscription = client.v2.billing.pricing_plan_subscriptions .retrieve(subscription_id) # Look up your user in the database using the metadata passed into # Checkout Session create user_id = subscription.metadata["my_user_id"] user = User.find_by_id(user_id) # Fill in your logic here: mark_subscription_paused(user, subscription) when 'v2.billing.pricing_plan_subscription.servicing_canceled' # Servicing is canceled, either by the customer or by Stripe. subscription_id = event.related_object.id subscription = client.v2.billing.pricing_plan_subscriptions .retrieve(subscription_id) # Look up your user in the database using the metadata passed into # Checkout Session create user_id = subscription.metadata["my_user_id"] user = User.find_by_id(user_id) # Fill in your logic here: mark_subscription_canceled(user, subscription) end status 200 end ``` ## Tester l'intégration Pour tester votre intégration : - [Créer un environnement de test]](/sandboxes/dashboard/manage#create-a-sandbox). - Créez une offre tarifaire test et au moins une composante tarifaire sous-jacente dans votre bac à sable. - Utilisez les [cartes de test](https://docs.stripe.com/testing.md) pour simuler les paiements réussis et les échecs de paiement. - Créez des [événements de test ](https://docs.stripe.com/billing/subscriptions/usage-based/pricing-plans.md#create-meter) pour simuler l’utilisation. - Utilisez [Simulations](https://docs.stripe.com/billing/testing/test-clocks/simulate-subscriptions.md) pour simuler la facturation. > #### Ne créez pas d'horloges de simulation dans le passé > > Lorsque vous créez une horloge de test pour un abonnement à une offre tarifaire, ne créez des horloges qu’à l’avenir. Si vous créez une horloge dans le passé, les montants des factures ne seront pas corrects. Créer un environnement de test avec un horodatage UNIX : ```curl curl https://api.stripe.com/v1/test_helpers/test_clocks \ -u "<>:" \ -d frozen_time=1577836800 ``` Notez l’ID de l’horloge de simulation. Ensuite, créez un client de test avec l’horloge : ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ --data-urlencode "email=test@example.com" \ -d test_clock={{TEST_CLOCK_ID}} ``` Créer un profil de facturation : ```curl curl -X POST https://api.stripe.com/v2/billing/profiles \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "customer": "{{CUSTOMER_ID}}" }' ``` Créez une période de facturation pour définir quand facturer le client. Enregistrez l’ID. ```curl curl -X POST https://api.stripe.com/v2/billing/cadences \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "payer": { "billing_profile": "{{BILLING_PROFILE_ID}}" }, "billing_cycle": { "type": "month", "interval_count": 3 }, "settings": { "collection": { "id": "{{COLLECTION_SETTINGS_ID}}" } } }' ``` [Créer une offre tarifaire](https://docs.stripe.com/billing/subscriptions/usage-based/pricing-plans.md#subscribe) pour le client concerné par le test. Créez une [intention de facturation](https://docs.stripe.com/api/v2/billing-intents/intents/create.md?api-version=preview) pour suivre l’état de l’abonnement à l’offre tarifaire. Tout d’abord, commencez par créer un brouillon d’intention de facturation. Enregistrez ensuite l’ID de l’intention. ```curl curl -X POST https://api.stripe.com/v2/billing/intents \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "currency": "usd", "cadence": "{{CADENCE_ID}}", "actions": [ { "type": "subscribe", "subscribe": { "type": "pricing_plan_subscription_details", "pricing_plan_subscription_details": { "pricing_plan": "{{PRICING_PLAN_ID}}", "pricing_plan_version": "{{PRICING_PLAN_VERSION}}" } } } ] }' ``` Ensuite, réservez l’intention de facturation : ```curl curl -X POST https://api.stripe.com/v2/billing/intents/{{BILLING_INTENT_ID}}/reserve \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" ``` Ensuite, validez l’intention de facturation pour activer l’abonnement à l’offre tarifaire et facturer le client selon l’offre tarifaire et la cadence. (Si vous avez configuré les paramètres d’encaissement sur `automatic`, vous devez disposer d’une [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) réussie pour valider l’intention. Si les paramètres d’encaissement sont définis sur `send_invoice`, vous n’avez pas besoin de transmettre l’intention de paiement). ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1000 \ -d currency=usd \ -d customer={{CUSTOMER_ID}} \ -d payment_method=pm_card_visa \ -d "return_url=example.com" \ -d confirm=true ``` À des fins de test, vous pouvez attribuer à `payment_method` la valeur « pm_card_visa ». ```curl curl -X POST https://api.stripe.com/v2/billing/intents/{{BILLING_INTENT_ID}}/commit \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "payment_intent": "{{PAYMENT_INTENT_ID}}" }' ``` Payez la facture générée par l’abonnement. Une fois la facture payée, vous pouvez simuler l’utilisation et faire avancer l’horloge, ce qui déclenche la facturation du mois suivant. Si vous utilisez Checkout, vous pouvez ouvrir l’`url` de la session Checkout renvoyée dans votre navigateur et effectuer le paiement à l’aide d’une [carte de test](https://docs.stripe.com/testing.md#use-test-cards). Enregistrez quelques tests d’utilisation : ```curl curl -X POST https://api.stripe.com/v2/billing/meter_events \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "event_name": "hypernian_tokens", "payload": { "stripe_customer_id": "{{CUSTOMER_ID}}", "value": "100" } }' ``` Avancez d’un mois le temps gelé de l’horloge de simulation. Dans cet exemple, l’horloge de test a actuellement un horodatage de `1577836800`. Pour ajouter un mois, ajoutez `30 * 24 * 60 * 60`, ou `2592000` secondes. Le nouvel horodatage par mois dans un mois est `1580428800`. ```curl curl https://api.stripe.com/v1/test_helpers/test_clocks/{{TEST_CLOCK_ID}}/advance \ -u "<>:" \ -d frozen_time=1580428800 ``` ## Optional: Collecter des taxes Pour collecter automatiquement les taxes, [créez une session Checkout](https://docs.stripe.com/api/checkout/sessions/create.md) incluant des [checkout_items](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-checkout_items) et définissez `automatic_tax.enabled` sur true. ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -H "Stripe-Version: 2025-09-30.preview;checkout_product_catalog_preview=v1" \ -d customer={{CUSTOMER_ID}} \ -d "checkout_items[0][type]=pricing_plan_subscription_item" \ -d "checkout_items[0][pricing_plan_subscription_item][pricing_plan]={{PRICING_PLAN_ID}}" \ -d success_url={{SUCCESS_URL}} \ -d "automatic_tax[enabled]=true" ``` La page affiche les détails de votre offre tarifaire et rassemble les informations de paiement du client. Une fois la session terminée, le client est redirigé vers l’URL que vous avez spécifiée pour `success_url`. ## Optional: Configurer le portail client Vous pouvez mettre à disposition des fonctions en libre-service pour vos clients en mettant en place un [portail client](https://docs.stripe.com/customer-management/activate-no-code-customer-portal.md). L’utilisation du portail client avec les abonnements à des offres tarifaires est actuellement en lecture seule : les clients ne peuvent pas annuler, modifier les offres ou mettre à jour leurs moyens de paiement pour les abonnements à des offres tarifaires. Actuellement, vous ne pouvez configurer une session de portail client qu’à partir du Dashboard. L’utilisation du portail client avec les abonnements aux offres tarifaires permet à vos clients de visualiser : - L’offre à laquelle ils sont abonnés, y compris les détails de l’offre hybride que vous proposez. - Des factures à venir qui les aident à comprendre combien ils seront facturés à la fin du mois. - Le moyen de paiement enregistré pour l’Abonnement en question. - Les factures antérieures pour lesquelles ils ont été débités. - Leurs informations de facturation.