Credit systems

​

The two systems at a glance

​

Prepaid credits (Credit Ledger)

​

How prepaid credits work

1. Credits are added via direct API calls, subscription allocations, or automatic top-ups
2. Blocks are created with an amount, effective date, and optional expiration
3. Usage accrues throughout the billing period
4. At invoice calculation, credits are deducted from usage charges (in-arrears only)
5. Remaining usage after credit deduction becomes the amount due

​

Key characteristics

• Scoped by currency: Each customer can have multiple credit ledgers, one per pricing unit (e.g., USD, compute credits, storage credits)
• Block ordering: Credits are deducted in a specific order—blocks with item filters first, then soonest-expiring, then by cost basis, then creation time
• In-arrears only: Prepaid credits apply only to in-arrears charges (usage-based and fixed fees billed at period end)
• Pending vs committed: Entries remain pending during the reporting grace period, then become immutable once committed

​

When to use prepaid credits

• Usage commitments: Customer prepays for a usage allocation (e.g., 10,000 API calls for $500)
• Trial credits: Provide credits that expire after a trial period
• Enterprise drawdown: Large prepaid pools that draw down over months or years
• Multi-currency scenarios: Track separate credit pools for different product SKUs

// Example: Create a prepaid credit block
POST /customers/{customer_id}/credits/ledger
{
  "entry_type": "increment",
  "amount": 10000,
  "currency": "USD",
  "effective_date": "2024-01-01",
  "expiry_date": "2024-12-31",
  "per_unit_cost_basis": "0.05",
  "description": "Annual prepaid commitment"
}

​

Customer balance

​

How customer balance works

1. Balance is modified via manual adjustments, credit notes on paid invoices, or small balance carryovers
2. At invoice issuance, the balance is applied to reduce (or increase) the amount due
3. The final amount due reflects the balance adjustment after taxes

​

Key characteristics

• Single currency: Always in the customer’s billing currency
• Post-tax application: Applied after all line item calculations and taxes
• No revenue impact: Does not affect revenue recognition—strictly an AR adjustment
• Immediate effect: Applied to the next issued invoice automatically

​

When to use customer balance

• Refunds via credit notes: When a credit note is issued on a paid invoice, the refund amount goes to customer balance
• Goodwill credits: One-time credits for customer satisfaction issues
• Corrections: Manual adjustments to reconcile billing discrepancies
• Small balance carryovers: Amounts below payment minimums are carried forward

// Example: Add a goodwill credit to customer balance
POST /customers/{customer_id}/balance_transactions
{
  "type": "increment",
  "amount": "50.00",
  "description": "Goodwill credit for service interruption"
}

​

Calculation order on an invoice

1. Quantity calculation      → Billable metric evaluation
2. Subtotal                  → Quantity × rate
3. Adjustments               → Discounts, minimums, maximums
4. Prepaid credits           → Deducted from adjusted subtotal ← PREPAID CREDITS
5. Currency conversion       → Virtual to real currency
6. Previously invoiced       → Subtract threshold billing amounts
7. Tax                       → Tax provider calculation
8. Customer balance          → Applied to final amount due ← CUSTOMER BALANCE

​

Common scenarios

​

Scenario 1: Customer with both systems

• $500 in prepaid credits (Credit Ledger)
• $100 in customer balance (from a previous refund)

Usage charges:           $800
- Prepaid credits:       $500
= Subtotal before tax:   $300
+ Tax (10%):             $30
= Total with tax:        $330
- Customer balance:      $100
= Amount due:            $230

​

Scenario 2: Credits don’t cover the minimum

Usage charges:           $150
Apply minimum:           $300  (minimum kicks in)
- Prepaid credits:       $200
= Amount due:            $100

​

Scenario 3: Prepaid credits with virtual currency

Compute usage:           800 credits
- Prepaid credits:       800 credits (deducted)
= Overage:               0 credits
= Converted to USD:      $0

// If overage existed:
Compute usage:           1,200 credits
- Prepaid credits:       1,000 credits
= Overage:               200 credits
= Converted to USD:      $100 (200 × $0.50)

​

Migrating between systems

​

Moving from customer balance to prepaid credits

• Better revenue recognition tracking
• Expiration date support
• Multiple currency/pricing unit support
• Detailed consumption audit trail

​

Moving from prepaid credits to customer balance

• Expiration dates (credits never expire)
• Cost basis tracking (no revenue recognition)
• Block-level granularity (just a running total)

​

Best practices

1. Use prepaid credits for usage commitments: When customers prepay for usage, use the credit ledger for proper revenue recognition and expiration handling.
2. Use customer balance for AR adjustments: Refunds, corrections, and goodwill credits that don’t represent usage commitments belong in customer balance.
3. Don’t mix purposes: Avoid using customer balance as a workaround for prepaid credits, as this will cause revenue recognition issues.
4. Monitor credit block expiration: Set up balance alerts to notify customers before their prepaid credits expire.
5. Consider cost basis: When creating prepaid credit blocks, set the cost basis for accurate revenue reporting—trial credits typically have $0 cost basis.