Credit Burndown Billing Model

In a credit burndown model, customers hold a prepaid credit balance that decreases as they use your product. When the balance runs low they buy more, which is the point of the model: usage is not capped, it is metered against something the customer has already paid for.

The pattern shows up across AI platforms, developer tools like Supabase and PostHog, and enrichment services like Apollo.io and Clearbit. Most implementations share a shape:

• A paid plan includes a credit allocation each billing cycle, usually monthly. Free plans can use credits too, typically with a small or zero allocation.
• Customers on any plan can buy more credits whenever they want. This is what makes credits an expansion lever rather than just a usage cap: a paid customer can spend more without moving up a tier, and a free customer can start paying without a plan change at all.
• Features draw against the balance as they are used, and different features can cost different numbers of credits.
• A depleted balance is a purchase prompt, not a lockout. Many products add automatic top-ups so service is never interrupted at all.

What this buys you:

• Revenue scales with usage, the same as other usage-based models.
• Customers prepay, so there are no surprise invoices.
• Several features share one pricing metric instead of each being metered separately.
• Credit pricing supports volume discounts, such as 100 credits for $10 and 10,000 for $800.
• Individual feature costs can change without touching credit pricing or any other feature, so you can adjust as your own costs move.

Video Tutorial

This video walks through setting up a credit burndown model in Schematic, covering credit types, plans, and credit based features.

Implementing Credit Burndown in Schematic

This guide starts from a scenario where you already have a usage-based plan with two features, “AI Assists” and “AI Experiments”, and builds a new plan that bills the same features through credits instead of direct usage tracking.

By the end you’ll have a credit-based plan where customers spend credits on both features and can buy more when they run out.

1. Create a Credit Type that can be applied to plans.
2. Create a new plan that will use the credit burndown model.
3. Add the Credit Type to that plan.
4. Add features and configure how they consume credits.
5. Configure Credit Bundles customers can buy to top up.
6. Add the plan and bundles to the Catalog.

1. Create a Credit Type

Schematic supports multiple credit types, but most companies use a single type across all their credit based plans. Start there unless you have a reason not to.

Mouse over Catalog and select Credits to open the Credit Type page.

Click “Create Credit Type”:

1. Name the credit type. We’ll use “AI Tokens”. With multiple types, usage-based names like “Data Credits” or “API Tokens” work better than tier-based ones.
2. The description is optional and appears to customers in the portal and checkout flow.
3. Give singular and plural names for the unit. We’re using “AI Token” and “AI Tokens”.
4. Cost basis tracks what a credit costs you, for your own finance workflows. It does not control what customers pay. We’ll use $0.01, though fractional cents like $0.00025 are fine.
5. Click “Create Credit Type”.

2. Create a new plan

Any plan can use credit burndown, new or existing. We’ll create a dedicated one to keep the example clear.

1. Go to the “Plans” tab and click “Create Plan”.
2. Name it. We’ll use “Credit Based”. Click “Continue”.
3. Set it to “Paid” with a monthly price of $5 and a yearly price of $50.
4. Click “Save”.

3. Add the Credit Type to the plan

1. Click “Add credit grant”.
2. Select “AI Tokens”.
3. Set how many credits the plan provides each period. We’ll use 5,000. Leave Reset on Monthly and Rollover at 0, which means unused credits are discarded when the grant resets. Credit lifecycle covers the alternatives.
4. Click “Create plan grant”.

4. Add features and set their consumption rates

1. Click “Add feature”.
2. Select “AI Assists” and click “Continue”.
3. Set the type to “Credit burndown”.

4. Select “AI Tokens”.
5. Set the consumption rate, which is how many credits one use of the feature costs. We’ll use 5.
6. Click “Save Changes”.

7. Repeat for “AI Experiments” with a consumption rate of 10.

The finished plan:

5. Configure Credit Bundles

Bundles are what customers buy when their plan allowance runs out. We’ll set these to never expire so customers can keep using credit-based features after the plan balance is gone, though bundles can carry an expiry window instead.

Plan grants are spent before purchased bundles, so a bundle is only drawn from once the period’s plan credits are exhausted. See Consumption order for the full picture.

1. Go to the Credit Type page (Catalog > Credits > “AI Tokens”).
2. Name the bundle. We’ll use “Small Bundle”.
3. Set the credit quantity. We’ll use 5,000, matching what the plan provides.
4. Set a price, ideally in line with the credit type’s cost basis. We’ll use $5.
5. Click “Create Bundle”.

6. Repeat for a “Medium Bundle (10% off)” with 10,000 credits at $9. Volume discounts on larger bundles encourage customers to buy more at once.
7. Repeat once more for a “Large Bundle (20% off)” with 20,000 credits at $16.

The finished bundles:

6. Add the plan and bundles to the Catalog

1. Go to the “Catalog” tab and select “Configuration”.
2. Click the ”+” on the right of the “Live Plans” section.
3. Add the plan you created.
4. Click “Save”.

5. Scroll to “Credit Bundles” and click ”+” to add the bundles.

6. Save your changes with the “Save Changes” button in the top right. This step is easy to miss.

The bundles now appear in your checkout flow:

Credit lifecycle

The walkthrough used the defaults. This section covers what else a credit grant can do.

Reset is the setting everything else hangs off. A grant either recurs or it doesn’t, and that choice determines which other fields you see:

Rollover and expiration are alternatives, not independent settings. A recurring grant has no expiration date of its own, and a one-time grant has nothing to roll over.

You’ll find these by opening a credit grant on a plan, or any row in the Plan Grants table on a credit type page.

Reset and rollover

Pick a cadence and the grant refreshes on that schedule. For Monthly, Quarterly, and Yearly you also choose when the cycle starts: According to billing period start date, which follows the company’s own billing anniversary, or the calendar equivalent (First of month, First of quarter, or First of year). Daily and weekly grants always run from plan enrollment.

Rollover is the percentage of unused credits that survive a reset. At 0 the customer loses whatever they didn’t spend, which is what the walkthrough does. At 100 the full remainder carries forward. Values in between give customers partial credit for what they didn’t use without letting balances compound.

Rollover is only offered for monthly, quarterly, and yearly grants. Daily and weekly grants reset too often for it to be meaningful.

Grant expiration

Set Reset to “No reset” and the grant becomes one-time. Grant Expiration then controls how long the credits last:

Choosing Duration gives you quick-select buttons for 30 days, 90 days, and 1 year, plus a custom value in days. Choosing End of Billing Period adds a Billing Period selector for Current or Next.

On a free plan there is no billing period, so “End of Billing Period” is not offered.

Credit bundles have the same three options under a field labeled Expiry Type. The bundles in step 5 are set to No Expiry, but that is the example’s configuration, not a property of purchased credits.

Consumption order

A company usually holds several grants at once. Each consumption event draws its full amount from one grant and moves to the next once that one is empty, in this order:

1. Adjustment grants, meaning credits returned by a refund
2. Rollover grants, so last period’s leftovers go before the fresh grant they came from
3. Plan grants, oldest first
4. Everything else, oldest first, which in practice means purchased bundles and promotional credits

Rollover grants sitting ahead of the new period’s grant is what makes rollover useful. Because they also expire at the next reset, putting them last would mean they usually lapse unspent.

Where credits come from

Every grant records its source. The Companies tab on a credit type lists each grant a company holds along with its status, source, usage, and expiration.

App settings and their API fields

Everything above is configurable through the API as well. The dashboard uses friendlier labels than the underlying fields, and in a few places one control maps to more than one field, so this table is the translation.

Credit grant on a plan

These live on BillingPlanCreditGrantResponseData.

Two things the API exposes that the dashboard does not:

• expiry_type also accepts end_of_trial, which expires credits when the company’s trial ends. There is no dashboard control for it.
• expiry_unit also accepts billing_periods, so a duration can be counted in billing periods rather than days. The dashboard only offers days.

Credit bundle

These live on BillingCreditBundleResponseData.

Credit type

These live on BillingCreditResponseData.

The credit type also carries default_expiry_unit, default_expiry_unit_count, and default_rollover_policy, which set defaults new grants can inherit. The dashboard has no controls for them and clears them when you save the credit type, so they are only usable through the API.

Grant sources

The grant_reason field on a credit grant carries the source shown in the dashboard.

Rollover grants also carry source_grant_id, pointing back to the grant they came from, so a carried-forward balance is traceable to its origin.

Credit Refunds via Negative Quantities

Submitting a track event with a negative quantity for a credit burndown feature reverses the consumption and returns credits to the company’s balance. Use it when a request failed, was retried, or needs correcting.

How it works

1. Submit a negative quantity event using a secret API key. Publishable keys cannot submit negative quantities.
2. Schematic multiplies the negative quantity by the feature’s consumption rate to get the number of credits to refund.
3. The credits go into an adjustment grant, created automatically per company per credit type.
4. Adjustment grant credits are consumed before anything else on the next draw.

Example

“AI Assists” costs 5 credits per use and a company has used 10 of them, consuming 50 credits. To reverse 2 of those uses:

1
await client.track({
2
  event: "ai-assist",
3
  company: { "company-key": "acme-corp" },
4
  quantity: -2,
5
});

That returns 10 credits to the balance through an adjustment grant, and those 10 are spent first the next time the company uses any credit-consuming feature.

Key details

• Adjustment grants accumulate. Repeated refunds for the same company and credit type add to the existing adjustment grant rather than creating new ones.
• Adjustment grants are consumed first. This holds under every burn strategy, ahead of plan grants, purchased credits, and promotional credits.
• Adjustment grants do not expire quickly. They carry a rolling 1-year expiration that extends with each refund, so they will not lapse while in active use.
• Negative events create negative usage records. Each refund writes a corresponding negative record to the credit usage ledger for auditing.

Auto Top-Up

Auto top-up buys credits automatically when a customer’s balance falls below a threshold, so they are not cut off mid-workflow. It is configured on the plan’s credit grant, in the same form as the reset and expiry settings.

1. Open the credit burndown plan you want to configure.
2. Click “Add credit grant”.
3. Select the Credit Type and Credit Amount.
4. Set Top-up Availability to Automatic or User-controlled, covered in Who controls auto top-up below.

5. Top-up Threshold is the balance that triggers a purchase, given as a number of credits remaining rather than a percentage. The balance it checks counts all plan grants, purchased grants, and promotional grants.
6. Top-up Amount is how many credits get bought. The cost follows the credit type’s cost basis and appears in the confirmation below.
7. Top-up Grant Expiration sets the expiry policy for the purchased credits. Auto top-up grants offer Duration and No Expiry only, not the billing period options. A 1 year duration is a good default, long enough for customers to use the credits and short enough to keep revenue recognition simple.
8. Review the confirmation showing the final cost, threshold, and expiration, then click “Create plan grant”.

Who controls auto top-up

Top-up Availability decides both whether auto top-up runs and who operates it:

Choose User-controlled for self-serve plans where customers should manage their own refills, and Automatic when continuity matters more than customer control, such as an enterprise account that should never stop mid-workload. Under User-controlled the Top-up Threshold and Top-up Amount fields are labeled “(default)”, because the customer can change both.

Buyers can purchase credit bundles is a separate checkbox on the same grant, covering one-time bundle purchases. It is independent of top-up availability, so you can let a customer buy credits on demand without letting them set up an automatic refill, or the reverse. Unchecked, the buy-more button is hidden and one-time bundle purchases are rejected.

Per-company exceptions

Top-up settings live on the plan grant, so every company on that plan starts with the same threshold and amount. Individual companies can be given different values through the API, which is currently the only way to do it, as the dashboard has no per-company top-up control.

Under User-controlled availability the customer changes their own threshold and amount, which covers many of the cases an override would otherwise handle.

Triggering an Auto Top-Up

An auto top-up fires while processing an event that draws from a credit balance, when that balance is at or below the threshold. If several events arrive close together, only one top-up is purchased.

If a top-up purchase fails, Schematic retries the next time the balance is drawn from.

Three webhook events report the outcome of each attempt: auto.topup.success, auto.topup.hard.failure, and auto.topup.retry.exceeded. A hard failure carries the Stripe error code when the failure originated there, which is what lets you tell a declined card apart from a missing payment method. Subscribe to them under Settings > Integrations > Webhooks, and see Entitlement & Credit Trigger Webhooks for the full payloads.

Because a failing top-up means a customer is about to be cut off, wiring auto.topup.hard.failure to an internal alert and a customer-facing email is worth doing before you turn auto top-up on. See Spend and usage controls for how auto top-up fits with the other limits available to you.

Accessing Credit Information via API

List Company Credit Grants

List Company Credit Grants returns every grant a company holds, including its reason, quantity, remaining balance, and expiration, which is how you reconstruct the composition of a balance.

Grant Billing Credits to Company

Grant Billing Credits to Company adds credits outside the normal plan or purchase flow, for promotional grants, manual refunds, or administrative corrections.

Zero Out Grant

Zero Out Grant sets a specific grant’s remaining balance to zero, for when a grant needs cancelling.

List Feature Usage

List Feature Usage supports filtering and pagination, and with the include_usage_aggregation parameter it returns a credit_usage_aggregation object with time-bucketed data:

• usage_this_billing_period: credits used in the current billing period
• usage_this_calendar_month: credits used in the current calendar month
• usage_this_week: credits used in the current week
• usage_today: credits used today

Use this to show customers their consumption patterns over time.

Conclusion

You now have a credit burndown model that lets customers prepay for usage, buy more when they run out, and receive volume discounts on larger purchases, while you meter several features against a single pricing metric. The same setup works on existing plans as well as new ones.