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

# Credits Quick Start

> Offer prepaid balances and promotional credits to customers

Credits allow you to offer prepaid balances, promotional incentives, and consumption-based packages. This guide walks you through granting credits and managing balances in the dashboard.

***

## How Credits Work

```mermaid theme={null}
graph LR
    A[Grant Credits] --> B[Credits Available]
    B --> C[Invoice Generated]
    C --> D[Credits Auto-Applied]
    D --> E[Remaining Charged]
```

1. **Grant credits** - Add credits to a customer's account
2. **Invoice generated** - Customer incurs charges
3. **Credits applied** - Available credits automatically reduce the invoice
4. **Remainder charged** - Any balance charged to payment method

***

## Granting Credits

### Step 1: Navigate to Customer

1. Go to **Customers**
2. Click on the customer's name
3. Select the **Credits** tab

### Step 2: Create Credit Grant

1. Click **Grant Credits**
2. Fill in the details:

| Field          | Description                              |
| -------------- | ---------------------------------------- |
| **Type**       | Monetary (\$) or Units (API calls, etc.) |
| **Amount**     | Credit value to grant                    |
| **Currency**   | USD, EUR, etc. (for monetary)            |
| **Expiration** | When credits expire (optional)           |
| **Reason**     | Internal note (e.g., "Welcome credit")   |

3. Click **Grant**

***

## Credit Types

### Monetary Credits

Credits with a dollar value that reduce invoice totals.

**Use cases:**

* Welcome bonuses (\$50 credit for new customers)
* Service credits (compensation for outages)
* Referral rewards

### Unit Credits

Credits for specific usage quantities.

**Use cases:**

* API call packages (10,000 calls included)
* Storage allowances (50 GB included)
* Message credits

***

## Viewing Credit Balances

### Customer Credit Tab

1. Navigate to **Customers → \[Customer Name] → Credits**
2. View:
   * **Available balance** - Credits ready to use
   * **Pending** - Credits applied to unpaid invoices
   * **Expiring soon** - Credits expiring within 30 days
   * **Transaction history** - All credit activity

### Reports

1. Navigate to **Reports → Credits**
2. View credit usage across all customers
3. Filter by date range, customer, or credit type

***

## Automatic Credit Application

Credits are automatically applied when invoices are generated:

1. Invoice total calculated
2. Available credits checked
3. Credits expiring soonest are applied first
4. Remaining balance charged to payment method

**Example:**

|                  | Amount       |
| ---------------- | ------------ |
| Invoice subtotal | \$150.00     |
| Credit applied   | -\$50.00     |
| **Total due**    | **\$100.00** |

***

## Credit Expiration

### Setting Expiration

When granting credits, optionally set an expiration date. Expired credits are automatically removed and cannot be recovered.

### Best Practices

| Credit Type       | Recommended Expiration |
| ----------------- | ---------------------- |
| Welcome credits   | 90 days                |
| Referral bonuses  | 6 months               |
| Purchased credits | 12 months or never     |
| Service credits   | 6 months               |

***

## Voiding Credits

To remove unused credits:

1. Navigate to **Customers → \[Customer Name] → Credits**
2. Find the credit grant
3. Click the **⋮** menu → **Void**
4. Enter reason and confirm

<Warning>
  Voiding removes remaining credits immediately. Credits already applied to invoices are not affected.
</Warning>

***

## Common Use Cases

### Welcome Credits

Give new customers a credit to try your service:

1. Navigate to new customer's profile
2. Grant \$25 monetary credit
3. Set 90-day expiration
4. Add reason: "Welcome credit"

### Service Compensation

Compensate customers for issues:

1. Navigate to affected customer
2. Grant appropriate credit amount
3. Add reason with incident reference

### Prepaid Packages

Sell credit packages to customers:

1. Grant unit credits (e.g., 10,000 API calls)
2. Set 12-month expiration
3. Add reason: "Purchased package"

***

## Webhooks

Receive notifications about credit events:

| Event                              | When Sent                   |
| ---------------------------------- | --------------------------- |
| `account.credits.granted`          | Credits added to customer   |
| `account.credits.balance_depleted` | Credit balance reaches zero |

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Set Expirations" icon="calendar">
    Always set reasonable expiration dates to manage liability.
  </Card>

  <Card title="Document Reasons" icon="file-lines">
    Always add clear reasons for audit trails.
  </Card>

  <Card title="Communicate Terms" icon="message">
    Tell customers about credit expiration and terms.
  </Card>

  <Card title="Monitor Balances" icon="chart-line">
    Review credit usage regularly in Reports.
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Credits Overview" icon="coins" href="/credits/overview">
    Learn more about the credit system.
  </Card>

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