Understand Wallets

BETA

This feature is currently in beta and may change over time. During the beta period, functionality, availability, and performance may vary.

To join the Beta program, request Beta access.

Entitlements define what a subscriber is eligible to use, and metering measures what they actually used. A wallet tracks what remains: a consumable balance on a single subscription, funded by grants, drawn down by usage, with every movement written to a ledger you can read back entry by entry.

Why use wallets

Use a wallet when an allowance is consumed rather than simply granted, and when you need to answer how much is left? as reliably as what were they entitled to? Wallets let you:

• Carry a running balance on a subscription instead of recalculating one from usage records.
• Fund that balance automatically on a recurring cadence, or add to it manually when a deal requires it.
• Expire unused value on a schedule you set, so allowances don't accumulate forever.
• Explain any balance by reading its ledger, where every grant, debit, expiration, and correction is a separate immutable row.

How wallets work

A wallet is provisioned from a usage-limit entitlement on a feature. You author the wallet behavior once on the feature, and every subscription that resolves that feature gets a wallet built to match.

What a feature is

A feature is one capability or allowance you define once in Catalog > Features and reuse across any Plan or Product. Each one carries a name, a stable Lookup Key your code uses to reference it, and a kind that decides how its value is read:

• Access: a capability that is either on or off, such as SSO or priority support.
• Limit: a numeric allowance, such as API calls or storage. Only a Limit feature can be wallet-backed.
• Service Right: a service level or tier that does not reset, such as an SLA.

Attaching a feature to a Plan or Product sets the value a subscriber receives, and that value resolves onto each subscription that holds it. See Understand Entitlements for how features, their kinds, and their values work in full.

Where a wallet comes from

Three pieces combine to produce a wallet on a subscription:

1. A usage-limit feature: Wallet behavior can only be attached to a feature whose kind is usage limit. Access rights and service rights can't be wallet-backed.
2. A wallet product: The feature's wallet behavior points at a billing product that is metered and has a unit configured. That product's unit denominates the wallet, so a balance is always expressed in tokens, credits, calls, or whatever unit you've defined.
3. A wallet on the subscription: When the entitlement resolves, Advanced Billing creates the wallet against that subscription and funds it straight away, with no API call and no manual step. A wallet is always owned by exactly one subscription.

The configuration a wallet is built from is fixed once the wallet exists, so a subscription's wallet keeps behaving the way it did when it was created even if you later change the feature.

A wallet can also be created manually on a subscription, for cases the feature's own configuration doesn't cover. See Add a Wallet to a Subscription.

What makes up the balance

A wallet's balance isn't a single stored number you edit. It's the sum of what remains across the wallet's grants. Each grant records the amount it was originally worth, how much of it is still unspent, and, optionally, when it expires.

Because the balance is made of grants, usage has to draw down from somewhere specific. Advanced Billing spends grants in a fixed order: grants that carry an expiration date go first, soonest expiration first, and grants that never expire are spent last. That means value at risk of being written off is always consumed before value that remains available next month.

How the balance changes

Every change to a wallet falls into one of three shapes.

Grants add value

A grant is value arriving in the wallet. Grants come from five places:

• Recurring: Written automatically on the refill cadence set on the feature.
• One-time: Added deliberately, for example to compensate a customer after a service incident.
• Initial balance: The opening balance the wallet was created with.
• Allowance increase: Written automatically when the funding feature's allowance is raised mid-period.
• Purchase: Bought through the Purchase action on the subscription's Wallets tab, and billed on an invoice.

A grant's original amount is fixed at creation and can't be edited afterward. Correcting a grant means posting new ledger activity, not rewriting the grant.

Usage draws it down

Usage produces debits against the wallet, spent across grants in the drain order described above.

For a wallet paired with a meter, the balance you see also accounts for usage the meter has recorded but the ledger hasn't yet settled. Advanced Billing reads the meter's usage, converts it into the wallet's unit, and shows you the balance net of that usage. If the usage store can't be read at that moment, the recorded balance is shown instead and marked as out of date, rather than reporting a number that might be wrong.

That metered usage is also written to the ledger in its own right: when a grant is fully spent, when a grant expires, and periodically in between. The ledger therefore catches up with the balance rather than trailing it indefinitely, though between two of those postings the grants can still add up to more than the balance shown above them.

Where a wallet discards overflow, usage a meter records while the balance is already at zero is never written to that wallet's ledger. It stays recorded in the meter, and it isn't added later even if the wallet is funded again.

Expiration writes off what remains

If the feature sets a grant expiration policy, each grant is stamped with an expiration date when it's written. Once that moment passes, whatever is left in the grant is written off and recorded in the ledger as an expiration.

Refills and expiration write-offs are processed on a schedule rather than the instant they come due, so a balance can briefly lag the moment a refill or expiration was scheduled for.

What happens when a wallet runs out

Wallets enforce depletion by hard stop: once the balance is gone, further consumption isn't silently absorbed. What happens to the overflow depends on how the feature is configured:

• Discard: Consumption beyond the available balance is refused. The balance stops at zero and doesn't go negative.
• Allow negative: Consumption beyond the available balance is still recorded, and the balance goes below zero.

Important: Allowing negative balances means a subscriber can consume past their allowance. Advanced Billing doesn't bill that overage automatically, and a negative balance is repaid by the next grant or purchase that lands. Choose this option only when you intend to reconcile the overage some other way.

How the ledger records every change

Every movement in a wallet is a row in its ledger, and each row carries the balance as it stood immediately after that movement. Rows are one of five kinds:

Ledger rows are immutable once written. Nothing is ever edited or deleted, so correcting a mistake means posting an adjustment that references the original entry. The history of what actually happened stays intact, and the correction is visible alongside it.

Example: a subscriber is granted 20M tokens at renewal and uses 5.5M of them. The ledger shows a grant row of +20M and a debit row of -5.5M, with a balance of 14.5M after the second row. If that 5.5M turns out to have been over-counted, an adjustment row is posted against the debit rather than the debit being changed, and the ledger shows all three entries.

Requirements, dependencies, and limitations

Review these before using wallets in production, because they affect which sites can use wallets at all and how quickly balances settle:

• Wallets must be enabled for your site, and the site must be on invoice-centric billing. Contact your Customer Success Manager or Maxio Support to request activation.
• Drawing a wallet down from metered usage requires metered wallet consumption, a further setting on top of wallets being enabled. Ask your Customer Success Manager to enable it if you intend to pair wallets with meters.
• Wallet behavior can only be attached to a feature whose kind is usage limit.
• A wallet belongs to exactly one subscription. Wallets can't be shared or pooled across subscriptions, though a subscription can hold more than one wallet if it carries more than one funding feature.
• The billing product that denominates a wallet must be metered and must have a unit configured. Create one in Catalog > Wallet Products and give it a price point before you author wallet behavior on a feature.
• Refills and expiration write-offs are processed on a recurring schedule, so ledger settlement isn't instantaneous.
• A grant's original amount can't be changed after the grant is written, and ledger rows can't be edited or deleted.
• A wallet created manually supports only the Units balance type. Monetary (USD) balances, and drawing a wallet down by subscription-product charges, appear in the Add Wallet wizard but aren't available yet.
• Choosing Manual under Drawn down by saves nothing. It describes how a wallet with no meter already behaves rather than configuring anything, and funding is unchanged either way.
• Pairing a wallet with a meter is permanent. The meter and the conversion rate are both fixed when the wallet is created and can't be changed, removed, or re-picked afterward. Only meters that sum or count usage can be paired; every other meter is listed disabled, with the reason shown.
• A wallet's opening balance and any manual grant can each carry their own expiration date. Grants written by a feature's refill cadence take their expiration from that feature's Granted units expire policy instead.
• A grant's expiration date resolves in your site's time zone, so it reads the same for everyone looking at it. The other dates shown for a wallet come from the viewer's own browser time zone instead, so they can read a day earlier or later than the site itself shows.
• Billing consumption past zero isn't available. A negative balance is repaid by the next grant or purchase that lands, and Advanced Billing never invoices the shortfall by itself. To sell a customer more balance, use the Purchase action on the subscription's Wallets tab.

Related information

See Configure a Wallet to author wallet behavior on a usage-limit feature so subscriptions receive wallets automatically.

See Manage Subscription Wallets to add grants, buy more units, record usage, and archive a wallet.

See Troubleshoot Wallets to work out why a balance, a refill, or a correction isn't behaving as expected.

See Manage Wallets with the API to do the same work from your own application.