Credit Grants
Credit grants allow you to allocate credits to customer accounts. This guide covers creating, managing, and tracking credit grants.
Creating a Credit Grant
From the Dashboard
- Navigate to Customers and select a customer
- Click the Credits tab
- Click Add Credit Grant
- Fill in the grant details:
| Field | Description | Required |
|---|
| Type | Monetary or Units | Yes |
| Amount | Credit value or quantity | Yes |
| Currency | Currency code (for monetary) | Yes (monetary) |
| Expiration Date | When credits expire | No |
| Priority | Consumption order (lower = first) | No |
| Description | Internal note | No |
- Click Create Grant
Via API
curl -X POST https://api.alguna.io/credit-grants \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"accountId": "acc_123abc",
"type": "monetary",
"amount": "500.00",
"currency": "USD",
"expiresAt": "2025-12-31T23:59:59Z",
"priority": 10,
"description": "Q1 promotional credit"
}'
{
"id": "cg_456def",
"accountId": "acc_123abc",
"type": "monetary",
"amount": "500.00",
"remainingAmount": "500.00",
"currency": "USD",
"expiresAt": "2025-12-31T23:59:59Z",
"priority": 10,
"status": "active",
"description": "Q1 promotional credit",
"createdAt": "2024-01-15T10:30:00Z"
}
Grant Types
Monetary Credits
Monetary credits are applied directly to invoices as a payment method.
{
"type": "monetary",
"amount": "1000.00",
"currency": "USD"
}
- Must specify a currency
- Applied at invoice payment time
- Reduces the amount due
- Appears as “Credit Applied” on invoice
Unit Credits
Unit credits are consumed against usage-based products and metrics.
{
"type": "units",
"amount": "50000",
"metricId": "metric_api_calls"
}
- Can be tied to a specific metric
- Consumed as usage events are recorded
- Tracked separately from monetary balance
- Ideal for prepaid usage packages
Grant Status
| Status | Description |
|---|
active | Credits available for use |
exhausted | All credits consumed |
expired | Credits expired unused |
voided | Grant manually voided |
Expiration Handling
Setting Expiration
Expiration dates are optional but recommended for financial planning.
{
"expiresAt": "2025-12-31T23:59:59Z"
}
Expired credits cannot be recovered. Set appropriate expiration windows based on your business needs.
Expiration Notifications
Configure webhooks to notify customers before credits expire:
- Go to Settings > Notifications
- Enable Credit Expiration Warning
- Set warning period (e.g., 30 days before)
Priority System
The priority value determines the order in which credits are consumed when multiple grants exist.
Grant A: Priority 10, Expires 2025-06-30
Grant B: Priority 20, Expires 2025-03-31
Grant C: Priority 10, Expires 2025-01-31
- Grant C (priority 10, earliest expiration)
- Grant A (priority 10, later expiration)
- Grant B (priority 20)
Priority Best Practices
| Scenario | Recommended Priority |
|---|
| Promotional credits | 1-10 (consume first) |
| Purchased credits | 50-100 (preserve longer) |
| Loyalty rewards | 20-30 |
| Service credits | 5 (use immediately) |
Viewing Credit Balances
Dashboard
Navigate to Customers > [Customer] > Credits to see:
- Total available balance
- Breakdown by grant
- Consumption history
- Upcoming expirations
API
# Get all credit grants for an account
curl https://api.alguna.io/accounts/acc_123/credits/grants \
-H "Authorization: Bearer YOUR_API_KEY"
# Get aggregated balance
curl https://api.alguna.io/accounts/acc_123/credits/balance \
-H "Authorization: Bearer YOUR_API_KEY"
{
"accountId": "acc_123abc",
"balances": [
{
"type": "monetary",
"currency": "USD",
"available": "750.00",
"pending": "100.00",
"expiringWithin30Days": "200.00"
},
{
"type": "units",
"metricId": "metric_api_calls",
"available": "45000",
"pending": "5000"
}
]
}
Voiding a Grant
To void an unused or partially used grant:
Dashboard
- Go to Customers > [Customer] > Credits
- Find the grant and click … menu
- Select Void Grant
- Confirm the action
API
curl -X POST https://api.alguna.io/credit-grants/cg_456def/void \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"reason": "Customer requested cancellation"
}'
Voiding removes remaining credits immediately. Already-consumed credits are not affected.
Bulk Operations
Import Credits
Upload a CSV to create multiple grants:
account_id,type,amount,currency,expires_at,description
acc_123,monetary,500.00,USD,2025-12-31,Q1 promo
acc_456,monetary,250.00,USD,2025-12-31,Q1 promo
acc_789,units,10000,,2025-06-30,API package
Export Credit Report
Generate a report of all credit grants and balances:
- Go to Reports > Credits
- Set date range and filters
- Click Export CSV
Common Scenarios
Award credits to all customers in a segment:
# Using the bulk API
curl -X POST https://api.alguna.io/credit-grants/bulk \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"grants": [
{"accountId": "acc_1", "type": "monetary", "amount": "100", "currency": "USD"},
{"accountId": "acc_2", "type": "monetary", "amount": "100", "currency": "USD"}
],
"expiresAt": "2025-03-31T23:59:59Z",
"description": "Spring promotion"
}'
Service Credit for Outage
Issue credits to affected customers:
{
"accountId": "acc_123",
"type": "monetary",
"amount": "50.00",
"currency": "USD",
"priority": 1,
"description": "Service credit - 2024-01-15 outage"
}
Prepaid API Package
Sell a block of API calls:
{
"accountId": "acc_123",
"type": "units",
"amount": "100000",
"metricId": "metric_api_calls",
"expiresAt": "2025-12-31T23:59:59Z",
"description": "100K API calls package"
}
Next Steps
