Facturation à l'usageAncien

Vous pouvez utiliser des périodes d’essai pour les abonnements avec la 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 périodes d’essai

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, vérifiez qu’un moyen de paiement est défini pour le client afin de pouvoir le facturer. Si vous le souhaitez, vous pouvez notifier le client qu’il va être débité.

En savoir plus sur les abonnements et les webhooks.

Avec la facturation à l’usage, le tarif payé par le client varie en fonction de sa consommation au cours de la période de facturation. Lorsque la modification de la période de facturation entraîne la fin anticipée de la période de service d’un abonnement, vous facturez au client l’utilisation accumulée au cours de la période de facturation raccourcie.

Une fois un abonnement annulé, il ne peut plus être réactivé. Collectez dès lors les informations de facturation actualisées de votre client, mettez à jour son moyen de paiement par défaut et créez un nouvel abonnement à partir du dossier client existant.

Si l’annulation d’un abonnement a été prévue à l’aide du paramètre 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 consommation effective est indiquée dans une facture finale lorsque l’abonnement se termine, à la fin de la période de facturation.

Calculs au prorata

Lorsque votre client modifie son abonnement, un réajustement du montant dû. C’est ce que l’on appelle un calcul au prorata. Vous pouvez utiliser l’endpoint permettant la création de l’aperçu de la facture afin d’afficher le montant ajusté à vos clients.

Sur le front-end, transmettez les détails de l’aperçu de la facture à un endpoint du back-end.

function createPreviewInvoice(
  customerId,
  subscriptionId,
  newPriceId,
  trialEndDate
) {
  return fetch('/create-preview-invoice', {
    method: 'post',
    headers: {
      'Content-type': 'application/json',
    },
    body: JSON.stringify({
      customerId: customerId,
      subscriptionId: subscriptionId,
      newPriceId: newPriceId,
    }),
  })
    .then(response => {
      return response.json();
    })
    .then(invoice => {
      return invoice;
    });
}

Sur le back-end, définissez le endpoint que votre front-end appellera. Créez un aperçu de la facture et transmettez les changements que vous souhaitez prévisualiser. Dans le cas de cet exemple, vous devez supprimer le poste d’abonnement pour l’ID de l’ancien tarif, effacer l’utilisation, puis ajouter le nouvel ID du tarif. Ces changements ne sont pas réellement appliqués, ils définissent seulement la prévisualisation.

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

post '/create-preview-invoice' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  subscription = Stripe::Subscription.retrieve(data['subscriptionId'])

  invoice =
    Stripe::Invoice.create_preview(
      customer: data['customerId'],
      subscription: data['subscriptionId'],
      subscription_details: {
        items: [
          { id: subscription.items.data[0].id, deleted: true, clear_usage: true },
          { price: ENV[data['newPriceId']], deleted: false }
        ]
      }
    )

  invoice.to_json
end

Les seuils de facturation vous permettent d’émettre une facture, et de réinitialiser (facultativement) l’ancre du cycle de facturation d’un abonnement, lorsque l’utilisation accumulée d’un client au cours d’une période de service d’abonnement atteint un seuil monétaire ou d’utilisation spécifié. Envisagez d’utiliser des seuils de facturation si vous souhaitez ajouter des précautions pour limiter le montant dû ou les produits consommés entre les factures ou les paiements.

Ajouter un seuil monétaire à un abonnement

En règle générale, la valeur d’un seuil doit correspondre à un multiple du coût unitaire du produit vendu.

Si vous définissez un montant plus faible, vos clients recevront une facture pour chaque unité d’utilisation, ce qui peut être source de confusion.

La valeur est un entier positif exprimé dans l’unité monétaire la plus faible (par exemple, 100 centimes pour facturer 1 USD, ou 100 pour facturer 100 JPY, le JPY étant une devise sans décimale). Elle ne peut pas être inférieure à 50 unités monétaires.

Vous pouvez aussi définir des seuils monétaires dans le Dashboard lorsque vous créez ou modifiez un abonnement.

curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "billing_thresholds[amount_gte]"=10000 \
  -d "billing_thresholds[reset_billing_cycle_anchor]"="false"

Ajouter un seuil d’utilisation à un poste d’abonnement

Comme pour les seuils monétaires, les seuils d’utilisation doivent, dans l’idéal, être supérieurs à une unité d’utilisation afin d’éviter une facturation trop fréquente. À l’heure actuelle, Stripe ne prend pas en charge la définition de seuils d’utilisation via le Dashboard.

curl https://api.stripe.com/v1/subscription_items/si_CFhSgkWb0MyTWg \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "billing_thresholds[usage_gte]"=2000

Seuils et début du cycle de facturation

Lorsque la consommation d’un client atteint un seuil, la date de début du cycle de facturation de l’abonnement ne change pas (par défaut). Par exemple, si un seuil est atteint au milieu d’un abonnement mensuel, l’abonnement sera réinitialisé à la fin du mois, comme pour un abonnement sans seuil.

Vous pouvez modifier ce comportement de façon à ce que la date de début du cycle de facturation soit réinitialisée quand un seuil est atteint. De cette façon, le déclenchement du seuil sera traité comme si l’abonnement avait atteint son point de reconduction naturel à la fin du mois.

curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "billing_thresholds[reset_billing_cycle_anchor]"="true"

Notez que le paramétrage reset_billing_cycle_anchor=true n’est pas autorisé pour les abonnements facturés à la consommation qui présentent le paramétrage aggregate_usage=last_ever.

Seuils et tarification échelonnée

Les niveaux s’appliquent également aux factures à seuils. Comme pour les abonnements sans seuil, ces niveaux sont réinitialisés uniquement à la fin de la période de facturation, ou si vous configurez l’abonnement de manière à réinitialiser la date de début du cycle de facturation lorsqu’un seuil est atteint.

Par exemple, imaginons que vous gérez une plateforme publicitaire qui utilise une grille tarifaire progressive (graduated) pour ses impressions publicitaires :

L’utilisation étant facturée après coup, vous définissez un seuil de 100 USD pour le déclenchement de votre facturation. Dans cet exemple, votre client est facturé toutes les 200 impressions pour les 10 000 premières impressions (200 × 0,50 USD = 100 USD). Lorsque le client dépasse les 10 000 impressions, il est facturé toutes les 250 impressions (250 × 0,40 USD = 100 USD). Cela continue jusqu’à la fin de la période de facturation, stade auquel toute utilisation non facturée fait l’objet d’une nouvelle facturation. L’abonnement et les niveaux sont également réinitialisés.

Si vous préférez que les niveaux se réinitialisent quand un seuil est atteint, vous devez configurer l’abonnement de façon à réinitialiser la date de début du cycle de facturation lorsque l’utilisation atteint le seuil défini.

Tarification échelonnée au volume

La tarification échelonnée au volume assigne un même tarif à toutes les unités utilisées, contrairement à la tarification progressive qui assigne un tarif supplémentaire à chaque niveau de quantité franchi. Certains modèles tarifaires utilisent une tarification au volume afin de diminuer le tarif à l’unité au fur et à mesure que le nombre d’unités vendues augmente. Vous pouvez utiliser ces modèles pour encourager les clients à consommer vos produits (impressions publicitaires, Go de stockage, etc.) en plus grande quantité.

Associés à des seuils, ces modèles de tarification peuvent se traduire par des factures comportant des postes au montant négatif, dans les conditions suivantes :

1. Une facture à seuils a déjà été émise.
2. Les unités suivantes sont facturées à un coût unitaire plus faible.

Imaginons les niveaux suivants :

Si un client utilise 10 000 unités, le total de la facture sera de 5 000 USD (10 000 × 0,50 USD = 5 000 USD). Quand l’utilisation dépasse 10 000 unités, toutes les unités utilisées sont alors facturées à un coût unitaire plus faible de 0,40 USD. Donc, si le client utilise ne serait-ce qu’une unité supplémentaire, le montant facturé diminue, pour atteindre seulement 4 000,40 USD (10 001 × 0,40 USD = 4 000,40 USD).

Si aucun seuil n’avait été défini pour l’abonnement, Stripe émettrait une facture d’un montant de 4 000,40 USD à la fin de la période de facturation.

Cependant, pour vous montrer comment cela peut aboutir à une facture négative, imaginons que nous ayons défini un seuil monétaire de 5 000 USD. Dans ce scénario, Stripe émet une facture dès le client atteint 10 000 unités utilisées.

Si le client utilise uniquement une unité supplémentaire, le total de la facture chute à 4 000,40 USD (10 001 * 0,40 USD = 4 000,40 USD). Toutefois, si le client ne consomme pas d’autres unités, il doit recevoir 999,60 USD (5 000 USD - 4 000,40 USD = 999,60 USD). En fin de période de facturation, Stripe crédite ce montant sur le solde du client, montant qui sera utilisé pour le règlement des prochaines factures.

Imaginons que le client continue de cumuler de l’utilisation. Le coût de cette utilisation atteint 5 000 USD à nouveau lorsque le client a utilisé 12 500 unités (5 000 USD/0,40 USD = 12 500). Cependant, le paiement précédent de 5 000 USD couvrant déjà toutes ces utilisations, aucune facture n’est émise.

Stripe n’émettra pas de facture tant que l’utilisation totale n’aura pas atteint 25 000 unités (pour un coût total de 10 000 USD), ou tant que la période de facturation ne sera pas arrivée à son terme (selon la première de ces éventualités à survenir). Les tableaux ci-dessous montrent les postes auxquels vous devez vous attendre pour les deux factures émises dans le cas où l’utilisation atteindrait 25 000 unités.

Facture 1

Facture 2

Limites et mises en garde

• Les seuils ne s’appliquent pas aux abonnements avec période d’essai.
• Les seuils monétaires doivent être supérieurs à la somme de tous les frais fixes sur les abonnements facturés à l’utilisation.
• Les seuils de facturation ne sont pas évalués durant les 24 heures précédant la fin d’un abonnement. Cela permet d’éviter toute confusion chez un client qui reçoit plusieurs factures à la même date.
• Vous ne pouvez définir qu’un seuil monétaire par abonnement.
• Vous ne pouvez définir qu’un seuil d’utilisation par poste d’abonnement.
• L’utilisation étant communiquée en temps réel, les factures peuvent ne pas être émises au moment exact où le seuil est atteint. L’utilisation ou les montants facturés peuvent être légèrement supérieurs aux seuils spécifiés.
• La valeur utilisée pour déterminer si un seuil monétaire a été atteint inclut les réductions et les calculs au prorata applicables, mais ne tient pas compte des taxes.
• Si un abonnement utilise le mode de regroupement last_ever, vous ne pouvez pas activer l’option reset_billing_anchor.

Vous pouvez appliquer le modèle tarifaire à l’usage lorsque l’unité que vous mesurez ne repose pas strictement sur une somme.

Par exemple, Typographic propose un service de rédaction Web dont la facturation est établie en fonction du nombre de mots écrits. À la fin du mois, Typographic facture ses clients selon leur utilisation du service de rédaction, en plus des frais mensuels fixes. Typographic souhaite facturer le nombre maximum de mots utilisés par client et par mois. Pour cela, on peut utiliser le paramètre aggregate_usage :

curl https://api.stripe.com/v1/prices \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d nickname="Copywriting service" \
  -d product={{PRODUCT_ID}} \
  -d unit_amount=10000 \
  -d currency=usd \
  -d "recurring[interval]"=month \
  -d "recurring[usage_type]"=metered \
  -d "recurring[aggregate_usage]"=max

Imaginons qu’un client a utilisé 2 000 mots le 1er juin, puis 1 000 autres le 15. Il est ensuite crédité de 1 000 des 2 000 premiers mots le 20 juin. Le montant facturé à la fin du mois est de 2,00 USD (utilisation maximale de 2 000 mots au cours du mois à 0,10 USD par mot).

Le paramètre aggregate_usage détermine comment les abonnements gèrent les enregistrements d’utilisation. Les options de ce paramètre sont les suivantes :

• sum : la valeur par défaut (transmise si vous n’indiquez aucune valeur pour le paramètre). Le total facturé est calculé à partir de la somme de tous les enregistrements d’utilisation de la période de facturation.
• last_during_period : le total facturé est basé sur l’enregistrement d’utilisation le plus récent pour la période de facturation. Si aucune utilisation n’est signalée pour la période de facturation, le total facturé est basé sur la quantité d’utilisation 0.
• last_ever : le total facturé est basé sur l’enregistrement d’utilisation le plus récent. Si aucune utilisation n’est signalée pendant la période de facturation actuelle, Stripe recherche la dernière utilisation enregistrée. Si aucun enregistrement d’utilisation n’est trouvé, le total facturé est basé sur la quantité d’utilisation 0.
• max : le total facturé est basé sur l’utilisation enregistrée la plus élevée de la période de facturation. Si aucune utilisation n’est signalée pour la période de facturation, le total facturé est basé sur la quantité d’utilisation 0.

Le choix de l’option dépend de la manière dont vous gérez l’utilisation de votre côté. Définissez également la valeur du paramètre action de l’API Usage Records de manière à refléter la manière dont vous enregistrez l’utilisation.

curl https://api.stripe.com/v1/prices \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "currency"="usd" \
  -d "recurring[interval]"="month" \
  -d "recurring[usage_type]"="metered" \
  -d "product_data[name]"="Gold special" \
  -d "nickname"="Gold special price" \
  -d "unit_amount"=3000

Lorsque vous créez l’abonnement :

• Ne transmettez pas de paramètre quantity.
• Assurez-vous d’enregistrer l’ID du poste d’abonnement. Vous devez transmettre cette valeur à l’API Usage Records pour enregistrer l’utilisation.

Utilisez l’option transform_quantity pour cumuler l’utilisation avant de la multiplier par le coût unitaire. Cette option est utile si vous souhaitez communiquer une quantité ou utilisation différente avant de calculer le tarif total.

Typographic a décidé d’ajouter à son offre un service de conception de polices de caractères personnalisées. Les designs personnalisés demandant beaucoup de travail, des frais supplémentaires (un autre Product) sont donc facturés en fonction du niveau de personnalisation. Les designers indiquent le temps exact passé à réaliser les polices personnalisées. Cependant, Typographic ne souhaite pas facturer les clients à la minute, mais plutôt à l’heure de travail, même partielle.

Pour commencer, créez le produit de personnalisation des polices :

curl https://api.stripe.com/v1/products \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d name="Font Customization Service" \
  -d unit_label=Hours

Créez ensuite un tarif pour le produit de personnalisation de polices à hauteur de 150 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_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d nickname="Customization Per Hour Rate" \
  -d unit_amount=15000 \
  -d currency=usd \
  -d "recurring[interval]"=month \
  -d "recurring[usage_type]"=metered \
  -d product={{FONT_CUSTOMIZATION_SERVICE_PRODUCT_ID}} \
  -d "transform_quantity[divide_by]"=60 \
  -d "transform_quantity[round]"=up

Si un designer passe 150 minutes à créer des polices personnalisées, le client sera facturé 450 USD pour 3 heures de personnalisation (2 heures et 30 minutes, arrondies à l’heure supérieure).