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

# Usage Metering Quick Start

> Bill customers based on actual consumption

Bill customers based on what they actually use—API calls, storage, compute hours, or any measurable unit. This guide walks you through setting up usage-based billing in the dashboard.

***

## How Usage Billing Works

```mermaid theme={null}
graph LR
    A[Customer Uses Product] --> B[Usage Events Sent]
    B --> C[Alguna Aggregates Usage]
    C --> D[Invoice Generated]
    D --> E[Customer Pays]
```

1. **Usage occurs** - Customer uses your product (API calls, storage, etc.)
2. **Events recorded** - Usage events are sent to Alguna
3. **Usage aggregated** - Alguna totals usage for the billing period
4. **Invoice generated** - Charges calculated based on your pricing
5. **Payment collected** - Customer pays for their usage

***

## Step 1: Create a Billable Metric

Define what you want to measure:

1. Navigate to **Settings → Billable Metrics**
2. Click **Create Metric**
3. Fill in the details:
   * **Name**: What you're measuring (e.g., "API Calls")
   * **Code**: Unique identifier (e.g., `api_calls`)
   * **Aggregation Type**: How to count usage

### Aggregation Types

| Type             | Description             | Example                     |
| ---------------- | ----------------------- | --------------------------- |
| **Count**        | Count number of events  | Number of API requests      |
| **Sum**          | Sum a property value    | Total GB transferred        |
| **Unique Count** | Count unique values     | Unique active users         |
| **Max**          | Maximum value in period | Peak concurrent connections |

4. Click **Create**

***

## Step 2: Create a Usage-Based Product

1. Navigate to **Products**
2. Click **New Product**
3. Configure:
   * **Name**: Product name (e.g., "API Usage")
   * **Fee Type**: Select **Metered**
   * **Metric**: Select the metric you created
   * **Pricing Model**: Choose how to price usage

### Pricing Models for Usage

| Model        | Description                           | Example                            |
| ------------ | ------------------------------------- | ---------------------------------- |
| **Per Unit** | Fixed price per unit                  | \$0.001 per API call               |
| **Tiered**   | Different prices at different volumes | First 1,000 free, then \$0.01 each |
| **Volume**   | All units at same rate based on total | 0-1000: $0.01, 1001+: $0.008 each  |
| **Package**  | Price per bundle of units             | \$10 per 1,000 calls               |

4. Click **Save**

***

## Step 3: Add to a Plan

1. Navigate to **Plans**
2. Select or create a plan
3. Click **Add Product**
4. Select your usage-based product
5. Click **Save**

***

## Step 4: Send Usage Events

Work with your development team to send usage events. They'll need:

* **Metric Code**: The code you defined (e.g., `api_calls`)
* **Account ID**: The customer's Alguna account ID
* **Timestamp**: When the usage occurred

See the [Events API Reference](/api-reference/events/ingest) for technical details.

***

## Viewing Customer Usage

### Current Period Usage

1. Navigate to **Customers → \[Customer Name]**
2. Click the **Usage** tab
3. View:
   * Usage by metric
   * Estimated charges
   * Usage trends

### Historical Usage

1. Navigate to **Reports → Usage**
2. Filter by customer, metric, or date range
3. Export data if needed

***

## Common Use Cases

### API Billing

| Metric       | Aggregation | Pricing                      |
| ------------ | ----------- | ---------------------------- |
| API Requests | Count       | Tiered (free tier + overage) |

### Storage Billing

| Metric       | Aggregation | Pricing            |
| ------------ | ----------- | ------------------ |
| Storage (GB) | Max         | Per unit per month |

### Compute Billing

| Metric        | Aggregation | Pricing  |
| ------------- | ----------- | -------- |
| Compute Hours | Sum         | Per unit |

### Active User Billing

| Metric       | Aggregation  | Pricing            |
| ------------ | ------------ | ------------------ |
| Active Users | Unique Count | Per user per month |

***

## Troubleshooting

### No Usage Showing

1. Verify usage events are being sent (check with your dev team)
2. Confirm the metric code matches exactly
3. Check timestamps are within the billing period

### Incorrect Charges

1. Review the metric aggregation type
2. Check pricing model configuration
3. Verify billing period dates

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Clear Naming" icon="tag">
    Use descriptive metric names customers will understand.
  </Card>

  <Card title="Test First" icon="flask">
    Test usage tracking in sandbox before production.
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Regularly review usage reports for anomalies.
  </Card>

  <Card title="Communicate Pricing" icon="message">
    Clearly explain usage-based charges to customers.
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Define Metrics" icon="gauge" href="/billable-metrics/define-metrics">
    Learn more about metric configuration.
  </Card>

  <Card title="Pricing Models" icon="calculator" href="/pricing/pricing-models">
    Explore pricing options.
  </Card>
</CardGroup>