Credits & Wallets Overview

Credits are how a customer pays before consuming. Alguna has two balances that do this, and they are separate systems:

• A credit grant is a balance you allocate to a customer — a welcome credit, a service credit, a purchased package, or the included credits of a plan. Grants are monetary (in the subscription currency) or units (metric quantities), and they are consumed automatically when invoices are priced and, for gated usage, in realtime.
• A wallet is a prepaid money balance in one currency, funded by wallet grants and payments, and offered as a payment method on invoices in that currency.

Use this page to pick the right one and to learn the vocabulary the rest of the section relies on. For where credits sit in the quote-to-cash chain, see How Alguna Works.

---

​

Which one do I need?

Rule of thumb: if the customer is buying capacity (“10,000 API calls”, “$500 of usage”) or you are compensating them, use a credit grant. If the customer wants to deposit money and settle invoices from it, use a wallet.

---

​

Credit grants

​

Monetary and unit credits

A grant does not name a metric. What it may pay for at invoice time is set by its product and price filters; what it funds at the realtime gate is a separate gate-funding setting (off by default). Both are described on Credit Grants. Monetary credit must match the invoice currency: a USD grant never applies to a EUR invoice. See Multi-Currency.

​

Where grants come from

Each grant records its origin in grant_type: allocation (provisioned by a plan’s credit_allocation entitlement, including recurring allowances), manual (an operator in the dashboard), api (POST /subscriptions/{id}/credits/grant), or rebalance (written by a subscription version change).

​

Lifecycle

A grant has no status field. It is spendable from its creation until expires_at, and its remaining amount goes down as it is consumed. Expired credit is removed from the balance and cannot be recovered. There is no void action on an individual grant; remaining credit is voided by a subscription version change whose transition policy says so — see Entitlements and Subscription Versioning. Credit already applied to an issued invoice is never reversed by a later change.

​

Consumption order

When several grants can pay for the same charge they are drawn by priority (lowest number first), then expiring before non-expiring, then earliest expiry, then oldest. Priority is a dashboard setting on a subscription’s credit allocation; manual and API grants are priority 0. Worked examples are on Credit Consumption.

​

The credit ledger

Every movement is a ledger entry with a type — allocation_grant, manual_credit, manual_debit, invoice_consumption, immediate_consumption, capture, allocation_rollover_adjustment, credit_expiry. Invoice consumption is written as pending while the invoice is a draft and becomes final when it is issued. The ledger is visible per customer and per subscription in the dashboard; the entry types are described on Credit Consumption.

---

​

Wallets

A wallet holds one currency, belongs to one customer, and is credited and debited through the API with every movement recorded on the wallet ledger (credit_grant, payment, refund, manual_debit). A wallet grant is how a prepaid package is represented: it is pending until funded, approved when its amount has been credited to the wallet, and can end voided or expired. Wallets can be restricted to product_ids, and they pay only invoices in their own currency. A credit note can be refunded into a wallet instead of to the original payment. Full API and rules on Wallets.

---

​

In the dashboard

• Customers → [Customer] → Credits shows the customer’s credit balance by type, the grants behind it, and recent ledger activity. Add Credits creates a manual grant.
• A subscription’s Credits & Entitlements section shows its allocations and their filters, priority, and gate funding.
• Customers → [Customer] → Profile → Wallets lists the customer’s wallets and their balances.

---

​

Webhooks

Payloads are camelCase and carry the accountId, the credit type (monetary or units), and on grants the grantId, amount, and reason. See Webhooks. The credits_depleted automation trigger fires on the same condition, so you can email the customer or post to Slack without writing a webhook handler.

---

​

Next steps