Skip to main content

​
Credits & Wallets

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)
    • Currency/Metric: USD, EUR, or metric code for units
    • Expiration: When credits expire (optional)
    • Priority: Lower number = used first
    • Reason: Internal note (e.g., “Welcome credit”, “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

​
Void Credits

  1. Find the credit grant in the customer’s credits tab
  2. Click the ⋮ menu → Void
  3. Enter reason for voiding
  4. Confirm
Voiding removes remaining credits immediately. Credits already applied to invoices are not affected.

​
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
  • Priority: Order in which credits are consumed (lowest first)

​
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 multiple credit grants exist, they are consumed in this order:
  1. Expiration date (earliest first)
  2. Priority value (lowest first)
  3. Creation date (oldest first)

​
Partial Consumption

Credits can be partially consumed. If an invoice is 100andthecustomerhas100 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

EventDescription
account.credits.grantedCredits manually granted to customer
account.credits.balance_depletedCredit 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.

Use Priority Values

Assign priorities to ensure promotional credits are used before purchased credits.

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.