Gids

Usage-based billing met Stripe: zo bouwden we credits

AI-producten hebben een billingprobleem: elke actie kost een ander bedrag, en sommige acties mislukken. Wij losten dat drie keer op, met een creditsaldo in Postcrest en met beeldtegoeden in Twelve Lumens en Salestreak. Hier lees je hoe die systemen op Stripe werken, met vereenvoudigde code en de fouten die je beter kunt vermijden.

Martin Balk Oprichter van Balk.dev Bijgewerkt op 7 min leestijd
Op deze pagina
  1. Credits, meten per eenheid of tegoeden?
  2. Houd het grootboek in je eigen database bij
  3. Prijs elke actie met kostenregels
  4. Schrijf af van saldi onder een lock
  5. Reken nooit af voor mislukt werk
  6. Verwerk elke Stripe-webhook precies één keer
  7. Van betaling naar saldo
  8. Valkuilen waar we je voor waarschuwen
  9. Wat er in Stripe draait

Credits, meten per eenheid of tegoeden?

Er zijn drie gangbare manieren om verbruik af te rekenen, en we draaien er twee van in productie.

Model Hoe het werkt Goed voor Let op
CreditsKlanten krijgen of kopen een saldo; elke actie kost een aantal creditsVeel acties met heel verschillende kosten, zoals beeld, video en stem genererenCredits voelen abstract, dus toon de kosten van elke actie voordat die start
TegoedenEen abonnement bevat een aantal eenheden per periode, met bundels voor extra eenhedenEén hoofdeenheid die klanten snappen, zoals beelden per woning of producten per maandEenheden met een ander gewicht (een 2K-beeld telt als twee) vragen om duidelijke uitleg
Meten per eenheidVerbruik wordt aan Stripe gemeld en achteraf gefactureerdProducten met een gelijkmatige, voorspelbare eenheid, zoals infrastructuurKlanten zien de rekening pas achteraf, dus bouw verbruiksoverzichten en waarschuwingen

Postcrest werkt met credits, omdat die AI-werkplek meer dan 20 modellen met heel verschillende kosten aanbiedt. Twelve Lumens en Salestreak werken met tegoeden: beelden per woning of per product, met extra beeldbundels, en de belofte dat er geen credits of tokens aan te pas komen. Dezelfde Stripe eronder, een heel andere ervaring.

Houd het grootboek in je eigen database bij

Stripe is de bron van waarheid voor geld: abonnementen, facturen, betalingen, terugbetalingen. Je app hoort de bron van waarheid te zijn voor verbruik. In Postcrest is elke toekenning van credits een rij met een bron, een aantal, een vervaldatum en een status:

  • Bronnen: abonnement, bundel (een aanvulling die de klant kocht) en uitnodiging (credits voor het uitnodigen van iemand).
  • Vervaldatum: elke toekenning verloopt; aanvulbundels na een vast aantal weken.
  • Status: een toekenning staat in afwachting tot de factuur betaald is, wordt daarna actief en gaat over naar verbruikt of verlopen.
  • Maandelijkse reset: het tegoed uit het abonnement telt per factuurperiode en schuift niet door naar de volgende maand.
class Credit < ApplicationRecord
  belongs_to :organization
  has_many :generations

  enum :source, { subscription: "subscription", package: "package", invite: "invite" }
  enum :status, { payment_pending: "payment_pending", active: "active", used: "used", expired: "expired" }

  scope :available, -> { active.where(expires_at: Time.current..) }

  # Usage is derived, not decremented: only successful, billable generations count.
  def used_amount
    generations.not_failed.billable.sum(:cost)
  end

  def amount_left
    amount - used_amount
  end
end

De interessante keuze: verbruik wordt afgeleid in plaats van afgeschreven. Een toekenning houdt geen lopend saldo bij waar taken van aftrekken; het verbruik is de som van de kosten van de geslaagde generaties die eraan gekoppeld zijn. Een mislukte generatie telt gewoon niet mee, dus er valt niets terug te boeken.

Prijs elke actie met kostenregels

Met meer dan 20 modellen zouden vaste prijzen in controllers al snel een chaos worden. Elk model in Postcrest legt een basisprijs per run vast, plus de opties die die prijs veranderen:

class Generations::Core::ExampleImageModel < Generations::Core::Base
  cost_per_run 10
  cost_rule :resolution,        multiplier: { "4K" => 2 }
  cost_rule :enable_web_search, addition:   { true => 6 }
end

# One run costs ceil(cost_per_run * product of multipliers) + sum of additions,
# rounded up so a debit never undercharges.
def self.cost_for(field_values = {})
  multiplier = 1.0
  addition   = 0

  cost_rules.each do |field, rule|
    value = field_values[field]
    multiplier *= rule[:multiplier].fetch(value, 1).to_f
    addition   += rule[:addition].fetch(value, 0).to_i
  end

  (cost_per_run * multiplier).ceil + addition
end

Video wordt per seconde output geprijsd, met een tarief per resolutie. Een clip van vijf seconden in 1080p kost dus vijf keer het secondetarief voor 1080p. Sommige kosten ken je pas achteraf, zoals de uiteindelijke lengte van een gegenereerd bestand; die taken berekenen hun kosten opnieuw zodra het bestand binnen is.

Dezelfde regels sturen de interface aan. De modelkiezer toont ‘vanaf X credits’ op basis van de goedkoopste combinatie van opties, en voordat er iets draait, ziet de gebruiker de opbouw: de basisprijs, het effect van elke optie en het totaal.

Schrijf af van saldi onder een lock

Twee taken die in dezelfde seconde starten, kunnen allebei genoeg saldo zien en het allebei uitgeven. Overal waar je een teller bijhoudt die omlaag gaat, vergrendel je de rijen die je gaat wijzigen. Twelve Lumens verbruikt gekochte beeldbundels van oud naar nieuw, binnen een transactie die ze vergrendelt:

# Spend purchased image packs oldest first, under a row lock.
def self.consume!(organization, count: 1)
  ImagePackPurchase.transaction do
    purchases = organization.image_pack_purchases.usable.oldest_first.lock # SELECT ... FOR UPDATE
    available = purchases.sum(&:images_remaining)
    raise InsufficientBalance, "needs #{count}, has #{available}" if available < count

    remaining = count
    purchases.each do |purchase|
      break if remaining.zero?

      take = [purchase.images_remaining, remaining].min
      purchase.update!(images_used: purchase.images_used + take)
      remaining -= take
    end
  end
end

Van oud naar nieuw betekent dat de bundels die het eerst verlopen ook het eerst gebruikt worden, en dat verwachten klanten ook. Beelden uit het abonnement gaan voor bundels, en elke render legt een verbruiksregel vast met zijn gewicht: een render in 2K telt als twee beelden.

Reken nooit af voor mislukt werk

Generatieve modellen falen: timeouts, contentfilters, storingen bij de aanbieder. Klanten accepteren dat, maar ze accepteren niet dat ze ervoor betalen. Er zijn twee manieren om dat te voorkomen.

  • Leid verbruik af van geslaagde taken. Postcrest telt alleen generaties die niet mislukt zijn, dus een mislukking hoeft niet teruggeboekt te worden. Taken die een uur vastzitten, worden als mislukt gemarkeerd en vallen daarmee automatisch uit de telling.
  • Boek expliciet terug. Twelve Lumens schrijft het tegoed vooraf af en geeft het terug als een render mislukt. Dat gaat eerst naar de bundel die het laatst gebruikt is, en nooit meer dan die bundel verbruikte.
# Called when a render fails: give back exactly what it used.
def self.release!(version:)
  ImageUsage.transaction do
    version.image_usages.lock.each do |usage|
      ExtraImages.refund!(version.organization, count: usage.from_extra) if usage.from_extra.positive?
      usage.destroy!
    end
  end
end

Welke aanpak je ook kiest: maak het automatisch. Een terugboeking die afhangt van iemand bij support die een mail leest, is een terugboeking die niet gebeurt.

Verwerk elke Stripe-webhook precies één keer

Saldi veranderen als er geld beweegt, en geld beweegt via webhooks: checkout.session.completed voor een aanvulling, invoice.paid voor een verlenging. Stripe probeert een webhook opnieuw tot je met een 2xx antwoordt, in live-modus tot drie dagen lang, en kan hetzelfde event meer dan eens bezorgen. Je handler moet dus veilig twee keer kunnen draaien.

class StripeWebhooksController < ActionController::API
  def create
    event = Stripe::Webhook.construct_event(
      request.body.read, request.headers["Stripe-Signature"], endpoint_secret
    )
    Billing::WebhookHandler.new(event).process
    head :ok
  rescue JSON::ParserError, Stripe::SignatureVerificationError
    head :bad_request
  end

  private

  def endpoint_secret = Rails.application.credentials.dig(:stripe, :webhook_secret)
end

module Billing
  class WebhookHandler
    def initialize(event)
      @event = event
    end

    # BillingEvent has a unique index on stripe_event_id, so a redelivery is a no-op.
    def process
      record = BillingEvent.find_by(stripe_event_id: @event.id)
      record ||= begin
        BillingEvent.create!(stripe_event_id: @event.id, event_type: @event.type)
      rescue ActiveRecord::RecordNotUnique
        BillingEvent.find_by!(stripe_event_id: @event.id)
      end
      return record unless record.pending?

      case @event.type
      when "checkout.session.completed" then grant_purchased_pack
      when "invoice.paid"               then renew_allowance
      end
      record.mark_processed!
    rescue StandardError => e
      record&.mark_failed!(e)
      raise # answer 5xx so Stripe retries the event
    end
  end
end

Nog twee regels. Gebruik idempotency keys als je server objecten in Stripe aanmaakt, zodat een herhaald verzoek geen tweede checkout of betaling oplevert. En wijzig saldi en statussen onder een row lock, binnen dezelfde transactie die het event vastlegt.

Van betaling naar saldo

Een aanvulbundel is een losse Stripe Checkout-sessie in payment-modus. In de metadata van de sessie zetten we de organisatie en de bundel, zodat de webhook precies weet wat er toegekend moet worden, en bij de aankoop slaan we het id van de Checkout-sessie op. Dat id is de tweede bewaking tegen dubbel toekennen.

def handle_checkout_completed
  session = @event.data.object
  return unless session.mode == "payment"
  return if ImagePackPurchase.exists?(stripe_checkout_session_id: session.id) # granted already

  organization = Organization.find(session.metadata["organization_id"])
  pack = ImagePack.find(session.metadata["image_pack_id"])

  ExtraImages.grant!(organization,
                     images: pack.image_count,
                     image_pack: pack,
                     validity_months: pack.validity_months,
                     stripe_checkout_session_id: session.id,
                     stripe_payment_intent_id: session.payment_intent)
end

Ken toe op basis van de webhook, niet op de bedankpagina waar de klant na het betalen landt. Die pagina is een mooi moment om bedankt te zeggen, maar mensen sluiten tabbladen, terwijl Stripe de webhook blijft aanbieden tot je server hem bevestigt. Stripe stuurt ook checkout.session.expired als een Checkout-sessie verloopt zonder betaling (standaard na 24 uur), een handig signaal dat iemand een aankoop liet liggen.

Valkuilen waar we je voor waarschuwen

  • Workflows dubbel tellen. Draait één actie meerdere modellen, reken dan de losse stappen af of het totaal, nooit allebei. In Postcrest toont een workflow een totaal ter informatie, en tellen alleen de onderliggende generaties mee.
  • Naar beneden afronden. Breuken tellen op over duizenden runs. Rond elke run naar boven af op een hele credit.
  • Onduidelijke vervaldata. Verlopen credits, laat dan zien wanneer, en verbruik eerst wat het eerst verloopt.
  • Misbruik van proefperiodes. Gratis verbruik trekt mensen die zich steeds opnieuw aanmelden. Postcrest werkt met een betaalde proefperiode met kaartcontrole, een risicoscore en een register van één proefperiode per persoon.
  • Prijzen die afdrijven van kosten. Modelprijzen veranderen. Houd kosten op één plek bij (de kostenregels), zodat een prijswijziging één regel code is.
  • Onzichtbare saldi. Klanten moeten kunnen zien wat ze hebben, wat een actie kost en wat ze gebruikt hebben, zonder een factuur te openen.

Wat er in Stripe draait

Opvallend weinig van deze logica zit in Stripe zelf, en dat is bewust. Stripe doet waar het sterk in is: Checkout voor abonnementen en losse bundels, het klantportaal voor kaartwijzigingen en opzeggingen, Stripe Tax en btw-nummers, facturen, terugbetalingen en betwiste betalingen. Salestreak kiest euro of dollar op basis van het land van de bezoeker. Alles wat bepaalt wat een klant mag, zit in de app, naast de taken die het gebruiken.

Plan je een SaaS met usage-based pricing, ontwerp dit deel dan als eerste, niet als laatste. Het hoort bij hoe we SaaS ontwikkelen en Stripe koppelen.

Veelgestelde vragen

Moet ik de usage-based billing van Stripe gebruiken of een eigen creditgrootboek?

Stripe biedt zelf usage-based billing, inclusief vooraf betaalde credits, en dat werkt goed als verbruik vooral gefactureerd moet worden. Houd een eigen grootboek bij als je app vóór elke taak moet beslissen of die mag draaien, als de kosten van een actie in je app worden berekend, of als je verbruik in je eigen interface wilt tonen. Onze producten houden het grootboek in de app en laten Stripe de betalingen afhandelen.

Hoe voorkom ik dat klanten betalen voor mislukte AI-generaties?

Tel verbruik alleen op basis van geslaagde taken, of boek automatisch terug als een taak mislukt. Markeer ook taken die blijven hangen als mislukt, zodat ze niet voor altijd afgerekend blijven.

Moeten credits verlopen?

Dat is een productkeuze. Een vervaldatum houdt saldi actueel als je prijzen of modellen veranderen. Laten credits verlopen, vertel dat dan bij de aankoop, toon de datum en verbruik de oudste eerst.

Hoe ga ik om met dubbele Stripe-webhooks?

Sla elk event-id op met een unieke index voordat je het verwerkt, sla events over die al verwerkt zijn, en antwoord met een fout als de verwerking mislukt, zodat Stripe het opnieuw probeert.

Kunnen jullie usage-based billing voor ons product bouwen?

Ja. We bouwden creditgrootboeken, tegoeden en aanvulbundels op Stripe voor onze eigen producten. Lees meer over onze SaaS-ontwikkeling.

Usage-based pricing in je product?

Vertel wat je product doet en hoe je wilt afrekenen. Dan vertellen we welk model past en wat ervoor nodig is om het goed te bouwen.

martin@balk.dev

Je hoort meestal binnen één werkdag van ons.

Handig om te noemen

  • Wat je wilt bouwen, in een paar zinnen
  • Wie het gaat gebruiken
  • Een eventuele deadline of lanceerdatum
  • Systemen en tools waar het mee moet samenwerken