Credit Consumption

Credits are automatically consumed when invoices are generated or usage events occur. This guide explains the consumption mechanics and how to track credit usage.

How Credits Are Consumed

Monetary Credits

Monetary credits are applied when an invoice is finalized:

Invoice is generated with line items
System calculates total amount due
Available credits are applied (by priority)
Remaining balance charged to payment method

Invoice Total:     $500.00
Credits Applied:  -$300.00
Amount Due:        $200.00

Unit Credits

Unit credits are consumed as usage events are ingested:

Usage event is received
Event is matched to a metric
Credits for that metric are decremented
If credits exhausted, usage is billed normally

API Calls Made:    15,000
Credits Available: 10,000
Credits Used:     -10,000
Billable Usage:     5,000

Consumption Priority

When multiple credit grants exist, consumption follows this order:

Priority Rules

Expiration date - Earliest expiring first
Priority value - Lowest number first
Creation date - Oldest first

Example

Grant A: $200, Priority 10, Expires 2025-06-30
Grant B: $150, Priority 5,  Expires 2025-12-31
Grant C: $100, Priority 10, Expires 2025-03-31

Invoice: $350

Consumption order:
1. Grant B: $150 (lowest priority)
2. Grant C: $100 (same priority as A, but expires sooner)
3. Grant A: $100 (remaining needed)

Result: All grants partially/fully consumed

Automatic vs Manual Application

Automatic Application

By default, credits are automatically applied to invoices:

When invoice transitions to pending status
Before payment is attempted
Full available balance is applied

To disable automatic application for an account:

curl -X PATCH https://api.alguna.io/accounts/acc_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "creditSettings": {
      "autoApply": false
    }
  }'

Manual Application

When auto-apply is disabled, apply credits manually:

curl -X POST https://api.alguna.io/invoices/inv_456/apply-credits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "amount": "250.00"
  }'

Tracking Consumption

Credit Ledger

Every credit transaction is recorded in the ledger:

curl https://api.alguna.io/accounts/acc_123/credits/ledgers \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "entries": [
    {
      "id": "cle_001",
      "grantId": "cg_456",
      "type": "consumption",
      "amount": "-150.00",
      "balanceAfter": "350.00",
      "reference": {
        "type": "invoice",
        "id": "inv_789"
      },
      "createdAt": "2024-01-20T14:30:00Z"
    },
    {
      "id": "cle_002",
      "grantId": "cg_456",
      "type": "grant",
      "amount": "500.00",
      "balanceAfter": "500.00",
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ]
}

Ledger Entry Types

Type	Description
`grant`	Credit grant created
`consumption`	Credits used for invoice/usage
`expiration`	Credits expired
`void`	Grant voided
`adjustment`	Manual adjustment

Invoice Credit Display

When credits are applied to an invoice, they appear as a line item:

{
  "id": "inv_789",
  "total": "500.00",
  "creditsApplied": "300.00",
  "amountDue": "200.00",
  "lineItems": [
    {
      "description": "Platform subscription",
      "amount": "500.00"
    }
  ],
  "creditApplications": [
    {
      "grantId": "cg_456",
      "amount": "300.00",
      "description": "Q1 promotional credit"
    }
  ]
}

Unit Credit Consumption

For usage-based products, unit credits are consumed in real-time:

Configuration

Link credits to specific metrics:

curl -X POST https://api.alguna.io/credit-grants \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "accountId": "acc_123",
    "type": "units",
    "amount": "100000",
    "metricId": "metric_api_calls"
  }'

Consumption Flow

Checking Unit Balance

curl https://api.alguna.io/accounts/acc_123/credits/balances \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "type": "units",
    "metricId": "metric_api_calls"
  }'

Response:

{
  "type": "units",
  "metricId": "metric_api_calls",
  "available": 45000,
  "consumed": 55000,
  "pending": 0
}

Pending Consumption

Some consumption is recorded as “pending” before being confirmed:

When Pending Occurs

Pre-authorization for large transactions
Usage aggregation periods
Invoice draft state

Confirming Pending

Pending consumption is automatically confirmed when:

Invoice is finalized
Billing period closes
Manual confirmation via API

curl -X POST https://api.alguna.io/credits/consumption/confirm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "consumptionId": "cc_123"
  }'

Rolling Back Pending

If an invoice is voided or usage is corrected:

curl -X POST https://api.alguna.io/credits/consumption/rollback \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "consumptionId": "cc_123"
  }'

Consumption Reports

Dashboard

View consumption analytics at Reports > Credits:

Consumption by period
Top consumers
Expiration forecasts
Grant utilization rates

API Export

curl https://api.alguna.io/reports/credits/consumption \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "startDate": "2024-01-01",
    "endDate": "2024-03-31",
    "format": "csv"
  }'

Webhooks

Monitor consumption with webhooks:

Event	Description
`credits.consumed`	Credits applied to invoice/usage
`credits.balance_low`	Balance below threshold
`credits.balance_depleted`	Balance reached zero

Balance Threshold Configuration

Set alerts when balance falls below a threshold:

curl -X PATCH https://api.alguna.io/accounts/acc_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "creditSettings": {
      "lowBalanceThreshold": "100.00",
      "lowBalanceNotification": true
    }
  }'

Common Scenarios

Partial Credit Application

Apply only part of available credits:

curl -X POST https://api.alguna.io/invoices/inv_456/apply-credits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "amount": "100.00",
    "grantId": "cg_789"
  }'

Credit Refund

If an invoice is voided after credits were applied:

System automatically reverses the credit consumption
Credits are returned to the original grant
Ledger entry records the reversal

{
  "type": "reversal",
  "amount": "150.00",
  "reference": {
    "type": "invoice_void",
    "id": "inv_456"
  }
}

​Credit Consumption

​How Credits Are Consumed

​Monetary Credits

​Unit Credits

​Consumption Priority

​Priority Rules

​Example

​Automatic vs Manual Application

​Automatic Application

​Manual Application

​Tracking Consumption

​Credit Ledger

​Ledger Entry Types

​Invoice Credit Display

​Unit Credit Consumption

​Configuration

​Consumption Flow

​Checking Unit Balance

​Pending Consumption

​When Pending Occurs

​Confirming Pending

​Rolling Back Pending

​Consumption Reports

​Dashboard

​API Export

​Webhooks

​Balance Threshold Configuration

​Common Scenarios

​Partial Credit Application

​Credit Refund

​Next Steps

Wallets

Credit Grants