Credits & billing: one currency for every AI action
Mass meters every AI action — a page generation, an image, a render, a token of text — in a single currency: credits. Behind that simple number is an append-only ledger, a key-source-aware cost engine, plan-based monthly allocations, free allowance pools, top-ups, and Stripe billing. This guide explains exactly how a credit is priced, deducted, granted, and refunded, so the number you see is never a mystery.
20 min read · The complete credits & billing guide
What a credit is
One unit of metered usage, pegged to a stable USD value.
A credit is the platform's unit of account for anything that costs money to run — AI text and images, video renders, storage, and other provider-backed operations. Instead of exposing raw token counts and per-provider prices, Mass converts every operation into credits so cost is consistent and predictable across features.
Credits are pegged to a stable USD value (the "USD peg"), so a credit is worth the same whether it's spent on a long-form generation or a batch of images. That peg is also what lets the platform convert a provider's real token cost into the credits a single operation deducts.
- One currency — text, images, renders, and storage all resolve to the same credit unit, so usage is comparable across the whole platform.
- USD-pegged — credits map to a stable dollar value, which is how raw provider cost becomes a credit cost.
- Predictable — you reason about one number, not a matrix of providers, models, and token prices.
- Auditable — every credit that moves is written to a ledger you can read back — nothing is implicit.
The append-only ledger & derived balance
Every credit movement is a row; the balance is always a sum, never a cached guess.
Credits live in an append-only ledger. Every billable event — a render, AI text or image, storage, a top-up, a refund, a promo, or a manual adjustment — appends one immutable row. A balance is never stored as a single mutable field that can drift; it's derived by summing the ledger, so the number is always reconstructable from the history that produced it.
Consumption rows (renders, AI text, AI image, storage) are debits; top-ups, refunds, and promos are credits. Because writes go through a service-role client, background workers and webhook receivers can append rows without a user session — so a render finishing on a worker and a Stripe top-up landing on a webhook both record correctly.
- Immutable rows — each event appends one row with its kind, amount, unit count, unit cost, reason, and reference id — history is never rewritten.
- Balance = SUM — the balance is computed by summing the ledger on read, so it can't silently drift out of sync.
- Debits vs credits — render, render_batch, ai_text, ai_image, and storage are debits; topup, refund, and promo are credits.
- Pre-flight checks — expensive and bulk operations call a balance check first, with the whole batch's estimated cost, so one click is never half-debited.
Why a ledger instead of a counter
A single mutable balance can drift under concurrency or a failed write. An append-only ledger makes the balance auditable and reconstructable — you can always answer 'why is my balance this number' by reading the rows that produced it.
How an operation is priced: the 3-tier markup
Base provider cost → admin markup → platform fee, and who pays depends on whose API key ran it.
The cost of an AI operation starts from the provider's real usage — input and output tokens for an LLM, or units consumed for image, audio, and video models — converted to a base cost via the model's price. On top of that base, two markups can apply: a model-specific markup, and an admin (per-tenant) markup that can be global or set per provider (OpenAI, Anthropic, DeepSeek, fal, Replicate, ElevenLabs).
Crucially, pricing is key-source-aware. When the platform's API key runs the call, the full base cost plus admin and platform markup applies. When a white-label tenant owns the key, the base is zero — they paid the provider directly — so they're charged the admin markup plus the platform fee. When a user brings their own key (BYOK), only the platform fee applies. Legacy "OG partner" lifetime deals deduct nothing. The final credit cost is rounded up so a real operation always costs at least one credit.
- Base cost — provider token or unit usage × the model's price, taken from the model-cost table (with sensible fallbacks).
- Admin markup — a per-tenant margin, global or per-provider, applied on top of base — this is how agencies price their resold credits.
- Platform fee — the platform's cut, applied regardless of key source so even BYOK usage carries a small fee.
- Key-source-aware — platform key = full cost; tenant key (WL) = markup + fee; user key (BYOK) = fee only; OG partner = free.
Plan tiers & pricing
Five tiers, from a free trial allotment to a lifetime Black Label license.
Plans set both feature access and the monthly credit allotment. There are five tiers: Free, Starter ($47/mo), Growth ($97/mo, the "pro" tier), Agency ($297/mo or a $1,497 lifetime, the "partner" tier), and Black Label ($6,997 lifetime, the "enterprise" tier). Each tier unlocks feature flags — custom domains, white-label, sub-accounts, credit markup, BYOK, the reseller program — and numeric caps such as funnels, contacts, email sends, automations, team members, and sub-accounts.
Free and Starter have hard per-day and per-month AI generation caps; Growth lifts most caps toward unlimited; Agency and Black Label use the unlimited limit set. Lifetime Agency and Black Label are BYOK — they bring their own API keys and skip AI credit checks — while the $297/mo Agency subscription does not get BYOK and runs on allocated credits.
- Free — 500 credits that expire in 14 days, 1 funnel, 100 contacts — enough to try the platform end to end.
- Starter — $47/mo — 2,500 credits/mo, 5 funnels, 2,500 contacts, 3 active automations, 25 AI generations/day.
- Growth — $97/mo — 10,000 credits/mo, 25 funnels, 25,000 contacts, unlimited campaigns, 3 custom domains.
- Agency — $297/mo or $1,497 lifetime — sub-accounts, credit markup, white-label; lifetime is BYOK and skips credit checks.
- Black Label — $6,997 lifetime — sell white-label licenses, reseller program, always lifetime + BYOK — no monthly credits needed.
Monthly allocation & the invoice webhook
Paid plans get topped up automatically when Stripe confirms the payment.
Credit allocation is driven by Stripe, not by a clock the platform has to babysit. When an invoice is paid, the Stripe webhook reads the plan's monthly credit amount and grants it to the tenant: it upserts the tenant's credit balance, records the monthly allowance, and writes a transaction row describing the allocation. The same webhook flow handles the initial subscription, renewals, and one-off included-credit grants.
Standard monthly allotments are 2,500 for Starter, 10,000 for Growth, and 25,000 for the Agency subscription. Free gets 500 (expiring in 14 days). Lifetime BYOK tenants — White Label and Black Label — are allocated zero on purpose: they run on their own API keys, so the webhook checks the lifetime-access flag and skips the credit grant rather than handing out credits that would never be spent.
- Driven by invoice.paid — the webhook grants credits when Stripe confirms payment, so allocation and billing can't fall out of step.
- Standard allotments — Starter 2,500 · Growth 10,000 · Agency subscription 25,000 · Free 500 (14-day expiry).
- Idempotent — the webhook checks whether an event was already processed before granting, so a redelivered event won't double-credit.
- BYOK gets zero — lifetime White Label / Black Label tenants are skipped — they pay providers directly with their own keys.
Allowance pools: free credits drawn first
Plan-granted 'free' buckets are spent before the paid balance is ever touched.
On top of the paid balance, a tenant can have allowance pools — buckets of included credits scoped to a product area (for example a pool for a specific channel or feature). When an operation is classified to a product key, the deduction first draws from any matching allowance pool, and only the remainder hits the paid balance. A single click can therefore be partly free and partly paid, transparently.
Allowance pools are provisioned from a tenant's plan tier: each tier has a set of pool templates with a monthly grant and optional rollover. Upgrading a tier tops the pools up immediately so the new, larger grant is spendable right away. The allowance step is closed-on-failure — if the billing tables are briefly unavailable, it returns "nothing drawn" rather than blocking usage, so an outage never silently locks the whole platform.
- Free first — matching allowance is consumed before the paid balance, so included credits are always used up first.
- Product-scoped — each operation is classified to a product key and drawn from the pool that matches it.
- Tier-provisioned — pools come from plan-tier templates with monthly grants and optional rollover; an upgrade tops them up at once.
- Fail-open — if billing tables are unavailable the draw returns zero rather than blocking — usage is never blanket-blocked by an outage.
Top-ups, refunds & promos
Buy more any time, get credited back automatically when an operation fails.
When credits run low, a tenant can purchase a credit package through a Stripe checkout. The purchase is logged as a pending transaction immediately and finalized on the webhook when payment completes, so the ledger reflects the buy the moment Stripe confirms it. Purchased credits don't expire on a monthly cycle the way free-plan credits do — monthly allotments are spent first, then purchased credits.
Refunds are built into the operation flow. AI calls can be wrapped so that if the operation throws after credits were deducted, the deduction is automatically reversed with a refund row — you're not charged for a generation that failed. Promotional credits and manual adjustments are first-class ledger kinds too, so a support grant or a launch promo is recorded the same auditable way as everything else.
- Credit packages — buy more credits via Stripe checkout; the purchase is logged pending and finalized on the webhook.
- Never expire — purchased credits don't lapse monthly — monthly allotment is consumed first, then purchased balance.
- Auto-refund on failure — operations can be wrapped so a failed AI call reverses its own deduction with a refund row.
- Promos & adjustments — promotional grants and manual corrections are explicit ledger kinds, fully auditable.
Limits, alerts, spend caps & dunning
Guardrails that protect both the buyer and the platform from runaway spend.
Each tenant carries credit settings: a daily credit limit, a monthly credit limit, and a maximum balance, plus low and critical thresholds that drive alerts. When usage approaches a threshold the tenant is warned, and when a hard limit is hit the operation is blocked rather than silently overspending. These settings also control whether credit purchasing and alerts are enabled, and how many free credits a new signup receives.
Above the per-tenant limits sit spend caps and dunning. A spend cap can block further usage with a clear message when a configured ceiling is reached, and dunning suspends a tenant whose subscription payment has failed — with the open dunning state resolved automatically when the next invoice is paid. The result is that a stuck card or an unexpected spike degrades gracefully into a clear blocked-state message instead of an open-ended bill.
- Daily / monthly / max balance — three numeric guardrails per tenant; hitting a hard limit blocks rather than overspends.
- Low & critical alerts — configurable thresholds warn before a tenant runs out, if alerts are enabled.
- Spend caps — a configured ceiling blocks further usage with an explicit message instead of an unbounded bill.
- Dunning — a failed subscription payment suspends usage; the next paid invoice resolves the dunning state automatically.
The billing page & Stripe portal
Manage the plan you pay the platform for — separate from the merchant account buyers pay.
The tenant billing page surfaces the platform subscription: the current plan and tier, lifetime-access state, and a "Manage billing" button that opens the Stripe-hosted Customer Portal for cards, invoices, and cancellation. A "Change plan" link routes to the plans page to upgrade or downgrade. Lifetime tenants see a clear note that there's no ongoing subscription to manage, and the manage-billing button is disabled for them.
This platform-billing tab is deliberately separate from the payments settings, which configure the tenant's own merchant Stripe account — the one their buyers pay. One screen is "the plan you pay Mass for"; the other is "the account your customers pay you through." Keeping them apart avoids the classic confusion between your subscription and your revenue.
- Plan snapshot — current plan, tier, and lifetime-access state read from the billing subscription endpoint.
- Stripe Customer Portal — 'Manage billing' opens Stripe's hosted portal for cards, invoices, and cancellation.
- Change plan — a direct link to the plans page to upgrade or downgrade the subscription.
- Separate from Payments — platform billing (what you pay us) is distinct from merchant payments (what your buyers pay you).