How to use the prepurchase ledger with custom credits

​

Step 1: Configuring Custom Pricing Units for Credits

1. Go to Settings > Pricing Units:
   1. You’ll find a list of real-world currencies, such as USD.
   2. Custom Pricing Units represent the credits that will be used in your pre-purchase credit ledger.
2. Create a Custom Pricing Unit:
   1. Identifier: Used programmatically to reference credits.
   2. Display Name: How the credits will appear in the Orb UI.
   3. Short Name: How credits will be denoted on invoice line items (e.g., “consumed 2 credits”).

​

Step 2: Creating a Plan with Custom Credit Pricing

1. Create a new plan: For example, “Starter with Credits.”
2. Enable Custom Pricing Units: When you add a usage-based price, you’ll see a new input called Price Currency.
   1. Select Credits instead of USD to charge using your custom credit unit.
   2. Set up overage charges: If the customer runs out of credits, you can set a price for overages. For example, you might charge $2 for every additional credit used beyond their allocation.

​

Step 3: Using Allocations to Grant Credits

• Recurring Allocation: For example, you could give the customer 10 credits each month.
• One-Time Allocation: If you only want to provide credits upon sign-up.
• No Rollover: Credits will expire at the end of the month if they aren’t used, preventing accumulation.

​

Step 4: Adding a Prepaid Credit Balance

1. Go to the Customer Profile and add a Prepaid Credit Balance:
   1. Choose Credits (or USD, depending on your pricing unit).
   2. Enter the number of credits (e.g., 10 credits) and the Cost Basis (e.g., $2 per credit).
   3. Set the Effective Date: This determines when the credit block becomes active for drawdown.
   4. Optional settings:
      1. You can add an expiration date for the credits.
      2. Optionally, generate an invoice for the credit purchase (e.g., 10 credits at $2 each will result in a $20 invoice).

​

Step 5: Creating a Subscription to Track Usage

1. Create the subscription for the customer:
   1. Select the plan that uses the credit-based pricing model (e.g., “Starter with Credits”).
   2. Align the subscription’s effective date with the credit block’s date to ensure they synchronize.
2. Ingest usage events:
   1. Orb will automatically deduct credits as usage events are sent in. If you backdate the subscription, Orb will replay the ledger to apply the appropriate credits to past usage events.

​

Step 6: Monitoring Credit Usage and Overages

1. View usage events: As usage events are ingested, credits are deducted from the balance.
   1. For example, if a customer uses 2 API calls, 2 credits will be deducted from their balance.
2. Handling overages:
   1. If the customer exhausts their credit balance, overage charges will apply based on the plan’s settings.
      1. Example: If the customer runs out of credits and uses additional API calls, they will be charged $2 per credit over the allocated amount.

​

Step 7: Reviewing Invoices with Credits Applied

1. Draft invoices: Orb will generate draft invoices that reflect the usage and credit consumption.
   1. If the customer stays within their pre-purchased credit allocation, the invoice will reflect a $0 charge.
   2. If they exceed their credit balance, overage charges will appear on the invoice.
2. Currency Matching:
   1. Orb ensures that usage for a price is deducted from the credit block’s matching currency (e.g., USD or credits).
   2. However, fixed fees will not be deducted from the credit balance.
      1. For example, USD fixed fees will not be deducted from the USD credit balance.
3. Viewing the Credit Ledger:
   1. You can view a detailed ledger showing credit increments and decrements.
   2. Pending states indicate that a usage event is still within the grace period and could change before being “committed”.