Accéder directement au contenu
Créez un compte ou connecter-vous
Logo de la documentation Stripe
/
Créez un compteConnectez-vous

Mettre en place une facturation avancée à usage avec des offres tarifairesVersion bêta privée

Facturez vos clients en fonction de leur utilisation et des frais récurrents.

Vous pouvez regrouper différents composants tarifaires dans une seule offre tarifaire. Par exemple, vous pouvez créer une offre tarifaire qui inclut des cartes tarifaires pour la facturation à l’usage, des frais de licence pour les paiements récurrents et des actions de service liées aux crédits récurrents. Lorsqu’un client souscrit à une offre tarifaire, tous les composants récurrents sont automatiquement inscrits et facturés selon la fréquence que vous définissez. Les modèles tarifaires pris en charge incluent le paiement à l’utilisation et l’épuisement du crédit.

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

Version bêta privée

Les offres tarifaires sont actuellement en version bêta privée et peuvent changer en termes de fonctionnalités et de chemin d’intégration avant d’être généralement disponibles pour tous les utilisateurs Stripe. Contactez-nous pour demander l’accès.

Avant de commencer

You can also use a guided API (Blueprint) version of this guide in the Dashboard.

Les offres tarifaires utilisent des endpoints de l’API /v2. En savoir plus sur les espaces de noms /v2 et /v1.

Utilisez des bacs à sable pour tester l’intégration de vos offres tarifaires. Vous ne pouvez pas utiliser le mode test avec les API /v2.

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, vous pouvez configurer:

  • 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.
  • Métadonnées : ajoutez éventuellement vos propres métadonnées à l’offre tarifaire.

Après avoir défini les paramètres de devise et les paramètres fiscaux, définissez les composants pertinents de votre offre. Les composants que vous incluez dépendent de votre modèle de tarification. Ce guide utilise les trois composantes (

Créez l’offre tarifaire

  1. Sur l’onglet Offre tarifaire, cliquez sur Créer offre tarifaire.
  2. 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.
  3. Cliquez sur Continuer.

Ajouter une carte tarifaire

  1. Dans l’éditeur d’offre tarifaire, cliquez sur et Grille tarifaire.
  2. 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){ % /if %}.
    • (Facultatif) Sous Paramètres avancés, fournissez une clé de recherche et des métadonnées.
  3. 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, ouProgressif. 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 de100 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), 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.
  2. Cliquez sur Terminé.
  3. (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.
  2. 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){ % /if %}.
    • Sélectionnez le Type de prix : Tarif fixe, En fonction du volume, ouProgressif. Par exemple50.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), 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.
  3. Cliquez sur Terminé.

Ajouter une action de service

  1. Dans l’éditeur d’offre tarifaire, cliquez sur et Octroi de crédits.
  2. 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){ % /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.
  3. Cliquez sur Terminé.

Une fois la configuration de l’offre tarifaire terminée, cliquez sur Créer une offre tarifaire.

Souscrire votre client à une offre tarifaire

une fois une offre tarifaire configurée, vous pouvez y abonner un client. vous pouvez créer un abonnement en utilisant l’api checkout sessions avec une page hébergée par Stripe ou des composants intégrés comme interface utilisateur de paiement (la checkout session crée également un client). vous pouvez aussi utiliser l’api pour créer directement un abonnement à une offre tarifaire. si vous optez pour la méthode directe, vous devez créer un client, un paramètre de recouvrement, une cadence de facturation et une intention de facturation, qui ensemble créent l’abonnement avec une offre tarifaire.

Utilisez l’API Checkout Sessions 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 (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

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 :

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.

Pour créer une session Checkout avec les offres tarifaires, incluez dans le tableau checkout_items un objet dont le 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.

Command Line
cURL
No results
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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 :

Command Line
cURL
No results
curl https://api.stripe.com/v2/billing/pricing_plans/{{PRICING_PLAN_ID}}/components \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-09-30.preview"

Créez la session Checkout en utilisant l’identifiant du composant des frais de licence :

Command Line
cURL
No results
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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.

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.

  1. Allez dans l’onglet Offres tarifaires abonnements à une offre tarifaire .
  2. Cliquez sur l’abonnement pour lequel vous souhaitez enregistrer l’utilisation.
  3. 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.
  4. 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.
  5. Sur la page d’informations du dispositif de mesure, cliquez sur + Ajouter une utilisation, puis sélectionnez Saisir manuellement l’utilisation.
  6. 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.
  7. Cliquez sur Envoyer.

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.

  1. Allez dans l’onglet Offres tarifaires abonnements à une offre tarifaire .
  2. Cliquez sur l’abonnement pour lequel vous souhaitez afficher l’aperçu d’une facture.
  3. 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.

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 :

v2.billing.pricing_plan_subscription.servicing_activatedL’utilisateur paie l’abonnement qui active le service.
v2.billing.pricing_plan_subscription.servicing_pausedL’utilisateur met l’abonnement en pause.
v2.billing.pricing_plan_subscription.servicing_canceledL’utilisateur annule le service.
v2.billing.pricing_plan_subscription.collection_currentLe recouvrement de l’abonnement est en cours.
v2.billing.pricing_plan_subscription.collection_awaiting_customer_actionLe recouvrement attend que le client fasse quelque chose.
v2.billing.pricing_plan_subscription.collection_pausedLe recouvrement est interrompu.
v2.billing.rate_card_subscription.collection_past_dueLe recouvrement est exigible.
v2.billing.rate_card_subscription.collection_unpaidLe recouvrement est considéré comme impayé.

Pour traiter ces événements v2, configurez une destination d’événement et dirigez-la vers votre endpoint webhook. Vous pouvez soit :

Une fois que vous avez créé une destination, vous pouvez configurer votre endpoint de webhook pour qu’il gère les événements suivants :

server.rb
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(
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
)

  case event.type
  when 'v2.billing.pricing_plan_subscription.servicing_activated'
    # The customer clicked Pay on Stripe Checkout, which activates the service.
    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'
    # The customer paused the subscription.
    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'
    # The customer canceled the subscription.
    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 pour simuler les paiements réussis et les échecs de paiement.
  • Créez des événements de test pour simuler l’utilisation.
  • Utilisez des horloges de simulation 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 :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/test_helpers/test_clocks \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d frozen_time=1577836800

Notez l’ID de l’horloge de simulation. Ensuite, créez un client de test avec l’horloge :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  --data-urlencode email="test@example.com" \
  -d test_clock={{TEST_CLOCK_ID}}

Créer un profil de facturation :

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/billing/profiles \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: {{STRIPE_API_VERSION}}" \
  --json '{
    "customer": "{{CUSTOMER_ID}}"
  }'

Créez une période de facturation pour définir quand facturer le client. Enregistrez l’ID.

Command Line
cURL
No results
curl -X POST https://api.stripe.com/v2/billing/cadences \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: {{STRIPE_API_VERSION}}" \
  --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 pour le client concerné par le test.

Créez une intention de facturation 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.

Command Line
cURL
No results
curl -X POST https://api.stripe.com/v2/billing/intents \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: {{STRIPE_API_VERSION}}" \
  --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 :

Command Line
cURL
No results
curl -X POST https://api.stripe.com/v2/billing/intents/{{BILLING_INTENT_ID}}/reserve \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: {{STRIPE_API_VERSION}}"

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

Command Line
cURL
No results
curl https://api.stripe.com/payment_intent \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount={{AMOUNT}} \
  -d currency={{CURRENCY}} \
  -d customer={{CUSTOMER_ID}} \
  -d payment_method={{PM_ID}} \
  -d return_url="example.com" \
  -d confirm=true

À des fins de test, vous pouvez attribuer à payment_method la valeur « pm_card_visa ».

Command Line
cURL
No results
curl -X POST https://api.stripe.com/v2/billing/intents/{{BILLING_INTENT_ID}}/commit \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: {{STRIPE_API_VERSION}}" \
  --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.

Enregistrez quelques tests d’utilisation :

Command Line
cURL
No results
curl -X POST https://api.stripe.com/v2/billing/meter_events \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: {{STRIPE_API_VERSION}}" \
  --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.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/test_helpers/test_clocks/{{TEST_CLOCK_ID}}/advance \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d frozen_time=1580428800

FacultatifCollecter des taxes

Pour collecter automatiquement les taxes, créez une session Checkout incluant des checkout_items et définissez automatic_tax.enabled sur true.

Command Line
cURL
No results
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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}}

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.

FacultatifConfigurer le portail client

Vous pouvez mettre à disposition des fonctions en libre-service pour vos clients en mettant en place un portail client.

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.