For a general overview of prepaid credits and to understand if prepaid credits makes sense for your pricing model, please read the prepaid credits guide. In this guide, we’re going to walk you through setting up prepaid credits and the basic actions of adding prepaid credits. Ensure you are in Orb test mode environment before continuing with this guide.

​
Prepaid credits

In Orb, custom pricing units allow you to use multiple ledgers, a real-world currency ledger and any number of credit ledgers. Prepaid credits are a type of custom pricing unit that enables you to offer credits to your customers, which can be used to pay for product usage and services. You can create custom pricing units and enable credits in the settings page. Note that each custom pricing unit will have its own ledger, allowing you to manage and track credits separately.

​
Enabling custom pricing units

Prepaid credits work similarly to other ledgers, deducting usage from the available credit balance. However, there are key differences in plan creation and invoice display. When setting up plans with credit ledgers, you’ll need to configure a credit overage rate, which determines the conversion rate from credits to real-world currency for any overage incurred during a billing period. This ensures clarity on invoices, where the overage conversion is explicitly shown on each line item. With custom pricing units, you can set usage prices to use either credits or real-world currency. Prices set to use real-world currency won’t be included on the ledger, while prices using credits will utilize any available credit balance on the ledger. This flexibility allows you to offer various pricing options to your customers.
Once custom pricing units are configured, the setting can not be modified.
  1. Navigate to the settings page.
  2. In the Pricing units tab, click “Enable custom pricing units” and confirm.
  3. Input the identifier, display name, and short name for the new pricing unit.
  4. Confirm your new pricing unit. This unit will now be available to use as a price currency when creating a new plan.
custom-pricing-units.png

​
Including credits in a plan

When you create a plan, you can decide which prices in the plan burn down from the prepaid credit balance. Not all prices in a plan need to use prepaid credits if you are using credit ledgers. Let’s create a new plan with a price that uses prepaid credits:

​
Using a credit ledger

  1. Navigate to the plan creation flow
  2. Select the primary currency you want to invoice in (e.g. USD) and click “Enable custom pricing units”
  3. Add a usage based price using the billable metric you created, and specify Credits as the price currency
  4. Enter a conversion rate. This is the per unit conversion of the custom currency (e.g. credits) to the invoicing currency (e.g. USD). This is the amount in the invoicing currency that will be charged on the invoice at the end of the billing period if a customer goes over their prepaid credit balance.
credits-plan-creation-flow.png

​
Using a currency ledger

  1. Navigate to the plan creation flow
  2. Select the primary currency you want to invoice in (e.g. USD)
  3. Add a usage based price using the billable metric you created.
    1. In this situation, all usage based prices will deduct from the ledger.
Now, when you subscribe a customer to this plan and stream in usage events, you should see deductions in the credit ledger view or via the Fetch customer ledger API endpoint for the usage-based price. The customer’s invoice should show the fixed fee.

​
Trial credits

Trial credits are free credits you might offer your user to try out your product. Let’s add some trial credits for a customer we’ve created:
  1. Navigate to a customer’s page
  2. In the Prepaid credit balance section, click Adjust credits
adjust-credits.png
  1. Fill in an amount and $0.00 for the cost basis
    1. Cost basis refers to how much the user paid for these credits
  2. Optionally add an expiry date and description, and click Save
add-trial-credits.png
  1. Click View full credit ledger in the Credits section to see this credit increment and all future changes to the customer’s prepaid credit balance
When a customer pays for a block of prepaid credits, you can use the Adjust credits UI as described above to add paid credits. The differences compared to trial credits are:
  1. Specify a real, non-$0 cost basis for the credit block - this is how much the user paid for a single credit
    1. This is important later on when your finance team needs to pull revenue numbers
  2. Check the Create an invoice for this purchase button, specify when you want the invoice to be due, and add an optional memo
add-paid-credits.png Programatically, you can use the Add credit ledger entry API endpoint to load in trial and paid credits, and to invoice for paid credits.

​
Invoice processing for paid credits

When creating invoices for paid credits, Orb will attempt to process them synchronously if your account has automatic invoice issuance enabled. This means the invoice will be generated and finalized immediately, providing faster confirmation of the credit purchase. However, if the invoice needs to be synced to an external provider or if there’s system contention, the invoice will be processed asynchronously in the background.

​
Additional credits configuration

You can also automatically add credits based on a customer’s usage using top ups or as part of a customer’s subscription with allocations. For more information on these and advanced credits configurations, visit Orb documentation on configuring prepaid credits.