Credits & billing: one currency for every AI action

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.

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.

Plans & the pricing page

Personal, Agency, and Lifetime deals — compared on one page, with a plan finder to pick the right one.

Plans set both feature access and the monthly credit allotment. The pricing page groups them into three tabs: Personal (Free, Starter, Pro, and Unlimited), Agency (Partner / Reseller, White Label, and White Label Pro), and Lifetime deals (pay-once Partner / Reseller, White Label, and Black Label). A monthly/annual toggle shows the annual savings badge, and each plan card shows its credit equivalents and the apps the plan includes. Current prices and allotments are always shown on the pricing page.

The plan finder lets you pick the apps and usage you expect and recommends a plan, with credits by plan and your savings compared with the tools Mass replaces. Turn on the reseller toggle to estimate potential monthly and yearly profit and break-even client counts for the agency plans. Choosing a plan opens checkout in a pop-up on the page; if you're signed out, you log in and the checkout reopens where you left off.

• Free — 500 one-time credits that expire after 14 days — enough to try the platform end to end.
• Personal & Agency — monthly or annual subscriptions with credits that refresh every month.
• Lifetime deals — pay once — Partner / Reseller, White Label, and Black Label run on your own AI keys (BYOK).
• Plan finder — recommends a plan from the apps and usage you pick, with credits by plan and savings versus the tools it replaces.
• Reseller estimate — a reseller toggle shows potential monthly and yearly profit and break-even client counts for agency plans.

Choosing a plan at sign-up & the Starter trial

New accounts pick a plan before entering the dashboard.

Right after creating an account, new sign-ups choose a plan before they reach the dashboard. Starter comes with a free trial that requires a card; higher plans use pay-today pricing. Starter sign-ups can also skip the trial and pay today for a bonus reward. Platform admins configure each plan's offer and an optional countdown window.

Trial length comes from a dropdown of presets: platform admins and agencies in SaaS Mode choose a 3, 7, 14, or 30-day trial, with 3 days as the default.

• Post-signup plan picker — new accounts choose a plan before entering the dashboard.
• Starter free trial — a card-required free trial on Starter; higher plans are paid today.
• Skip-the-trial reward — Starter sign-ups can pay today for a bonus reward; admins set each plan's offer and an optional countdown.
• Trial presets — 3, 7, 14, or 30 days, set by platform admins or agencies in SaaS Mode; 3 days is the default.

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. A plan's first payment adds its monthly credits once — never twice.

Each plan's monthly allotment is shown on its plan card on the pricing page, and your plan's credits refresh each billing cycle. Free gets 500 (expiring in 14 days). Lifetime BYOK tenants 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.
• Refresh monthly — plan credits refresh each billing cycle; see each plan card for its allotment · 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 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 buy a credit pack in a secure payment window on Mass — you're no longer sent to a separate Stripe page. The purchase is logged as a pending transaction immediately and finalized when payment completes, and each credit purchase is added exactly once. 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.

• On-site checkout — buy credit packs in a payment window on the page; each purchase is added exactly once.
• 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.

Metered messaging, Google Sheets & Pay-to-Download

Usage-based actions are charged in credits at the price you see.

Email, SMS, and voice usage is turned into credits every 15 minutes, with fractions carried over so a single email is not rounded up to a full credit. SMS, WhatsApp, voice calls, and email sends pause when the paying wallet cannot cover the messaging owed. The per-row price shown on Google Sheets automation steps matches what is charged, including any agency markup.

Pay-to-Download adds a charge when you download. It doesn't replace the credits used to generate, which are charged as usual. Admins set free downloads per period for each plan and a credit price per download for videos, funnel and page exports, and documents. Locked videos show a watermarked preview, and re-downloading the same item is free. For white-label agencies, sub-account usage is charged to the agency wallet at the platform price and to the sub-account at the agency's price — or absorbed by the agency — with the margin recorded on every charge.

• Messaging in credits — email, SMS, and voice usage converts to credits every 15 minutes, with fractions carried over.
• Empty-wallet protection — SMS, WhatsApp, voice calls, and email sends pause when the paying wallet can't cover them.
• Google Sheets pricing — the per-row price on Google Sheets steps matches the charge, including agency markup.
• Pay-to-Download — free downloads per period by plan, then a credit price per download; re-downloads are free.
• Agency wallet settlement — white-label sub-account usage settles against the agency wallet, with margin recorded per charge.

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, saved cards & the 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 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.

Saved cards are managed in Mass: Settings → Payments lists all your saved cards, where you can add a card, make one the default, or remove one. You can also update your card straight from the payment-overdue banner or the auto-recharge settings. In Settings → Credits & Billing, the credit balance in the top bar can be shown or hidden at the platform, agency, or account level.

Platform billing is deliberately separate from the tenant's own merchant Stripe account — the one their buyers pay. One 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 on the billing page.
• Saved cards — add, make default, or remove cards in Settings → Payments, or update from the overdue banner or auto-recharge settings.
• Change plan — a direct link to the plans page to upgrade or downgrade the subscription.
• Credit counter — show or hide the top-bar credit balance at the platform, agency, or account level in Settings → Credits & Billing.
• Separate from merchant payments — platform billing (what you pay us) is distinct from merchant payments (what your buyers pay you).