Skip to main content
Metered billing is powerful, but a bill that only appears at the end of the month can surprise customers. Credits flip the model: customers hold a prepaid balance that gets drawn down as they generate usage. They know what they’ve paid for up front, and you decide what happens when the balance runs out.

​
The mechanics

Every event you ingest accrues against a Usage Meter. Credits sit on that same meter as a positive balance:
  1. You grant a customer some number of units (a credit).
  2. As events arrive, each unit of usage is deducted from the credit balance first.
  3. Once the balance hits 0, any further usage becomes overage — billed against the meter’s metered price.
So credits are not a separate ledger. They are a head start on the meter the customer is already metered against.
Macropay is the Merchant of Record for every credit you sell. We collect and remit the correct sales tax or VAT on the prepaid purchase, appear as the seller on the customer’s statement, and absorb PCI scope — so a prepaid balance doesn’t add tax-compliance work on your side.

​
Prepaid-only, no overage

Want a hard prepaid model where customers can never run up a surprise bill? Don’t attach a metered price to the product. With no price on the meter, billing is never triggered — usage simply draws the balance toward 0 and stops mattering once you stop honoring it in your app. The meter still tracks consumption; it just never invoices.

​
Granting credits with the Credits benefit

The simplest way to fund a balance is the Credits benefit, attached to a product. When a customer acquires that product, the benefit tops up their meter balance automatically. When the credit lands depends on the product type: For example, a “Starter” subscription that grants 10000 units each month refreshes the customer to a full balance on every renewal, while a “Credit pack” one-time product drops a fixed 50000 units in once and lets them spend it down at their own pace. To grant credits programmatically — say, after a manual top-up or an account-management action rather than a purchase — follow the grant meter credits guide.

​
Reading the balance

Your application almost always needs to know how much a customer has left. Two ways to get it:

Customer State

One call returns a full snapshot of the customer, including the live balance of every active meter. Best when you already fetch customer state on login.

Customer Meters API

Query meter balances directly when you only need usage figures — ideal for a usage widget or a pre-flight balance check.
A typical gate in your app: read the balance, and if it’s depleted, hold the action or prompt for a top-up.

​
Credits for AI and agent usage

Prepaid credits map cleanly onto AI workloads, where a single customer action can fan out into unpredictable token spend. Sell a customer a block of credits, meter their consumption, and let the balance absorb the variance instead of issuing a volatile invoice each month.
  • Token usage: route traffic through the AI proxy so token cost is captured automatically, then draw it from the prepaid balance.
  • Agent activity and outcomes: ingest agent signals, meter them, and bill prepaid credits against completed actions or delivered outcomes — pairing nicely with value receipts that certify the ROI behind each draw-down.
This keeps agentic margin legible: prepaid revenue on one side, the underlying AI cost on the other.
Macropay does not block usage when a customer exhausts their balance. The meter keeps counting and, if a metered price is attached, overage is billed. Enforcing a hard stop — rejecting requests once the balance hits 0 — is your application’s responsibility.