> ## Documentation Index > Fetch the complete documentation index at: https://docs.withorb.com/llms.txt > Use this file to discover all available pages before exploring further. # Credit systems Orb provides two distinct credit systems that serve different purposes in the billing lifecycle. Understanding when to use each is essential for accurate revenue recognition, customer experience, and financial reporting. ## The two systems at a glance | Aspect | Prepaid Credits (Credit Ledger) | Customer Balance | | ----------------------- | ----------------------------------------- | --------------------------------------------------- | | **Purpose** | Usage commitment and consumption tracking | Accounts receivable adjustment | | **Applied** | Before taxes, during invoice calculation | After taxes, at invoice issuance | | **Revenue recognition** | Yes, recognized as credits are consumed | No impact on revenue | | **Expiration** | Supports expiration dates | Never expires | | **Currency** | Real or virtual currencies | Customer's billing currency only | | **Audit trail** | Append-only ledger with sequence numbers | Transaction history with balance snapshots | | **Typical use** | Prepaid usage commitments, trial credits | Refunds, goodwill credits, small balance carryovers | ## Prepaid credits (Credit Ledger) The prepaid credit system is designed for customers who commit to usage upfront. Credits are organized into **blocks** with optional expiration dates and cost basis, stored in an **append-only ledger** that provides a complete audit trail. ### 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 ```json theme={null} // 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 Customer balance is a simpler system that acts like a digital wallet for accounts receivable adjustments. It represents credit or debit amounts that modify what the customer owes on their next invoice. ### 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 ```json theme={null} // 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 Understanding where each credit system applies in the invoice calculation pipeline is critical: ```text theme={null} 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 A customer has: * \$500 in prepaid credits (Credit Ledger) * \$100 in customer balance (from a previous refund) Invoice calculation: ```text theme={null} 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 A customer has a \$300 minimum on their plan and \$200 in prepaid credits. Invoice calculation: ```text theme={null} Usage charges: $150 Apply minimum: $300 (minimum kicks in) - Prepaid credits: $200 = Amount due: $100 ``` Note: The minimum is applied *before* prepaid credits. This prevents customers from using credits to avoid contractual minimums, while still allowing the credits to reduce the total amount due. ### Scenario 3: Prepaid credits with virtual currency A customer has 1,000 compute credits (virtual currency) with a \$0.50 conversion rate. Invoice calculation: ```text theme={null} 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 If you've been using customer balance for usage commitments, consider migrating to prepaid credits for: * Better revenue recognition tracking * Expiration date support * Multiple currency/pricing unit support * Detailed consumption audit trail ### Moving from prepaid credits to customer balance Customer balance is simpler but loses: * 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.