Op deze pagina
- Credits, meten per eenheid of tegoeden?
- Houd het grootboek in je eigen database bij
- Prijs elke actie met kostenregels
- Schrijf af van saldi onder een lock
- Reken nooit af voor mislukt werk
- Verwerk elke Stripe-webhook precies één keer
- Van betaling naar saldo
- Valkuilen waar we je voor waarschuwen
- 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 |
|---|---|---|---|
| Credits | Klanten krijgen of kopen een saldo; elke actie kost een aantal credits | Veel acties met heel verschillende kosten, zoals beeld, video en stem genereren | Credits voelen abstract, dus toon de kosten van elke actie voordat die start |
| Tegoeden | Een abonnement bevat een aantal eenheden per periode, met bundels voor extra eenheden | Eén hoofdeenheid die klanten snappen, zoals beelden per woning of producten per maand | Eenheden met een ander gewicht (een 2K-beeld telt als twee) vragen om duidelijke uitleg |
| Meten per eenheid | Verbruik wordt aan Stripe gemeld en achteraf gefactureerd | Producten met een gelijkmatige, voorspelbare eenheid, zoals infrastructuur | Klanten 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.