---
title: Credits Overview
slug: credits-overview
docTags: 
createdAt: 2026-02-13T04:24:46.989Z
---

The Nue Credits API enables you to build customer-facing experiences that provide real-time visibility into prepaid credit balances, consumption patterns, and credit burndown. These endpoints are essential for creating transparent, self-service portals for customers using usage-based billing with committed credits.

## Understanding Credits in Nue

Nue supports two primary credit models for usage-based billing:

### Credit Burndown (Prepaid)

Customers **prepay** for credits that are consumed as they use your services:

1. **Customer purchases credits**: Customer buys a credit package upfront (e.g., $120,000 in prepaid credits)
2. **Credits are issued**: Credits are immediately added to the customer's credit pool
3. **Usage consumes credits**: As the customer uses your service, credits burn down
4. **Real-time tracking**: Customer can monitor their remaining balance and consumption rate

**Ideal for:**

- Customers who want to lock in pricing and avoid monthly invoicing
- Usage-based services with predictable consumption patterns
- Customers seeking budget certainty

### Committed Credits (Post-Paid)

Customers **commit** to a minimum spend over a period and receive discounted rates:

1. **Customer commits**: Customer agrees to spend a minimum amount (e.g., $120,000 annually)
2. **Usage is tracked**: Credits are tracked as services are consumed
3. **Billed periodically**: Customer is invoiced monthly/quarterly based on actual usage
4. **Commitment reconciliation**: At period end, ensure minimum commitment is met

**Ideal for:**

- Enterprise customers with significant usage volumes
- Customers who want flexibility without upfront payment
- Negotiated discount agreements based on committed spend

## Customer Use Cases for Real-Time Credits Data

### 1. Self-Service Credit Balance Dashboard

Enable customers to monitor their prepaid credit investments in real-time:

**What customers need to see:**

- Current available balance across all credit pools
- Total credits purchased vs. consumed
- Pending credits (future-dated commitments)
- Credit expiration dates and amounts at risk

**Why it matters:**

- Customers can plan their usage to maximize value
- Reduces support inquiries about "how many credits do I have left?"
- Builds trust through transparency

**API endpoints to use:**

- `GET /customers/{customerId}/account-credit-pools` - Show all credit pools and balances
- `GET /customers/{customerId}/credit-stats` - Display aggregated statistics

### 2. Credit Consumption Analytics

Help customers understand their spending patterns and optimize usage:

**What customers need to see:**

- Daily/weekly/monthly credit consumption trends
- Consumption by product or service
- Burn rate projections (when will credits run out?)
- Comparison to previous periods

**Why it matters:**

- Customers can identify cost optimization opportunities
- Enables proactive purchasing decisions before credits run out
- Helps customers validate they're getting expected value

**API endpoints to use:**

- `GET /customers/{customerId}/credit-flows` - Retrieve consumption history
- `GET /customers/{customerId}/credit-flows?includes=product` - Show consumption by product

### 3. Credit Expiration Alerts

Notify customers about credits approaching expiration:

**What customers need to see:**

- Credits expiring in next 30/60/90 days
- Total value at risk of expiration
- Recommendations to use or extend credits

**Why it matters:**

- Prevents customers from losing prepaid value
- Drives engagement and usage
- Reduces disputes and refund requests

**API endpoints to use:**

- `GET /customers/{customerId}/credit-flows` - Filter for credits with upcoming expiration dates
- `GET /customers/{customerId}/account-credit-pools` - Check credit pool details including validity periods

### 4. Usage Forecasting and Recommendations

Provide intelligent insights to help customers manage their credit commitments:

**What customers need to see:**

- Projected credit depletion date based on current burn rate
- Recommendations to increase/decrease usage
- Alerts when consumption deviates from expected patterns

**Why it matters:**

- Helps customers avoid service interruptions
- Enables better budgeting and planning
- Creates opportunities for upsell conversations

**API endpoints to use:**

- `GET /customers/{customerId}/credit-stats` - Get aggregated consumption metrics
- `GET /customers/{customerId}/credit-flows` - Analyze consumption patterns over time

### 5. Multi-Pool Credit Management

For customers with multiple credit pools (e.g., different regions, products, or commitment tiers):

**What customers need to see:**

- Breakdown by credit pool
- Which pools are being consumed fastest
- Recommendations to rebalance usage across pools

**Why it matters:**

- Customers with complex agreements need granular visibility
- Prevents inefficient credit utilization
- Supports multi-product or multi-region deployments

**API endpoints to use:**

- `GET /customers/{customerId}/account-credit-pools` - List all pools
- `GET /customers/{customerId}/credit-stats?accountPoolIds=[...]` - Compare statistics across pools

## Available Endpoints

| Endpoint                                           | Use Case                                          |
| -------------------------------------------------- | ------------------------------------------------- |
| `GET /customers/{customerId}/account-credit-pools` | Display current credit pool balances and details  |
| `GET /customers/{customerId}/credit-flows`         | Show transaction history and consumption patterns |
| `GET /customers/{customerId}/credit-stats`         | Present aggregated statistics and health metrics  |