Credits Overview
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:
- Customer purchases credits: Customer buys a credit package upfront (e.g., $120,000 in prepaid credits)
- Credits are issued: Credits are immediately added to the customer's credit pool
- Usage consumes credits: As the customer uses your service, credits burn down
- 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:
- Customer commits: Customer agrees to spend a minimum amount (e.g., $120,000 annually)
- Usage is tracked: Credits are tracked as services are consumed
- Billed periodically: Customer is invoiced monthly/quarterly based on actual usage
- 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 |