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 Handle your code uses to reference it, and a Feature Type 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:

• 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.
• 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.
• 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 six 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.
• Carried over: Moved from an archived overage wallet, keeping its expiration date, or no expiration if it never expired, when a change to the subscription's features, such as a plan change, moves overage to another price point. See the section on that change below.

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, and Balance Breakdown on the wallet's page already counts that unposted usage against each grant. While the balance is current, the grants' left amounts add up to the balance shown above them, unless the balance is below zero.

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

Once the balance is gone, further consumption isn't silently absorbed. What happens to it depends on what the wallet was set to do when usage exceeds the balance, a choice fixed when the wallet is created:

• 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.
• Bill as overage: The balance stops at zero, and consumption beyond it is recorded as overage and billed on the subscription's invoice.

Important: Allowing negative balances means a subscriber can consume past their allowance without being invoiced for it. A negative balance is repaid in units by the next refill, grant or purchase. If you want consumption past the allowance charged, use Bill as overage instead.

How overage is billed

On a wallet set to bill overage, usage that the wallet's grants can't cover is posted to the ledger as an Overage row, and the balance stays at zero. That overage is billed in arrears, as one charge for the period's overage at the wallet product price point the wallet stores. When it is billed follows that price point's own billing interval:

• A billing interval: a monthly interval bills each month's overage at the month's end, even on a subscription with an annual plan.
• No billing interval: the overage is billed on the subscription's renewal invoice.

The quantity is in the wallet's own unit and can be fractional, and a period with no overage adds no overage line to the invoice.

The overage line takes the wallet product's name as its title. When the line bills a single wallet that was created from a feature, the title also says how much the subscription's allowance included, for example Additional calls (beyond 100 included). The same title appears on the invoice and on previews of the upcoming invoice.

The included amount is the allowance of every refill schedule still funding the wallet, added together. Two cases change what the title quotes:

• If an allowance is lowered during the period, the title quotes what was already granted for that period.
• On the final invoice of a subscription canceled at the end of its period, the title still quotes the allowance that funded the wallet during that period.

The overage line keeps the plain wallet product name when:

• The wallet was added manually on the subscription rather than created from a feature.
• The line bills more than one wallet, including overage from an archived wallet that hasn't been invoiced yet.
• The included amount can't be read from the wallet's refill schedules, or adds up to zero.

These rules apply to overage billing:

• The price point has to be able to bill it. A price point with hybrid pricing can't bill overage. On a termed subscription in a currency other than your site's primary currency, the price point needs a definitive price in that currency.
• One price point per wallet product on a subscription. If a subscription already bills overage for a wallet product at one price point, a second overage wallet on the same wallet product has to use that price point too. A change that replaces a feature's wallet with another feature's wallet at a different price point is handled separately, as described in When a plan change moves overage to another price point.
• Usage is never billed twice. An overage wallet and an event-based component can't bill the same meter on one subscription, whichever is added first, including a component scheduled to activate at a renewal or through a pending change. Wallets that discard or allow a negative balance aren't affected.
• Several overage wallets can share a meter. When several overage wallets on one subscription read the same meter, usage that all of them are over on is billed once, on the wallet whose price is lowest per meter unit. The other wallets post a zero-amount row whose memo reads Overage of the amount deferred to wallet followed by that wallet's name.
• A cancellation at the end of the period bills the last overage. The final renewal invoice bills the overage through the end of the period, including usage from the wallet's last usage window. Usage after that isn't captured as overage.
• An immediate cancellation depends on your site. If your site charges unbilled usage after a subscription is canceled, overage up to the end of the canceled subscription's period is billed with that unbilled usage, last usage window included. If it doesn't, overage capture stops when the subscription is canceled, and overage captured before then that isn't on an invoice yet is written off. Either way, usage after the cutoff isn't captured as overage.
• Reactivation writes off what's unbilled. Reactivating a subscription doesn't bill overage from before the reactivation. Any overage not yet billed is written off.
• Overage is billed to four decimal places. Each capture is rounded on its own, half up, so a capture from 0.00005 of a unit bills as 0.0001. A capture below that rounds to zero, bills nothing, and is written off when it's captured. Small captures aren't added together, so they never build up into a billed amount.
• The wallet product stays in use. While an active wallet bills overage through it, the wallet product can't be archived (Wallet product is in use by an active overage wallet), and neither can the price point the wallet bills at (Price point is in use by an active overage wallet).

Other than a capture that rounds to zero, which is recorded and written off as described above, if overage can't be billed when usage is recorded, the part beyond the balance isn't recorded. Usage you record yourself reports that the amount couldn't be billed as overage and wasn't recorded. For a metered wallet, the ledger gets a zero-amount row whose memo starts Overage of the amount not billed: followed by the reason.

When a plan change moves overage to another price point

A subscription can move from one feature's overage wallet to another feature's overage wallet that bills the same wallet product at a different price point, for example when you change its plan to a higher or lower tier. When the funding of every active overage wallet on that wallet product has ended, Advanced Billing replaces the old wallet with the new one in these steps:

1. Overage that hasn't been invoiced yet is billed at the old price point on its own invoice, created and issued at the time of the change rather than added to the plan change's invoice or the next renewal. If the payment for it is declined, the invoice stays open. With no unbilled overage, no invoice is created.
2. The old wallet is archived. The Overage rows billed on that invoice read Billed on invoice followed by its number, so the overage isn't billed again at renewal. Rows that already had a status, such as Not billed (written off), keep it.
3. The new wallet is created at the new price point, and the subscription's overage for that wallet product is billed at the new price point from then on.
4. Each unspent grant on the old wallet moves to the new wallet as a Carried over grant and keeps its expiration setting: a grant with an expiration date keeps that date, and a grant that never expires still never expires. A grant that has already passed its expiration date stays on the old wallet to be written off. The new feature's allowance is granted on top of the carried-over units. The handover writes the Carried over to wallet adjustments on the old wallet in the same step as the archive, so they post even though an archived wallet otherwise accepts no new adjustments.

The old wallet stays active and the new wallet isn't created when another active overage wallet on the same wallet product was added manually on the subscription, or is still funded by a feature the subscription holds.

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 six 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 what you need to set up first:

• 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.
• 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; see Create and Manage Wallet Products.

What wallets can't do and how they behave

These limits and behaviors apply once wallets are running, and they affect where wallets can be used, how quickly balances settle, and what you can change afterward:

• Wallet behavior can only be attached to a feature whose kind is usage limit. That feature also can't be attached to a Plan or Product that's metered, prepaid-usage, or events-based, because those already meter their own consumption and a usage-limit feature there would double it. Attaching one is refused with a 422, whether or not the feature is wallet-backed.
• Wallets aren't available on a prepaid subscription, since a prepaid subscription already meters against its own balance. A wallet-backed feature isn't provisioned one, the Add Wallet wizard isn't offered, and POST /wallets.json refuses with "Wallets are not available on prepaid subscriptions".
• A subscription that hasn't gone live yet (Awaiting Signup, Awaiting Signup Date, Pending, or Failed to Create) isn't provisioned a wallet at all, not even at a zero balance. As soon as it goes live, the wallet is created and funded for the period already in progress, with no backlog from the waiting period to catch up on.
• 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.
• 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 Grants Expiration policy instead.
• On a wallet's details page, the ledger rows, the metered usage window, the line that says how current a metered balance is, and an adjustment's entry date resolve in your site's time zone and carry its abbreviation, so they read the same for everyone regardless of their own browser's time zone. A grant's expiration date is a calendar date judged in your site's time zone, with no time or abbreviation. The Last activity date on a wallet card in the Wallets tab's list uses your browser's time zone.
• A wallet that allows a negative balance never invoices the shortfall. It's repaid in units by the next refill, grant or purchase. To charge for consumption past zero, create the wallet to bill overage instead (see How overage is billed), or sell more balance with the Purchase action on the subscription's Wallets tab.

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.