Set up Prepaid Credits

This guide walks you through implementing prepaid credits end-to-end: from enabling the wallet to monitoring depletion and handling expiration.

When to use prepaid credits: Prepaid credits are ideal when customers want to prepay for usage, you offer volume commitments, or you need to provide promotional incentives.

Overview

Prepaid credits follow this lifecycle:

Step 1: Enable the Credit Wallet

The credit wallet is enabled automatically when you grant the first credit. You can do this via:

Dashboard: Grant your first credit
API (promotional grants): Use POST /v1/contracts/{contractId}/credits/promotional/grant
Contract creation: Include creditGrantCents when creating a contract

Full credit wallet form showing prepaid credits, bonus credits, and expiration settings

# Navigate to: Customers → [Customer] → [Contract] → Credit Wallet → Grant Credits

Step 2: Configure Depletion Behavior

Choose what happens when credits run out:

Setting	Behavior
Auto Invoice	Invoice sent automatically at cycle end
Alert Only	Invoice held for manual review

Both settings:

Deduct all available credits
Send Slack alert on depletion
Allow usage to continue accruing

Configure this in the contract’s credit wallet settings or via the API.

Step 3: Monitor Credit Usage

Real-Time Balance

Check the current balance and credit blocks via API:

curl "https://api.monk.com/v1/contracts/{contractId}/credits/balance" \
  -H "Authorization: Bearer mk_live_..."

Response:

{
  "data": {
    "balance": {
      "balanceCents": 45000,
      "creditBalance": 1406.25,
      "currency": "USD",
      "blockCount": 2,
      "asOf": "2026-02-27T10:00:00.000Z"
    },
    "blocks": [
      {
        "id": "block-1",
        "status": "active",
        "priority": 1,
        "remainingCents": 45000,
        "remainingCredits": 1406.25,
        "isPromotional": false,
        "expiresAt": "2026-12-31T23:59:59.000Z"
      }
    ]
  }
}

Alerts & Thresholds

Monk sends automatic alerts when your credit balance drops below configured thresholds:

Alert	When
Threshold Crossed	Balance drops below 25%, 10%, or custom levels
Wallet Depleted	Balance reaches $0 during billing cycle
Invoice Held	End of cycle with “Alert Only” mode

Thresholds are calculated as a percentage of the High-Water Mark — the maximum balance ever reached. Default thresholds are 25%, 10%, and 0%.

Configure custom thresholds in the Credit Wallet settings. Enable Slack alerts in Settings → Integrations → Slack and subscribe to webhook events for programmatic integrations.

Ledger History

View all credit activity:

curl "https://api.monk.com/v1/contracts/{contractId}/credits/ledger" \
  -H "Authorization: Bearer mk_live_..."

The entries array shows every ledger entry:

{
  "data": {
    "totalCount": 3,
    "entries": [
      {
        "type": "usage",
        "amountCents": -8000,
        "description": "Storage usage deduction",
        "grantEntryId": "grant-1"
      },
      {
        "type": "usage",
        "amountCents": -15000,
        "description": "API usage deduction",
        "grantEntryId": "grant-1"
      },
      {
        "type": "grant",
        "amountCents": 100000,
        "description": "Q1 commitment",
        "grantEntryId": null
      }
    ]
  }
}

Step 4: Handle Expiration (Optional)

If you set an expiresAt date on grants:

What Happens at Expiration

Nightly cron checks for expired grants
Remaining balance is written off
Expiration entry is created in the ledger
Breakage revenue is recognized (paid credits only)

Example: Annual Commitment

# Paid prepaid commitments are configured during contract setup (or in dashboard).
# Public API grants are promotional-only.
curl -X POST "https://api.monk.com/v1/contracts" \
  -H "Authorization: Bearer mk_live_..." \
  -d '{
    "planId": "plan_...",
    "customerId": "cust_...",
    "startDate": "2026-03-01",
    "creditGrantCents": 120000
  }'

If the customer only uses $80,000 by year-end:

$40,000 expires
An expiration entry is created
Breakage revenue of $40,000 is recognized

Promotional credits don’t generate breakage revenue. Since they have no cost basis, there’s nothing to recognize.

Step 5: Review Invoice with Credits

When the billing cycle ends, the invoice shows:

Line Item	Amount
API Usage (10,000 calls)	$150.00
Storage (50 GB)	$25.00
Prepaid Credits Applied	-$100.00
Total Due	$75.00

For detailed credit consumption, use the Credit Usage Statement.

Best Practices

Set realistic expiration dates

Give customers enough time to use their credits. Annual commitments typically expire at year-end, quarterly at quarter-end.

Use promotional credits for incentives

Sign-up bonuses, referral rewards, and goodwill credits should be marked as promotional. This ensures correct deduction priority and accounting.

Monitor depletion proactively

Set up Slack alerts and check balances regularly. Consider reaching out to customers before they run out to discuss top-ups.

Track credit units for customer clarity

If your pricing is complex, use credit units to give customers a simpler view: “You have 500 credits remaining” vs “$160.00 remaining”.

Common Patterns

Volume Commitment

Customer commits to $10,000/year in exchange for 15% discount:

# Configure contract with discounted prepaid commitment
curl -X POST "https://api.monk.com/v1/contracts" \
  -d '{
    "planId": "plan_...",
    "customerId": "cust_...",
    "startDate": "2026-03-01",
    "creditGrantCents": 850000
  }'

Monthly Promotional Top-Up

Automatically grant bonus credits at the start of each month:

// In your backend, triggered monthly
await fetch('.../credits/promotional/grant', {
  method: 'POST',
  body: JSON.stringify({
    amountCents: 50000,
    description: `Monthly bonus top-up - ${month}`,
    expiresAt: endOfMonth(addMonths(new Date(), 3)).toISOString(),
    externalId: `monthly-bonus-${contractId}-${month}`,
  }),
});

Hybrid: Base + Overage

Grant base credits, charge overage at a higher rate:

Grant monthly credits (e.g., $500)
Configure plan with overage pricing
Credits cover base usage
Overage billed at standard rates

Next Steps

How Usage-Based Billing Works

See how credits fit into the full billing flow

Promotional Credits

Set up sign-up bonuses and referral programs

Credits API

Promotional grants and credit reporting endpoints

Enterprise Billing

Volume commitments and custom rates

Quick Start

Step-by-Step

Prepaid Credits

Enterprise

Set up Prepaid Credits

Set up Prepaid Credits

Overview

Step 1: Enable the Credit Wallet

Step 2: Configure Depletion Behavior

Step 3: Monitor Credit Usage

Real-Time Balance

Alerts & Thresholds

Ledger History

Step 4: Handle Expiration (Optional)

What Happens at Expiration

Example: Annual Commitment

Step 5: Review Invoice with Credits

Best Practices

Common Patterns

Volume Commitment

Monthly Promotional Top-Up

Hybrid: Base + Overage

Next Steps

How Usage-Based Billing Works

Promotional Credits

Credits API

Enterprise Billing

Quick Start

Step-by-Step

Prepaid Credits

Enterprise

​Set up Prepaid Credits

​Overview

​Step 1: Enable the Credit Wallet

​Step 2: Configure Depletion Behavior

​Step 3: Monitor Credit Usage

​Real-Time Balance

​Alerts & Thresholds

​Ledger History

​Step 4: Handle Expiration (Optional)

​What Happens at Expiration

​Example: Annual Commitment

​Step 5: Review Invoice with Credits

​Best Practices

​Common Patterns

​Volume Commitment

​Monthly Promotional Top-Up

​Hybrid: Base + Overage

​Next Steps

How Usage-Based Billing Works

Promotional Credits

Credits API

Enterprise Billing

Set up Prepaid Credits

Overview

Step 1: Enable the Credit Wallet

Step 2: Configure Depletion Behavior

Step 3: Monitor Credit Usage

Real-Time Balance

Alerts & Thresholds

Ledger History

Step 4: Handle Expiration (Optional)

What Happens at Expiration

Example: Annual Commitment

Step 5: Review Invoice with Credits

Best Practices

Common Patterns

Volume Commitment

Monthly Promotional Top-Up

Hybrid: Base + Overage

Next Steps