Skip to main content

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.

​
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

  1. Navigate to Customers and select a customer
  2. Click the Credits tab
  3. Click Add Credit Grant
  4. Fill in the grant details:
FieldDescriptionRequired
TypeMonetary or UnitsYes
AmountCredit value or quantityYes
CurrencyCurrency code (for monetary)Yes (monetary)
Expiration DateWhen credits expireNo
PriorityConsumption order (lower = first)No
DescriptionInternal noteNo
  1. 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

StatusDescription
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:
  1. Go to Settings > Notifications
  2. Enable Credit Expiration Warning
  3. 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:
  1. Grant C (priority 10, earliest expiration)
  2. Grant A (priority 10, later expiration)
  3. Grant B (priority 20)

​
Priority Best Practices

ScenarioRecommended Priority
Promotional credits1-10 (consume first)
Purchased credits50-100 (preserve longer)
Loyalty rewards20-30
Service credits5 (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

  1. Go to Customers > [Customer] > Credits
  2. Find the grant and click … menu
  3. Select Void Grant
  4. 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:
  1. Go to Reports > Credits
  2. Set date range and filters
  3. Click Export CSV

​
Common Scenarios

​
Promotional Campaign

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.