> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Credits & Wallets Overview
> Understand how credits and wallets work in Alguna
# 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.
```plaintext theme={null}
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.
```plaintext theme={null}
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
```mermaid theme={null}
graph LR
A[Grant Created] --> B[Active]
B --> C{Usage?}
C -->|Consumed| D[Partially Used]
D --> E{Depleted?}
E -->|Yes| F[Exhausted]
E -->|No| B
B --> G{Expired?}
G -->|Yes| H[Expired]
C -->|No Usage| G
```
### 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 $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:**
```json theme={null}
{
"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:**
```json theme={null}
{
"type": "account.credits.balance_depleted",
"timestamp": "2024-08-03T20:26:10Z",
"data": {
"accountId": "aBsZxlLh",
"amount": "0",
"type": "units"
}
}
```
***
## Best Practices
Always set reasonable expiration dates to prevent indefinite liabilities on your books.
Assign priorities to ensure promotional credits are used before purchased credits.
Set up webhooks to notify customers when balances are depleted.
Clearly communicate credit terms, including expiration and non-transferability.
***
## Next Steps
Learn how to create and manage credit grants.
Understand how credits are consumed.
Set up prepaid wallets for customers.
Explore the Wallets API.