AI Credits & Billing Reference

This is the deep reference for DND.chat's AI-credit system: the three credit packs and their prices, exactly which features spend credits and how many, the balance and checkout APIs, and how credits are granted today. The short version is the one to keep in mind: nothing is live-billed during beta. Core campaign chat and auditable dice are always free, and even the metered LLM features run as a no-op while billing is switched off.

For the bigger picture of tiers and what a single membership covers, start at One Membership, Every Site.

Credit packs

AI credits are sold in three packs. These are the verbatim packs defined in DND.chat's billing code; they appear in the AI credits card on the pricing page with a Coming soon tag and no buy button wired up.

A small naming gotcha for anyone reading the API: the pack id for Table night is table, not table-night. The full set of ids is starter, table, campaign.

What actually debits credits

Only LLM features meter against credits, and only through one server-side helper, consumeCredits. There are exactly three sinks, and one of them is not wired up yet.

A few honest details:

• Color commentary debits 1 credit per line, but only if the model actually returns a line that differs from the deterministic template. If narration falls back to the free template, it costs nothing.
• Session recap charges RECAP_CREDIT_COST = 50 credits, and only when the model successfully returns prose. The structured-markdown recap fallback is free, and the recap endpoint is DM-only (a non-DM gets a 403).
• Autopilot DM turns are governed by turn caps (rails), not credits — there is no per-turn credit price defined in code today.

Core chat messages and auditable dice are never gated and never debit credits. As the AI-credits tier itself puts it: Never required for core chat or dice.

Nothing is charged in beta

Even the three sinks above don't reduce a balance right now. consumeCredits checks the platform flag ai_credits.enabled; when that flag is off — the beta default — it returns { ok: true } without deducting anything. So an LLM feature succeeds, the work runs, and your balance is untouched.

// consumeCredits while ai_credits.enabled is false (beta):
{ "ok": true }   // LLM call succeeds, balance unchanged

When the flag is on, consumeCredits reads user_credit_balances, refuses (ok: false) if the balance is below the cost, and otherwise debits and returns the remaining balance. None of that runs today.

Balance & checkout APIs

Reading a balance

GET /api/billing/balance (auth required) returns the signed-in user's balance plus two status flags:

{
  "balance": 0,
  "billingEnabled": false,
  "stripeConfigured": false
}

balance comes from the per-user ledger, billingEnabled reflects the ai_credits.enabled flag, and stripeConfigured is true only when STRIPE_SECRET_KEY is set.

Checkout is a stub

POST /api/billing/checkout accepts { packId } (defaulting to starter) and calls createCreditCheckout. It always returns a stub today — there is no live Checkout URL and no webhook handler:

• Without STRIPE_SECRET_KEY, it returns a message telling you to set the key or ask an admin to adjust your balance.
• Even with the key set, it still stubs, because the stripe npm package isn't installed (the message literally says to run npm install stripe and wire it up).

The success/cancel URLs are already reserved (/pricing?checkout=success and /pricing?checkout=cancel), but no checkout session is ever created.

How credits are granted today

Because checkout is a stub, the only way credits change hands right now is an admin top-up. A platform admin opens /admin/credits and uses the per-user form:

1. Sign in as a platform admin and open /admin/credits.
2. Enter a user's auth UUID and click Check balance to read their current balance.
3. Enter an amount under Admin top-up (per user) and click Top up to grant credits.

That hits POST /api/admin/credits with { userId, amount, mode } — add is the default, set overwrites — and the grant is logged as a credits_top_up audit action. The admin page also surfaces Stripe status (configured / stub), Billing enabled (showing No (beta) today), and the default balance for new users.

Data model

The whole system rests on two pieces of storage:

• platform_settings key ai_credits holds { enabled, default_balance } — the master switch and the starting balance new users are seeded with.
• user_credit_balances is the per-user ledger (user_id, balance, updated_at). New users are seeded with default_balance on first read; if the table is missing entirely, a balance read returns 0 rather than erroring.

Don't confuse these with billing

The word "credits" and the word "usage" show up elsewhere in the family and mean different things. Two false positives worth flagging:

• DNDCards card "credits" are source attribution (Humblewood, Kobold Press Tome of Beasts, and so on) printed on card backs — not AI billing. See Cards & the Shared Compendium.
• DNDCards /admin/usage tracks the operator's raw OpenAI spend in USD across AI generations. That's internal cost telemetry, not your credit balance.

Neither is the user-facing billing system described on this page.

What we can't tell you yet

A few things are genuinely undefined in the code, so we won't guess:

• The Pro subscription price is literally TBD.
• The per-turn credit cost of an autopilot DM scene isn't set — autopilot is turn-capped, not yet credit-metered.
• The default starting balance for new users is a database value, not a hardcoded number.
• There is no Stripe webhook / fulfilment path yet, so how a real purchase would grant credits isn't defined.

Until any of that lands, treat everything as free. For where credits sit within the tier model, see One Membership, Every Site; for the LLM features that will eventually meter, see DND.chat — The AI-DM Tavern and the FAQ.