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

A grant (or a subscription’s credit allocation) can be restricted to specific products or prices, using include and exclude rules. In the dashboard this is the Applies to / Configure Credit Filters dialog on the credit entitlement.

These filters are invoice-time only. They decide which invoice lines the grant’s credits may pay for when an invoice is produced. They do not affect the realtime credit gate: /check and /track resolve a billable metric, not a product, so a grant’s product and price filters are never evaluated there. What a grant funds at the gate is set separately — see Realtime gate funding below.The same applies to a grant made under a subscription. At invoice time the subscription scopes what the grant may pay for; for realtime draws it only records where the grant came from, and its credits are spendable against any metric its gate funding covers.

Realtime Gate Funding

Whether a grant pays for realtime /check and /track draws is a separate setting on the grant, expressed in billable metrics — the only thing the gate ever resolves. A product can sit above several metrics, which is why the invoice-time product and price filters cannot answer this question.

Setting	What the grant funds at the gate
`off`	Nothing. This is the default.
`all`	Any metric that has an active credit consumption configuration, including ones configured later.
`chosen`	Only the billable metrics listed on the grant.

off is the default, including for every grant that already exists. Turning the realtime gate on covers nothing until you opt grants into it — deliberately, so credits bought for something else never start funding the gate by surprise.

Naming a metric that has no active credit consumption configuration is allowed and returns a warning on the response: the grant saves, and that part of the filter funds nothing until the configuration exists.

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

​Product and Price Filters

​Realtime Gate Funding

​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

Product and Price Filters

Realtime Gate Funding

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