Stripe ile kullanım bazlı faturalama: pratik bir veri modeli

Gerçekte ne inşa ediyorsunuz (ve neden bozuluyor)

Kullanıma dayalı faturalama basit gibi görünür: müşterinin ne kullandığını ölçün, bir fiyatla çarpın ve dönemin sonunda tahsil edin. Pratikte küçük bir muhasebe sistemi inşa ediyorsunuz. Veri geç geldiğinde, iki kez geldiğinde veya hiç gelmediğinde doğru kalması gerekiyor.

Çoğu hata ödeme ekranında veya panoda olmaz. Ölçüm verisi modelinde olur. “Bu faturada hangi kullanım olayları sayıldı ve neden?” sorusuna emin bir şekilde cevap veremiyorsanız, eninde sonunda fazla fatura keser, eksik fatura keser veya güven kaybedersiniz.

Kullanım faturalaması genellikle öngörülebilir birkaç şekilde bozulur: bir kesinti sonrası olaylar kaybolur, tekrarlar çoğaltma yaratır, geç gelen kayıtlar toplamlar hesaplandıktan sonra ortaya çıkar veya farklı sistemler uyuşmaz ve farkı uzlaşamazsınız.

Stripe fiyatlandırma, faturalar, vergiler ve tahsilatta mükemmeldir. Ancak Stripe, ham kullanımınızı bilmez — onu siz gönderiyorsunuz. Bu da bir kaynak-kararı zorunlu kılar: defter Stripe mı, yoksa Stripe'ın yansıttığı defter sizin veritabanınız mı?

Çoğu ekip için en güvenli ayrım şudur:

• Ham kullanım olayları ve bunların yaşam döngüsü için kaynak otorite veritabanınızdır.
• Stripe ise gerçekten fatura edilen ve ödenen şey için kaynak otoritedir.

Örnek: “API çağrıları”nı takip ediyorsunuz. Her çağrı kararlı bir benzersiz anahtarla bir kullanım olayı üretir. Fatura zamanında yalnızca henüz faturalanmamış uygun olayları toplar, sonra Stripe fatura öğesini oluşturur veya güncellersiniz. İncelemeler veya webhook tekrarları gelirse idempotency kuralları çoğaltmayı zararsız hale getirir.

Tabloları tasarlamadan önce kararlar

Tabloları oluşturmadan önce, faturalamanın ileride açıklanabilir kalmasını sağlayacak tanımları kesinleştirin. Çoğu “esrarengiz fatura hatası” belirsiz kurallardan gelir, kötü SQL'den değil.

Önce ücretlendirdiğiniz birimi belirleyin. Ölçmesi kolay ve tartışılması zor bir şey seçin. “API çağrıları” yeniden denemeler, toplu istekler ve hatalarla karışabilir. “Dakikalar” üst üste binmelerle zorlaşır. “GB” için açık bir temel (GB vs GiB) ve ölçüm yöntemi (ortalama mı, pik mi) gerekir.

Sonra sınırları tanımlayın. Sisteminiz bir olayın hangi pencereye ait olduğunu kesin olarak bilmeli. Kullanım saatlik, günlük, faturalama dönemi bazlı mı yoksa müşteri eylemine göre mi sayılıyor? Müşteri ay ortasında yükseltme yaparsa pencereyi bölüyor musunuz yoksa tüm aya tek fiyat mı uygulanıyor? Bu seçimler olayları nasıl gruplayacağınızı ve toplamları nasıl açıklayacağınızı belirler.

Ayrıca hangi sistemin hangi gerçeğe sahip olacağını kararlaştırın. Stripe ile yaygın bir desen: uygulamanız ham olaylar ve türetilmiş toplamların sahibi olsun, Stripe faturalar ve ödeme durumunun sahibi olsun. Bu yaklaşım geçmişi sessizce değiştirmediğinizde en iyi şekilde çalışır. Düzeltmeleri yeni girdiler olarak kaydedin ve orijinal kaydı saklayın.

Kısa, vazgeçilmez bir liste şunları tutmanıza yardımcı olur:

• İzlenebilirlik: faturalandırılan her birim saklanan olaylara geri izlenebilir olmalı.
• Denetlenebilirlik: aylar sonra “neden bu tahsil edildi?” sorusuna cevap verebilmelisiniz.
• Geri alınabilirlik: hatalar açık düzeltmelerle giderilmeli.
• Idempotency: aynı girdi iki kez sayılmamalı.
• Net sahiplik: her gerçek için tek bir sistem sahibi olmalı (kullanım, fiyatlama, faturalama).

Örnek: “gönderilen mesajlar” için faturalandırıyorsanız, yeniden denemelerin sayılıp sayılmayacağını, başarısız teslimlerin sayılıp sayılmayacağını ve hangi zaman damgasının geçerli olduğunu (istemci zamanı mı sunucu zamanı mı) kararlaştırın. Bunları yazın, sonra olay alanlarına ve doğrulamaya kodlayın, birinin hafızasına bırakmayın.

Kullanım olayları için basit veri modeli

Kullanıma dayalı faturalama, kullanımı muhasebe gibi ele aldığınızda en kolay haline gelir: ham veriler eklemeli olsun, toplamlar türetilmiş olsun. Bu tek tercih çoğu anlaşmazlığı önler çünkü bir sayının nereden geldiğini her zaman açıklayabilirsiniz.

Pratik bir başlangıç beş temel tablo kullanır (isimler değişebilir):

• customer: dahili müşteri id'si, Stripe customer id'si, durum, temel metadata.
• subscription: dahili abonelik id'si, Stripe subscription id'si, beklenen plan/fiyatlar, başlangıç/bitiş zaman damgaları.
• meter: neyi ölçtüğünüz (API çağrıları, kullanıcı sayısı, depolama GB-saat). Kararlı bir meter anahtarı, birim ve nasıl toplandığı (toplam, maksimum, benzersiz) dahil edin.
• usage_event: ölçülen her eylem için bir satır. customer_id, subscription_id (biliniyorsa), meter_id, quantity, occurred_at (olayın gerçekleştiği zaman), received_at (ingest edildiği zaman), source (app, batch import, partner) ve çoğaltma önleme için kararlı bir external key saklayın.
• usage_aggregate: türetilmiş toplamlar; genellikle müşteri + meter + zaman kovası (gün veya saat) ve faturalama dönemi bazında. Toplam miktar ve yeniden hesaplama desteklemek için bir versiyon veya last_event_received_at saklayın.

usage_event'i değiştirilemez (immutable) tutun. Sonradan bir hata keşfederseniz, geçmişi düzenlemek yerine telafi edici bir olay yazın (örneğin, iptal için -3 seat).

Denetimler ve ihtilaflar için ham olayları saklayın. Eğer sonsuza kadar saklayamıyorsanız, en az faturalama geri dönüş penceresi artı iade/itiraz penceresi kadar tutun.

Türetilmiş toplamları ayrı tutun. Aggregate tablolar faturalar ve panolar için hızlıdır, ama atılabilir olmalılar. Her zaman usage_event'lerden usage_aggregate'ı yeniden oluşturabilmelisiniz, hatta bir backfill sonrası bile.

Idempotency ve olay yaşam döngüsü durumları

Kullanım verisi gürültülüdür. İstemciler istekleri tekrarlar, kuyruklar çoğaltılmış teslimatlar yapar ve Stripe webhook'ları sıra dışı gelebilir. Veritabanınız “bu kullanım olayı zaten sayıldı” diyemiyorsa sonunda iki kez faturalandırırsınız.

Her kullanım olayına kararlı, deterministik bir event_id verin ve üzerinde benzersizlik zorunluluğu uygulayın. Yalnızca otomatik artan id'ye güvenmeyin. İyi bir event_id iş eyleminden türetilir, örneğin customer_id + meter + source_record_id (veya customer_id + meter + timestamp_bucket + sequence). Aynı eylem tekrar gönderilirse aynı event_id oluşur ve insert güvenli bir no-op olur.

Idempotency sadece herkese açık API yolunu kapsamalı, tüm ingest yollarını kapsamalı. SDK çağrıları, toplu içe aktarımlar, worker işleri ve webhook işlemcileri hepsi tekrar edilebilir. Bir kural kullanın: giriş tekrar edilebiliyorsa, veritabanında saklanan ve toplamlar değişmeden önce kontrol edilen bir idempotency anahtarına sahip olmalı.

Basit bir yaşam döngüsü durum modeli tekrarları güvenli hale getirir ve destek işlemlerini kolaylaştırır. Bunu açık tutun ve bir şey başarısız olduğunda nedeni saklayın:

• received: saklandı, henüz kontrol edilmedi
• validated: şema, müşteri, meter ve zaman-pencere kurallarını geçti
• posted: faturalama dönem toplamlarına sayıldı
• rejected: kalıcı olarak yok sayıldı (bir neden kodu ile)

Örnek: worker'ınız doğruladıktan sonra çöküyor ama post etmeden önce. Yeniden denemede aynı event_id'yi validated durumda bulur, ardından ikinci kez saymadan posted durumuna geçirir.

Stripe webhook'ları için aynı deseni kullanın: Stripe event.id'yi depolayın ve yalnızca bir kez işlendi olarak işaretleyin, böylece çoğaltılmış teslimatlar zararsız olur.

Adım adım: ölçüm olaylarını baştan sona ingest etmek

Her ölçüm olayını para gibi ele alın: doğrulayın, orijinalini saklayın, sonra toplamları kaynaktan türetin. Bu, sistemler tekrar denediğinde veya veri geç geldiğinde faturalamayı öngörülebilir tutar.

Güvenilir bir ingest akışı

Her gelen olayı toplamlara dokunmadan önce doğrulayın. En azından şu alanları zorunlu kılın: kararlı bir müşteri tanımlayıcısı, bir meter adı, sayısal bir miktar, bir zaman damgası ve idempotency için benzersiz bir olay anahtarı.

Ham olayı önce yazın, toplamları daha sonra hesaplamayı planlasanız bile. O ham kayıt, yeniden işleme, denetim ve hataları düzeltme için kullanacağınız kaynaktır.

Güvenilir bir akış şöyle görünür:

• Olayı kabul edin, zorunlu alanları doğrulayın, birimleri normalize edin (ör. saniye vs dakika).
• Event key'i benzersiz kısıtlama olarak kullanarak ham usage_event satırını insert edin.
• Olay miktarını uygulayarak günlük veya faturalama dönemi kovasına aggregate edin.
• Stripe'a kullanım raporlayorsanız, gönderdiğiniz şeyi (meter, miktar, dönem ve Stripe yanıt id'leri) kaydedin.
• Anomali (reddedilen olaylar, birim dönüşümleri, geç gelen veriler) kayıtlarını denetimler için loglayın.

Aggregation'ı tekrarlanabilir tutun. Yaygın bir yöntem: ham olayı tek bir işlemde insert edip ardından bucket güncellemesi için bir iş kuyruğuna atmak. İş iki kez çalışırsa ham olayın zaten uygulandığını tespit etmelidir.

Bir müşteri neden 12.430 API çağrısı faturalandığını sorduğunda, o faturalama penceresine dahil edilen ham olayların tam listesini gösterebilmelisiniz.

Stripe webhook'ları ile veritabanınızı uzlaştırma

Webhook'lar Stripe'ın gerçekten ne yaptığının makbuzudur. Uygulamanız taslaklar oluşturabilir ve kullanım gönderebilir, ama fatura durumu yalnızca Stripe onayladığında gerçek olur.

Çoğu ekip faturalama sonuçlarını etkileyen küçük bir webhook setine odaklanır:

• invoice.created, invoice.finalized, invoice.paid, invoice.payment_failed
• customer.subscription.created, customer.subscription.updated, customer.subscription.deleted
• checkout.session.completed (Checkout ile abonelik başlatıyorsanız)

Aldığınız her webhook'u saklayın. Ham payload ile birlikte geldiğinde gözlemlediklerinizi de saklayın: Stripe event.id, event.created, imza doğrulama sonucu ve sunucunuzun aldığı zaman damgası. Bu geçmiş, bir uyuşmazlığı debug ederken veya "neden ücretlendirildim?" sorusuna cevap verirken önemlidir.

Sağlam, idempotent bir mutabakat deseni şöyle çalışır:

1. stripe_webhook_events tablosuna event_id üzerinde benzersiz kısıtlama ile webhook'u insert edin.
2. Eğer insert başarısız olursa, bu bir retry'dir. Durun.
3. İmzayı doğrulayın ve başarılı/başarısız kaydedin.
4. Olayı Stripe ID'leri (customer, subscription, invoice) ile dahili kayıtlara bakarak işleyin.
5. Durum değişikliğini yalnızca ileri taşıyorsa uygulayın.

Sıradışı teslim normaldir. "Maksimum durum kazansın" kuralı ve zaman damgaları kullanın: bir kaydı asla geriye taşımayın.

Örnek: invoice.paid geldiğinde dahili fatura satırınız henüz yoksa, "Stripe'dan görüldü" olarak işaretlenmiş bir satır oluşturun, sonra doğru hesaba Stripe customer ID'si ile ilişkilendirin. Bu, çift işleme olmadan defterinizi tutarlı kılar.

Kullanım toplamlarından fatura satırlarına

Ham kullanımı fatura satırlarına çevirmek çoğunlukla zamanlama ve sınırlarla ilgilidir. Gerçek zamanlı toplamlara ihtiyaç duyup duymadığınızı (panolar, harcama uyarıları) veya yalnızca fatura zamanında mı (faturalar) gerektiğini kararlaştırın. Birçok ekip her iki ihtiyacı da karşılar: olayları sürekli yazar, fatura hazır toplamları zamanlanmış bir işte hesaplar.

Kullanım pencerenizi Stripe'ın faturalama dönemiyle hizalayın. Takvim aylarını tahmin etmeyin. Abonelik öğesinin mevcut faturalama dönemi başlangıç ve bitişini kullanın, sonra yalnızca o pencereye düşen olayları toplayın. Zaman damgalarını UTC'de saklayın ve faturalama penceresini de UTC yapın.

Geçmişi değiştirilemez tutun. Sonradan bir hata bulursanız eski olayları düzenlemeyin ya da önceki toplamları yeniden yazmayın. Hangi pencereye işaret ettiğini belirten bir düzeltme kaydı oluşturun ve miktarı ekleyip çıkarın. Böylece denetlenmesi ve açıklanması daha kolay olur.

Plan değişiklikleri ve proration izlenebilirliğin sıkça kaybolduğu yerlerdir. Müşteri döngü ortasında plan değiştirirse, her fiyatın aktif olduğu aralığa uyan alt-pencerelere bölün. Faturanız iki kullanım satırı (veya bir satır artı düzeltme) içerebilir; her biri belirli bir fiyat ve zaman aralığına işaret etmeli.

Pratik bir akış:

• Fatura penceresini Stripe'dan period start ve end ile çekin.
• O pencere ve fiyata uygun kullanım olaylarını toplayın.
• Kullanım toplamından ve düzeltmelerden fatura satırlarını oluşturun.
• Sayıları daha sonra yeniden üretebilmek için bir hesaplama çalıştırma id'si saklayın.

Backfill'ler ve geç gelen verilerle güveni bozmadan başa çıkma

Geç gelen kullanım verisi normaldir. Cihazlar çevrimdışına çıkar, toplu işler gecikir, partnerler dosyaları yeniden gönderir ve log'lar bir kesintiden sonra tekrar oynatılabilir. Anahtar, backfill'leri düzeltme işi olarak ele almak, "sayılara uydurmak" için kullanmamak.

Backfill'lerin nereden gelebileceğini açıkça belirtin (uygulama logları, data warehouse ihracatları, partner sistemleri). Her olayda kaynağı kaydedin ki neden geç geldiğini açıklayabilesiniz.

Backfill yaparken en az iki zaman damgası tutun: kullanımın gerçekleştiği zaman (faturalandırmak istediğiniz zaman) ve içeri alındığı zaman. Olayı backfill olarak etiketleyin, ama geçmişi üzerine yazmayın.

Toplamlara bugünkü aggregate tablosuna delta uygulamaktan ziyade ham olaylardan yeniden oluşturmayı tercih edin. Replay'ler hatalardan tahmin yapmadan kurtulmanızı sağlar. Pipeline idempotent ise bir günü, bir haftayı veya tam bir faturalama dönemini yeniden çalıştırıp aynı toplamları elde edebilirsiniz.

Bir fatura zaten varsa düzeltmeler için net bir politika izleyin:

• Fatura kesinleşmemişse, kesinleştirmeden önce yeniden hesaplayın ve toplamları güncelleyin.
• Kesinleşmiş ve eksik faturalandıysa, açık bir açıklama ile ek fatura oluşturun (veya yeni bir fatura öğesi ekleyin).
• Kesinleşmiş ve fazla faturalandıysa, orijinal faturaya referans vererek kredi notu (credit note) çıkarın.
• Düzeltmeden kaçınmak için kullanımın farklı bir döneme taşınmasına izin vermeyin.
• Düzeltme nedeni için kısa bir açıklama saklayın (partner yeniden gönderimi, gecikmiş log teslimi, hata düzeltmesi).

Örnek: partner 28-29 Ocak için eksik olayları 3 Şubat'ta gönderirse, onları occurred_at Ocak, ingested_at Şubat ve kaynak “partner” ile insert edin. Ocak faturası zaten ödendiyse eksik birimlere küçük bir ek fatura oluşturun ve nedeni mutabakat kaydıyla saklayın.

Çift sayıma neden olan yaygın hatalar

Çift sayım, bir sistemi “bir mesaj geldi”yi “eylem gerçekleşti” olarak kabul ettiğinde olur. Tekrarlar, gecikmiş webhook'lar ve backfill'lerle müşteri eylemi ile işleme ayrımınızı net tutmanız gerekir.

Yaygın suçlular:

• Tekrarların yeni kullanım olarak işlenmesi. Her olay stabil bir eylem id'si (request_id, message_id) taşımıyorsa ve veritabanı benzersizliği zorlamıyorsa iki kez sayarsınız.
• Olay zamanının işlem zamanı ile karıştırılması. İçeri alındığı zamana göre raporlama, geç gelen olayların yanlış döneme düşmesine neden olur ve replay'larda tekrar sayılmalarına yol açar.
• Ham olayların silinmesi veya üzerine yazılması. Sadece akış tabanlı toplam tutuyorsanız ne olduğunu kanıtlayamazsınız ve yeniden işleme toplamları şişirebilir.
• Webhook sırasının varsayılması. Webhook'lar çoğaltılabilir, sıra dışı gelebilir veya kısmi durumları temsil edebilir. Stripe nesne ID'leri ile mutabakat yapın ve "zaten işlendi" gardıyanı tutun.
• İptaller, iadeler ve kredilerin açıkça modellenmemesi. Sadece kullanım ekliyorsanız ve negatif düzeltmeleri kaydetmiyorsanız, düzeltmeleri import ederek ya da yeniden göndererek toplamları yanlış düzeltirsiniz.

Örnek: “10 API çağrısı” kaydedip sonra bir kesinti nedeniyle 2 çağrı için kredi verirseniz; tüm günün kullanımını yeniden gönderip ayrıca krediyi uygularsanız müşteri 18 çağrı görebilir (10 + 10 - 2) yerine doğru olan 8.

Canlıya almadan önce hızlı kontrol listesi

Gerçek müşteriler için kullanım bazlı faturalamayı açmadan önce pahalı faturalama hatalarını önleyecek temel kontrolleri son bir kez gözden geçirin. Çoğu hata "Stripe sorunu" değil; veri sorunlarıdır: çoğaltmalar, eksik günler ve sessiz tekrarlar.

Kısa ve uygulanabilir kontrol listesi:

• Kullanım olaylarında benzersizliği zorlayın (örneğin event_id üzerinde benzersiz kısıtlama) ve tek bir id stratejisine bağlı kalın.
• Aldığınız her webhook'u saklayın, imzasını doğrulayın ve idempotent işleyin.
• Ham kullanımı değiştirilemez tutun. Düzeltmeleri (pozitif veya negatif) kullanın, düzenlemeyin.
• Dahili toplamları (müşteri başına, meter başına, gün başına) Stripe faturalama durumu ile karşılaştıran günlük bir mutabakat işi çalıştırın.
• Boşluklar ve anomaliler için uyarılar ekleyin: eksik günler, negatif toplamlar, ani sıçramalar veya “alınan olaylar” ile “faturalanan olaylar” arasındaki büyük fark.

Basit bir test: bir müşteriyi seçin, son 7 gün için ingest'i yeniden çalıştırın ve toplamların değişmediğini doğrulayın. Değişiyorsa hala idempotency veya backfill sorununuz var demektir.

Örnek senaryo: gerçekçi bir ayın kullanımı ve faturaları

Küçük bir destek ekibi, ele alınan her konuşma için 0,10$ ücret alan bir müşteri portalı kullanıyor. Stripe ile kullanım bazlı faturalama sunuyorlar, ama veri karmaşıklaşınca güven kullanım ile sağlanır.

1 Mart'ta müşteri yeni bir faturalama dönemi başlatır. Bir ajan bir konuşmayı kapattıkça uygulamanız bir kullanım olayı üretir:

• event_id: uygulamanızdan kararlı bir UUID
• customer_id ve subscription_item_id
• quantity: 1 konuşma
• occurred_at: kapanış zamanı
• ingested_at: ilk görüldüğü zaman

3 Mart'ta bir arka plan worker'ı zaman aşımından sonra yeniden dener ve aynı konuşmayı tekrar gönderir. event_id benzersiz olduğu için ikinci insert no-op olur ve toplamlar değişmez.

Ay ortasında Stripe fatura önizlemesi ve daha sonra kesinleşmiş fatura için webhook'lar gönderir. Webhook handler'ınız stripe_event_id, type ve received_at saklar ve veritabanı işlemi commit edildikten sonra ancak işaretler. Webhook iki kez gelirse ikinci teslimat stripe_event_id zaten var olduğu için yoksayılır.

17 Mart için çevrimdışı olan mobil istemciden gelen ve 35 konuşma içeren geç bir batch'i 18 Mart'ta import edersiniz. Bu olayların occurred_at geçmişte olmasına rağmen geçerli sayılır. Sisteminize insert edilir, 17 Mart için günlük toplamlar yeniden hesaplanır ve ekstra kullanım açık faturalama dönemindeyse sonraki faturada yakalanır.

22 Mart'ta bir konuşmanın hatayla iki kez kaydedildiğini ve iki farklı event_id üretildiğini keşfedersiniz. Tarihi silmek yerine quantity = -1 olan bir düzeltme olayı ve nedeni "duplicate detected" yazarak denetim izini korursunuz ve faturadaki değişiklik açıklanabilir olur.

Sonraki adımlar: güvenli bir şekilde uygulayın, izleyin ve yineleyin

Küçük başlayın: bir meter, bir plan, iyi anladığınız bir müşteri segmenti. Hedef basit tutarlılık — sayılarınız aylar boyunca Stripe ile uyuşsun, sürpriz olmasın.

Küçük inşa edin, sonra sertleştirin

Pratik ilk yayılım:

• Bir olay biçimi tanımlayın (ne sayılıyor, hangi birimde, hangi zamanda).
• Her olayı benzersiz bir idempotency anahtarı ve net bir durum ile saklayın.
• Faturaların açıklanabilmesi için günlük (veya saatlik) toplamlara aggregate edin.
• Stripe ile mutabakatı sadece gerçek zamanlı değil, zamanlanmış işler ile de yapın.
• Faturalamadan sonra dönemi kapatılmış sayın ve geç gelen olayları bir düzeltme yoluna yönlendirin.

Kod yazmadan bile güçlü veri bütünlüğü koruyabilirsiniz: idempotency anahtarları için benzersiz kısıtlamalar koyun, müşteri ve abonelik için yabancı anahtarlar zorunlu kılın ve kabul edilmiş ham olayları güncellemekten kaçının.

Sonradan hayatınızı kurtaracak izleme

Erken dönemde basit denetim ekranları ekleyin. İlk kez birisi "neden faturam bu ay daha yüksek?" diye sorduğunda kendilerini amorti ederler. Kullanışlı görünümler: müşteri ve dönem bazında olay arama, dönemlik günlük toplamları görme, webhook işleme durumunu takip etme ve kim/ ne zaman/ neden ile backfill ve düzeltmeleri gözden geçirme.

AppMaster (appmaster.io) ile bunu uyguluyorsanız, model doğal olarak uyar: ham olayları, toplamları ve düzeltmeleri Data Designer'da tanımlayın, sonra idempotent ingest, zamanlanmış aggregation ve webhook mutabakatı için Business Processes kullanın. Hâlâ gerçek bir defter ve denetim izi elde edersiniz, tüm altyapıyı elle yazmadan.

İlk metreniz stabil olduğunda, diğerini ekleyin. Aynı yaşam döngüsü kurallarını, aynı denetim araçlarını ve aynı alışkanlığı koruyun: bir şeyi değiştirin, sonra uçtan uca doğrulayın.