Foundation

The Credit Metering Playbook

A credit ledger, atomic spend RPC, refund-on-failure, and cost analytics that hold up.

CREDIT-METERING-PLAYBOOK.md · 13 sections · 2,547 words · 20 KB · markdown

If your app charges per output — a render, a generation, an enrichment — this is the metering layer. An append-only ledger, an atomic spend RPC that can't double-charge under concurrency, automatic refunds when a provider call fails, and the admin views that tell you whether your pricing is actually profitable.

What's inside

//An append-only credit ledger with a balance view
//An atomic spend RPC (row-locked, race-safe)
//Refund-on-failure wiring for every provider call
//A pricing matrix table: provider cost + infra cost + margin → credits charged
//Daily quota enforcement separate from balance
//Cost analytics views for real-dollar cost vs credits spent

When to use it

Week 3, only if the app charges per-output.

Build these first

App Infrastructure, Stripe Billing

Straight from the file

Seed credit_pricing with on conflict (format_key) do update set that refreshes metadata only — never blow away admin cost overrides:

Table of contents

0. Use this spec
1. Architecture
2. Schema
3. Pricing table seed
4. Atomic spend RPC
5. Server spend helper + pre-spend validation
6. Refund-on-failure (worker pattern)
7. Beta auto-refill + founding tier
8. Daily quota gate (optional)
9. Cost analytics views
10. Audit-orphan-charges cron (safety net)
11. Common pitfalls
12. Kickoff prompt

How to run it

Drop CREDIT-METERING-PLAYBOOK.md into your repo, then tell Claude Code: “Read CREDIT-METERING-PLAYBOOK.md and implement it in this codebase.” It's written for an agent to execute end to end. Search the file for angle-bracket placeholders and swap in your own project names, domains, and keys before the first run.

↓ Download the playbook

More foundation playbooks

S-tier

← All 28 Claude templates

The Credit Metering Playbook

App Infrastructure

Auth & Onboarding

Stripe Billing