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

> Create and manage credit grants for your customers

# 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:

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

5. Click **Create Grant**

### Via API

```bash theme={null}
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:**

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "expiresAt": "2025-12-31T23:59:59Z"
}
```

<Warning>
  Expired credits cannot be recovered. Set appropriate expiration windows based on your business needs.
</Warning>

### 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.

```plaintext theme={null}
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

| 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

```bash theme={null}
# 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:**

```json theme={null}
{
  "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

```bash theme={null}
curl -X POST https://api.alguna.io/credit-grants/cg_456def/void \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "reason": "Customer requested cancellation"
  }'
```

<Warning>
  Voiding removes remaining credits immediately. Already-consumed credits are not affected.
</Warning>

***

## Bulk Operations

### Import Credits

Upload a CSV to create multiple grants:

```csv theme={null}
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:

```bash theme={null}
# 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "accountId": "acc_123",
  "type": "units",
  "amount": "100000",
  "metricId": "metric_api_calls",
  "expiresAt": "2025-12-31T23:59:59Z",
  "description": "100K API calls package"
}
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Credit Consumption" icon="chart-pie" href="/credits/credit-consumption">
    Learn how credits are consumed.
  </Card>

  <Card title="Wallets" icon="wallet" href="/credits/wallets">
    Set up prepaid wallets.
  </Card>
</CardGroup>