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"
  }'

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
`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

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

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"
}

​Credit Grants

​Creating a Credit Grant

​From the Dashboard

​Via API

​Grant Types

​Monetary Credits

​Unit Credits

​Grant Status

​Expiration Handling

​Setting Expiration

​Expiration Notifications

​Priority System

​Priority Best Practices

​Viewing Credit Balances

​Dashboard

​API

​Voiding a Grant

​Dashboard

​API

​Bulk Operations

​Import Credits

​Export Credit Report

​Common Scenarios

​Promotional Campaign

​Service Credit for Outage

​Prepaid API Package

​Next Steps

Credit Consumption

Wallets

Credit Grants

Creating a Credit Grant

From the Dashboard

Via API

Grant Types

Monetary Credits

Unit Credits

Grant Status

Expiration Handling

Setting Expiration

Expiration Notifications

Priority System

Priority Best Practices

Viewing Credit Balances

Dashboard

API

Voiding a Grant

Dashboard

API

Bulk Operations

Import Credits

Export Credit Report

Common Scenarios

Promotional Campaign

Service Credit for Outage

Prepaid API Package

Next Steps