COMPARISONS/ARCHITECTURE COMPARISON · BUILD VS. DROP-IN

CreditKit vs. Building a Custom Postgres Credit Ledger

Adding a users.credits integer column takes 10 minutes—until you add expiring monthly subscriptions alongside non-expiring packs, parallel double-spend races, upstream 5xx timeouts, mid-cycle upgrades, partial Stripe refunds, and spoof-proof cross-device wallet sync.

Build a custom Postgres ledger in-house when:

  • Your billing logic is a single non-expiring integer counter with no recurring rollover caps, no promo lots, and no exit-intent recovery flows.
  • You already have dedicated billing engineers maintaining custom checkout modals, wallet receipt drawers, dunning banners, and Stripe webhook replay queues.
  • Regulatory or data-residency rules prohibit calling an external credit ledger API from your backend.

Drop in CreditKit instead of building from scratch when:

  • You want to combine expiring subscription allowances (monthly/annual with rollover caps) and permanent one-time top-up packs without burning the wrong bucket first.
  • Your actions call external LLM, media, or scraping APIs that occasionally time out or 502, and you want automatic 2-phase credit restoration.
  • You want production-tested handling for Stripe webhook races, mid-cycle subscription upgrade deltas, dunning, and proportional partial refund clawbacks.
  • You would rather ship your core product today than spend 2–4 weeks building pricing modals, balance pills, receipt drawers, and mobile checkout sheets.

Side-by-Side Architectural Breakdown

CapabilityCreditKit + Your Stripe AccountCustom DIY Postgres Ledger
Expiring + permanent creditsImmutable credit_lots table (ORDER BY expires_at ASC NULLS LAST)Single integer column breaks; requires full multi-lot ledger schema
Parallel double-spend protectionRow-level transactional locking + Idempotency-Key replay cacheNaive UPDATE credits = credits - 1 races under concurrent requests
Upstream 5xx / timeout refundsOne-line withCrashProofHold() restores exact source lots & expiriesMust build pending_holds table, lot-split tracking & stale-hold reaper
Subscription lifecycle & webhooksHandles renewals, 2x rollover caps, upgrade deltas, dunning & clawbacksMust reconcile out-of-order checkout.session & invoice.paid webhooks
Starter quota anti-farmingBound to signed-in userId + HMAC stamp + 24h project circuit-breaker capMust build per-account starter grant tracking & daily spend circuit breakers
Web & mobile checkout UIShadow DOM pill (floating or custom navbar), paywall, exit offer, wallet drawer & /p/[publicKey]Must design, theme, and maintain custom React + mobile webviews
Unit economics & conversion telemetryPer-action 5xx breakdown, paywall recovery funnel & A/B split testingRequires custom analytics instrumentation and SQL reporting views

Key Engineering Tradeoffs

1. Why a Single users.credits Integer Column Breaks in Week Two

The moment a subscriber has 200 monthly credits expiring on Friday and buys a 500-credit permanent pack on Tuesday, a single integer column (700) loses track of which credits expire on Friday. And if an upstream job fails 8 seconds after deducting 5 credits—3 from the expiring monthly lot and 2 from the permanent pack—a simple +5 increment corrupts expiration dates. CreditKit tracks every grant as an immutable lot and records per-lot hold allocations so refunds restore exact expiration timestamps.

2. Stripe Webhook Ordering, Upgrade Deltas & Partial Refund Clawbacks

Real production billing edge cases live in webhook corner cases: checkout.session.completed arriving simultaneously with invoice.paid, mid-cycle upgrades from a 500-credit plan to a 2,000-credit plan (granting the +1,500 delta without resetting permanent packs), scheduled period-end downgrades, payment-failure dunning, chargeback freezes, and proportional clawbacks when support issues a 50% partial Stripe refund.

3. Zero-CSS-Collision Paywall & Wallet Surfaces Included

Backend ledger tables are only half the work. Users expect a live credit badge, a transparent receipt history showing why credits changed, promo code redemption, saved-card one-click refills, and a mobile-friendly Apple Pay / Stripe Link sheet. CreditKit ships all five surfaces inside an isolated Shadow DOM container plus typed React hooks.

Frequently Asked Questions

How does CreditKit prevent parallel requests from double-spending the last credit?

Every /api/v1/consume and /api/v1/holds transaction locks the wallet and eligible non-expired credit lots inside an atomic PostgreSQL transaction, deducting across lots in strict FIFO expiration order and rejecting concurrent overflow requests with HTTP 402.

What happens if my server crashes while a 2-phase credit hold is open?

If your route handler throws or catches an upstream 5xx error, CreditKitClient.withCrashProofHold immediately releases the hold and restores the exact lots. Any orphaned holds that never settle are also safely reconciled.

Can I start on CreditKit for $0 while validating my app?

Yes. The Starter plan is $0/month with $0 fees on free starter credits and sandbox (pk_test_...) transactions; you only pay a 5% platform fee when real users buy paid credits (dropping to 2% on Builder and 1% on Studio).

Ready to test prepaid wallets & 2-phase holds in sandbox mode?

Start on Starter for $0/mo, or read CreditKit vs. Stripe Billing Meters.