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 UnitsYes 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" }'
Response: { "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" }
Characteristics:
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" }
Characteristics:
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 activeCredits available for use exhaustedAll credits consumed expiredCredits expired unused voidedGrant 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
Consumption order:
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"
Balance Response: { "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
Credit Consumption Learn how credits are consumed.
Wallets Set up prepaid wallets.
