Skip to main content
FlexPrice’s credit system enables prepaid billing, promotional credits, and wallet-based usage tracking.

​
Wallets

A wallet stores a customer’s credit balance: 
{
  "customer_id": "cust_uuid",
  "type": "PREPAID",
  "currency": "USD",
  "balance": 10000,
  "conversion_rate": 100
}
Wallet types:
  • PREPAID - Customer purchases credits upfront
  • POSTPAID - Usage tracked for later billing
Conversion rate determines how credits map to currency (e.g., 100 credits = $1.00).

​
Credit Grants

Credits are added to wallets via credit grants: 
{
  "wallet_id": "wallet_uuid",
  "amount": 5000,
  "reason": "PREPAID",
  "expiry_date": "2024-12-31T23:59:59Z",
  "metadata": {
    "campaign": "welcome_bonus"
  }
}

​
Grant Types

Customer purchases credits:
{
  "amount": 10000,
  "reason": "PREPAID",
  "grant_cadence": "ONE_TIME"
}
Credits are deducted as usage occurs.

​
Credit Application

Credits are applied to invoices automatically:
1

Invoice generated

Usage and subscription charges create an invoice
2

Credits applied

Wallet credits are applied based on priority and expiry
3

Balance deducted

Credit balance is reduced by applied amount
4

Remaining due

Any remaining amount is charged via payment method

​
Application Order

  1. Priority - Higher priority grants first
  2. Expiry - Expiring grants before non-expiring
  3. FIFO - Oldest grants first
Promotional credits typically have lower priority than prepaid credits.

​
Auto Top-Up

Automatically replenish credits when balance is low: 
{
  "wallet_id": "wallet_uuid",
  "auto_topup": {
    "threshold": 1000,
    "amount": 5000,
    "invoice_customer": true
  }
}
When balance drops below threshold, automatically:
  • Grant specified credit amount
  • Optionally create invoice for payment
Auto top-up prevents service interruption for prepaid customers.

​
Credit Expiration

Credits can expire after a period: 
{
  "expiry_date": "2024-12-31T23:59:59Z",
  "expiry_policy": "DURATION"
}
Expiry policies:
  • NEVER - Credits don’t expire
  • DURATION - Expire at specific date
  • BILLING_CYCLE - Expire at end of billing period
Expired credits are automatically removed and cannot be recovered.

​
Use Cases

Grant promotional credits to free tier users:
{
  "amount": 1000,
  "reason": "PROMOTIONAL",
  "expiry_policy": "NEVER"
}
When credits run out, prompt upgrade to paid plan.
Large customers purchase credit packages:
{
  "amount": 1000000,
  "reason": "PREPAID",
  "auto_topup": {
    "threshold": 100000,
    "amount": 500000
  }
}
Auto top-up ensures uninterrupted service.
Time-limited credit offers:
{
  "amount": 2000,
  "reason": "PROMOTIONAL",
  "expiry_date": "2024-01-31T23:59:59Z",
  "metadata": {
    "campaign": "new_year_2024"
  }
}
Track campaign performance via metadata.

​
Monitoring

Track wallet health:
  • Current balance
  • Total grants issued
  • Total credits consumed
  • Expiring credits in next 30 days
  • Auto top-up triggers
Set up alerts when customer balances are running low to prevent service disruption.

Wallets Guide

Detailed wallet configuration

Grants Guide

Credit grant management

Create Wallet API

API reference for wallets

Grant Credits API

API reference for credit grants

Build docs developers (and LLMs) love

Get started for freeTalk to us