Credits & Wallets Overview

Understand how credits and wallets work in Alguna

Credits provide a flexible way to offer prepaid balances, promotional incentives, and consumption-based pricing to your customers. Alguna’s credit system supports both monetary credits (USD, EUR, etc.) and unit-based credits (API calls, tokens, seats).

---

Managing Credits via Dashboard

View Customer Credits

1. Navigate to Customers → [Customer Name]
2. Click the Credits tab
3. View:
   • Current balance by type (monetary, units)
   • Active credit grants
   • Expiring credits
   • Transaction history

Grant Credits to a Customer

1. Navigate to Customers → [Customer Name] → Credits
2. Click Grant Credits
3. Fill in the grant details:
   • Type: Monetary or Units
   • Amount: Credit value (e.g., $100 or 1,000 API calls)
   • Expiration: When credits expire (optional)
   • Reason: Internal note, for example “Welcome credit” or “Service compensation”
4. Click Grant

View Credit Transactions

1. Navigate to Customers → [Customer Name] → Credits
2. Click Transactions or History
3. Filter by:
   • Date range
   • Transaction type (grant, consumption, expiration)
   • Credit grant
4. Export transactions if needed

Ending a Grant Early

There is no void action on an individual grant. Remaining credit is voided by a subscription version change, where the transition policy decides whether active grants are left intact or voided. See Entitlements and Subscription Versioning.

Credit already applied to an issued invoice is never reversed by a later change.

---

Key Concepts

Credit Grants

A credit grant is an allocation of credits to a customer account. Each grant has:

• Amount: The number of credits or monetary value
• Type: monetary (currency-based) or units (quantity-based)
• Expiration date: Optional date when unused credits expire
• Reason: Why the grant was made

Credit Ledger

The credit ledger tracks all credit transactions for an account:

• Credit grants (additions)
• Credit consumption (deductions)
• Expirations (automatic removals)
• Adjustments (manual corrections)

Wallets

A wallet is a prepaid account balance that customers can top up and use for payments. Wallets support:

• Multiple currencies
• Automatic payment deduction
• Top-up notifications
• Balance thresholds

---

Credit Types

Monetary Credits

Monetary credits have a specific currency value and can be applied to invoices.

Account: Acme Corp
Credit Type: Monetary
Currency: USD
Amount: $500.00
Expiration: 2025-12-31

Use cases:

• Promotional discounts
• Referral bonuses
• Service credits for outages
• Prepaid account balances

Unit Credits

Unit credits represent quantities that can be consumed against usage-based products.

Account: Acme Corp
Credit Type: Units
Amount: 10,000 API calls
Expiration: 2025-06-30

Use cases:

• API call packages
• Compute hours
• Message credits
• Storage allocations

---

Credit Lifecycle

1. Grant Created

When you create a credit grant, it becomes immediately available for the customer.

2. Active

Credits are available for consumption against invoices or usage.

3. Consumption

Credits are automatically applied based on:

• Invoice generation (monetary credits)
• Usage events (unit credits)
• Manual application

4. Expiration

Unused credits are automatically expired on the expiration date. Expired credits cannot be recovered.

---

Credit Application Rules

Priority Order

When several grants can pay for the same charge, they are drawn in this order:

1. Priority — lowest number first
2. Expiring grants before non-expiring ones
3. Earliest expiry first
4. Oldest grant first

Priority comes from a subscription’s credit allocation, configured in the dashboard. Grants created manually or through the API sit at priority 0. See Credit Grants.

Partial Consumption

Credits can be partially consumed. If an invoice is $100 and the customer has$75 in credits:

• $75 applied from credits
• $25 charged to payment method

Currency Matching

Monetary credits must match the invoice currency. A USD credit cannot be applied to a EUR invoice.

---

Webhooks

Event	Description
account.credits.granted	Credits manually granted to customer
account.credits.balance_depleted	Credit balance reaches zero

Example Webhook Payloads

Credit Granted:

{
  "type": "account.credits.granted",
  "timestamp": "2024-08-03T20:26:10Z",
  "data": {
    "accountId": "aBsZxlLh",
    "grantId": "cg_ZVzWRFnt",
    "amount": "100.00",
    "type": "monetary",
    "reason": "Customer loyalty bonus"
  }
}

Balance Depleted:

{
  "type": "account.credits.balance_depleted",
  "timestamp": "2024-08-03T20:26:10Z",
  "data": {
    "accountId": "aBsZxlLh",
    "amount": "0",
    "type": "units"
  }
}

---

Best Practices

Set Expiration Dates

Always set reasonable expiration dates to prevent indefinite liabilities on your books.

Order by expiry

Expiring grants are drawn before non-expiring ones, so short-dated promotional credit is used first without any extra configuration.

Monitor Balances

Set up webhooks to notify customers when balances are depleted.

Document Terms

Clearly communicate credit terms, including expiration and non-transferability.

---

Next Steps

Credit Grants

Learn how to create and manage credit grants.

Credit Consumption

Understand how credits are consumed.

Wallets

Set up prepaid wallets for customers.

Wallets API

Explore the Wallets API.