Modéliser une tarification à l'usage

Vous pouvez utiliser des périodes d’essai pour les abonnements avec facturation à l’usage. Pendant la période d’essai, l’utilisation n’est pas comptabilisée dans le total facturé au client à la fin du cycle de facturation. Après la fin de la période d’essai, l’utilisation est comptabilisée et facturée à la fin du cycle de facturation suivant.

En savoir plus sur les périodes d’essai et les abonnements.

Webhooks et essais

Vérifiez que votre intégration surveille et gère correctement les événements Web relatifs aux modifications d’état des périodes d’essai.

Quelques jours avant la fin de la période d’essai et le passage de l’abonnement de trialing à active, vous recevez un événement customer.subscription.trial_will_end. À réception de cet événement, assurez-vous qu’un moyen de paiement est défini pour le client afin de pouvoir le facturer. Si vous le souhaitez, informez le client à l’avance du paiement à venir.

En savoir plus sur les abonnements et les webhooks.

Avec la facturation à l’usage, le montant que le client paie varie en fonction de la quantité consommée durant le cycle de facturation. Si la modification du cycle de facturation provoque la fin anticipée d’un intervalle d’abonnement, vous facturez le client pour l’utilisation cumulée au cours du cycle de facturation écourté. Nous ne prenons pas en charge le calcul au prorata avec la facturation à l’usage.

Une fois un abonnement annulé, il ne peut plus être réactivé. Vous pouvez collecter les informations de facturation actualisées de votre client, mettre à jour son moyen de paiement par défaut et créer un nouvel abonnement à partir du dossier client existant.

Après avoir planifié l’annulation d’un abonnement à l’aide de cancel_at_period_end, vous pouvez le réactiver à tout moment jusqu’à la fin de la période en attribuant au paramètre cancel_at_period_end la valeur false. Toute utilisation calculée est indiquée dans une facture finale après l’annulation de l’abonnement, à la fin de la période de facturation.

Utilisez l’option transform_quantity pour transformer l’utilisation avant d’appliquer le tarif. Cela vous permet de diviser l’utilisation mesurée par un nombre spécifique et d’arrondir le résultat à l’entier supérieur ou inférieur. Cette option est couramment utilisée pour définir le tarif d’un lot de produits plutôt que celui d’unités individuelles. La modification de la quantité n’est pas compatible avec la tarification échelonnée.

Supposons par exemple que vous ayez un service de location de voitures. Vous déclarez l’utilisation sous la forme d’un nombre de minutes et vous souhaitez facturer les clients pour chaque heure de location de la voiture.

curl https://api.stripe.com/v1/products \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d name="Car Rental Service"

Créez ensuite un tarif pour le service de location de voitures à hauteur de 10 USD par heure, arrondis au chiffre supérieur (de manière à facturer une heure complète même si elle n’est que commencée) :

curl https://api.stripe.com/v1/prices \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d nickname="Car Rental Per Hour Rate" \
  -d unit_amount=1000 \
  -d currency=usd \
  -d "recurring[interval]"=month \
  -d "recurring[usage_type]"=metered \
  -d product={{CAR_RENTAL_SERVICE_PRODUCT_ID}} \
  -d "transform_quantity[divide_by]"=60 \
  -d "transform_quantity[round]"=up

Si une voiture est louée pendant 150 minutes, le client est facturé 30 USD pour 3 heures de location (2 heures et 30 minutes, arrondies à l’unité supérieure).

La tarification avec décimale est utile si vous souhaitez fixer des tarifs qui ne sont pas des nombres entiers. Par exemple, si vous dirigez une entreprise SaaS de stockage dans le cloud, vous pouvez créer un tarif qui facture 0,05 centime pour chaque Mo consommé par mois. En fonction de l’utilisation, la quantité de Mo est alors multipliée par 0,05 centime et arrondie au centime le plus proche.

Pour créer des tarifs avec décimale, spécifiez unit_amount_decimal à la place de unit_amount. unit_amount_decimal vous permet de définir un montant dans la sous-unité de la devise utilisée pour la facturation. Par exemple, vous pouvez définir unit_amount_decimal = 105.5 en USD pour représenter 105,5 centimes, soit 1,055 USD. unit_amount_decimal accepte jusqu’à 12 décimales.

Si vous prévoyez d’utiliser des niveaux de tarification, vous pouvez spécifier l’attribut unit_amount_decimal à la place de unit_amount. Vous pouvez aussi créer des postes de facture avec unit_amount_decimal à la place de unit_amount.

Dans les réponses de l’API, le champ unit_amount, qui doit correspondre à un nombre entier, n’est pas renseigné si vous créez l’objet avec une valeur décimale. Par exemple, si vous créez un tarif avec unit_amount_decimal = 0.05, la réponse contient unit_amount = null et unit_amount_decimal = 0.05. Vous pouvez toujours transférer les valeurs entières dans unit_amount_decimal, auquel cas unit_amount est renseigné dans la réponse. Par exemple, si vous créez un tarif avec unit_amount_decimal = 5, la réponse contient unit_amount = 5 et unit_amount_decimal = 5.0.

Par défaut, Stripe finalise les factures d’abonnement une heure après leur génération. Pendant ce délai de grâce d’une heure, vous pouvez continuer à mesurer l’utilisation pour la période précédente. Lorsque la facture est finalisée, nous la mettons à jour de façon à refléter l’utilisation effective pour sa période de facturation.

L’utilisation mesurée après la finalisation de la facture n’est pas prise en compte dans les factures ultérieures.

Vous pouvez établir une période de grâce plus longue.

Vous pouvez mettre à jour le prix d’un poste d’abonnement au cours d’un cycle de facturation. Toutefois, les limitations suivantes s’appliquent lors du passage d’une tarification à la consommation à une autre :

• Seule l’utilisation effectuée après la mise à jour sera prise en compte dans les factures futures. L’utilisation antérieure à la modification ne sera pas facturée. Par exemple, si vous avez un abonnement mensuel et que vous passez du prix A au prix B le 16 janvier, la facture générée à la fin du mois tient compte de l’utilisation du 16 au 31 janvier au prix B. L’utilisation du 1er au 16 janvier n’est pas facturée.
• Il existe une exception à cette règle si vous utilisez des seuils de facturation et qu’une facture seuil a déjà été générée à l’ancien prix. Par exemple, dans le scénario ci-dessus, si vous avez généré une facture seuil le 10 janvier au prix A, cette facture seuil est toujours facturée au client. À la fin du mois, la facture générée comptabilise l’utilisation du 16 au 31 janvier au prix B. La facture seuil antérieure ne compense aucune utilisation pour cette facture de fin de mois.
• Des restrictions similaires s’appliquent si vous ajoutez un nouveau poste d’abonnement avec une tarification à la consommation au cours du cycle d’abonnement. Par exemple, si vous ajoutez un nouveau poste d’abonnement au prix C le 16 janvier, la facture générée à la fin du mois comptabilise l’utilisation du 16 au 31 janvier au prix C pour ce poste d’abonnement.

Voici comment mettre à jour le prix d’un poste d’abonnement :

curl https://api.stripe.com/v1/subscription_items/{{SUBSCRIPTION_ITEM_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d price={{NEW_PRICE_ID}}

Pour supprimer un poste d’abonnement :

curl -X DELETE https://api.stripe.com/v1/subscription_items/{{SUBSCRIPTION_ITEM_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:"

Après la suppression, aucune utilisation de ce poste n’apparaît sur la facture.

Vous pouvez déclarer l’utilisation d’un client avant même de créer un abonnement pour lui. Après avoir signalé l’utilisation d’un client, vous pouvez utiliser backdate_start_date pour créer un abonnement avant le premier rapport, ce qui garantit que l’utilisation sera incluse dans la prochaine facture d’abonnement.

curl -X POST https://api.stripe.com/v2/billing/meter_events \
  -H "Authorization: Bearer 
{{YOUR_API_KEY}}
" \
  -H "Stripe-Version: 2024-11-20.acacia" \
  --json '{
    "event_name": "alpaca_ai_tokens",
    "payload": {
        "value": "25",
        "stripe_customer_id": "{{CUSTOMER_ID}}"
    },
    "timestamp": "2024-04-01T12:00:00.000Z"
  }'

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d customer={{CUSTOMER_ID}} \
  -d "items[0][price]"={{PRICE_ID}} \
  -d backdate_start_date=1710000000