Credits

Every account, and every team, has two credit buckets. Subscription credits reset on each grant and disappear when the subscription ends. Purchased credits never expire. A spend takes from the subscription bucket first. Every change to a balance writes one row to credit_transactions in the same transaction, so the ledger always explains the balance.

Import from @/lib/credits, not from ledger.ts directly: the facade's spendCredits settles any due yearly grant before it spends.

The two buckets

Personal balances live in credit_balances (one row per user). Team balances live in organization_credit_balances (one row per organization), with the same two columns.

Balances never go below zero. Clawbacks (refunds, negative adjustments) stop at zero.

Spending credits

From a feature the user triggers, call the Server Action:

import { consumeCredits } from '@/actions/credits'

const result = await consumeCredits({ amount: 10, note: 'Image generation' })
if (!result.success) {
  // result.customCode === 'INSUFFICIENT_CREDITS' when the balance is short
} else {
  const { txId, totalCredits } = result.data // keep txId if the task can still fail
}

consumeCredits requires a signed-in user, a positive integer amount and a note. It spends from the active workspace: the team pool in a team workspace, the personal buckets otherwise.

From server code (a route handler, a webhook), call the facade directly:

import { spendCredits, InsufficientCreditsError } from '@/lib/credits'

const { txId, buckets, spentFromSubscription, spentFromPurchased } = await spendCredits({
  userId,
  organizationId, // optional: spend from this team's pool
  amount: 10,
  note: 'Video generation',
})

It throws InsufficientCreditsError when the total is short; nothing is taken in that case. The demo generation routes under app/api/ai-demo/ leave charging as a TODO [Credits] comment; the add-tool-page skill wires it for a real tool. A worked example of spend and refund is at /dashboard/credit-usage-example.

Refunding a failed task

import { refundSpentCredits } from '@/lib/credits'

await refundSpentCredits({ userId, spendTxId: txId, note: 'Generation failed' })

The refund returns the exact split the usage row recorded, to the pool and buckets it came from. The column refunded_transaction_id on the ledger is unique, so a spend can be refunded once; a second call returns the current balance and writes nothing.

refundSpentCredits is deliberately not a Server Action. Call it only from trusted server code that knows the task failed; a refund the browser could trigger would make every task free.

Ledger functions

All of these are exported from @/lib/credits. Each takes an optional transaction handle as its last argument so a caller can bundle the balance change with its own writes. Each takes an optional organizationId; when it is set, the team pool is changed and userId records the member who acted.

Never call the grant functions from feature code. Paid credits come from the fulfillment core (Payments), which grants them only once money has settled.

A subscription reset writes two rows: the unused credits expiring, then the full grant. The grant row therefore always shows the plan's full amount, not a net difference.

Read functions: getUserCredits(userId), getOrganizationCredits(organizationId), getUserBillingSummary(userId), getOrganizationBillingSummary(organizationId) and hasEntitledSubscription(userId). The balance reads settle any due yearly grant first. ENTITLED_SUBSCRIPTION_STATUSES (active, trialing, past_due, unpaid) is the one definition of "currently subscribed" used across the code.

The signup gift

config/credits.ts sets signupBonusCredits (30 by default; 0 turns it off). The user.create.after hook in lib/auth/index.ts calls grantSignupRewards (lib/auth/signup-rewards.ts), which asks lib/signup-gift-gate first:

• The gate counts signups per source IP and per device fingerprint in Redis over windowDays (30). Past perIp (3) or perDevice (2), the account is still created but gets no gift, a warning is logged and Discord gets notifySignupGiftWithheld.
• Without Redis, without the signals, or on a Redis error, the gift is granted. The gate never fails closed.
• The ledger grants the gift at most once per user, checked inside the same transaction.

Yearly plans: the monthly drip

A yearly subscription is charged once a year but grants monthlyCredits month by month:

1. The yearly payment grants month one at once (a reset to monthlyCredits) and sets remaining_grants = 11 and next_grant_at on the subscriptions row.
2. Each later grant is due at the period start plus k months, clamped to the end of shorter months (addMonthsClamped: bought on the 31st, grants land on 2/28, 3/31, 4/30 …).
3. settleDripForSubscription locks the row, checks again, resets the bucket and moves the schedule. Several overdue months collapse into one reset.
4. Only active and trialing subscriptions receive drip grants. Ending, refunding or cancelling sets remaining_grants = 0.

Two triggers call that one function:

The lazy path means a subscriber can spend a grant the second it is due, even if the cron is not running. The cron is still needed so balances and the ledger are current for users who are not active.

The cron route

app/api/cron/credits/route.ts:

• POST with Authorization: Bearer $CRON_SECRET runs one tick and answers { ok, at, drip, renewals, pendingCaptures }.
• GET with the same header runs the same tick (Cloudflare's scheduled handler and Vercel Cron only send GET). GET without it answers { ok: true, status: 'healthy' } and does nothing.
• A tick does three things: settle due drip grants (up to 100), reconcile overdue renewals (up to 20), reconcile pending PayPal captures (up to 20). Backlogs drain over the following ticks.
• It is designed to run every minute. There is no lock between ticks; overlapping ticks are safe because each grant re-checks under a row lock.
• A tick whose rows failed still answers 200; the next tick retries them.

The cron is not scheduled in the repo by default. Add it when the product sells subscriptions or uses PayPal: on Cloudflare in triggers.crons in wrangler.jsonc plus the CRONS table in cloudflare/middleware.ts, on Vercel in vercel.json. The deploy skills cover both (Cloudflare, Vercel).

Team pools

A team plan (audience: 'team' in config/pricing.ts) bills an organization. Its grants land in organization_credit_balances; the subscription row carries organization_id.

• A member working in the team workspace spends from the pool (consumeCredits reads the active workspace through getWorkspaceContext, which re-checks membership on every call).
• Pool ledger rows carry organization_id and the acting member's user_id.
• Credit packs cannot be bought from a team workspace; the only money into a pool is a team subscription.
• getTeamOverview and getTeamCreditHistory in actions/team/ serve the team page.

Admin adjustments

Every admin action checks isAdmin(), which reads the fresh session, so a demoted admin is cut off at once. The admin actions adjust personal buckets only; they do not take an organizationId.

The credit_transactions table

Defined in lib/db/schema.ts. Rows are only ever inserted.

The user-facing history (getMyCreditHistory) shows personal rows only and hides subscription_cycle_expire bookkeeping rows.

When it fails