Skip to main content
This feature is in early access.Scoped credits are currently available to a limited set of customers. If you’re interested in enabling this feature or have feedback, please reach out to your Orb account team or contact support.

​
Overview

Scoped credits allow you to control how prepaid balances are consumed across different products and SKUs. When creating a credit block, you can scope it to specific items (products or SKUs in your catalog) so those credits apply only to usage from those items. Unscoped credits remain global and apply to all in-arrears usage and fixed fees in the same currency.

​
Key benefits

  • Product-specific budgets: Allocate dedicated credits to specific products or services (e.g., separate budgets for “API Calls” vs. “Storage”)
  • Automatic fallback: Scoped credits are applied first to matching items. Once scoped credits are exhausted, usage automatically draws from unscoped credits
  • Flexible credit hierarchies: Mix product-specific and organization-wide credits to match your business model

​
When to use scoped credits

Use scoped credits if:
  • You have customers using multiple products who need separate budgets per product
  • You need fine-grained control over how prepaid balances are consumed
  • You want product-specific credits to be exhausted before drawing from a general pool
Skip scoped credits if:
  • You prefer all credits to apply uniformly across all usage
  • Your customers use a single product or SKU

​
Quick start

The most common use case is creating credit blocks that can only be used for specific items. Here’s how that works:
  1. Create a scoped credit block: Grant $1000 in credits scoped to your “API Calls” item
  2. Customer incurs charges: When the customer uses your API, those charges draw from the scoped credits first
You can create scoped credits through the Orb dashboard or API (see Configuration below). The key is specifying which items the credits apply to when you create the credit block.

​
How scoped credits work

When you create a credit block, it exists in a specific currency (like USD or a custom pricing unit). By default, any credits in that currency can be used for any in-arrears usage and fixed fees in the same currency. Scoped credits let you add an additional layer of control: you can filter which items are eligible to draw from a specific credit block. For example, you might create a $500 credit block and scope it to “API Calls” usage. This means the credits can only be used for API Calls charges, not for Storage or other items.

​
Priority logic

When a customer incurs a charge, Orb looks at all available credit blocks in the same currency and applies them in this order:
  1. Scope: Scoped credits (filtered to matching items) take priority over unscoped credits
  2. Expiration: Among credits with the same scope, those expiring sooner are used first
  3. Cost basis: Among credits expiring at the same time, cheaper credits are used before more expensive credits
Example: A customer has $500 in credits scoped to “API Calls” (expires March 31) and $1000 in unscoped credits (expires March 15). When they incur API usage charges on March 1, Orb applies the “API Calls” credits first (scoped takes priority over unscoped), even though the unscoped credits expire sooner.

​
Common scenarios

​
Overlapping scoped credits

When an item appears in multiple scoped credit blocks, Orb uses the priority logic to determine which credits to apply first. Setup:
  • Credit block 1: $500 scoped to “API Calls” only (expires March 31)
  • Credit block 2: $1000 scoped to “API Calls” and “Storage” (expires March 15)
  • Customer incurs $1200 in API usage charges
Result: Orb applies credits from block 2 first because it expires sooner (March 15 vs. March 31). Once block 2’s $1000 is exhausted, the remaining $200 is deducted from block 1. Both blocks are scoped, so the expiration date is the tiebreaker.

​
Scoped and unscoped credits working together

You can mix scoped and unscoped credit blocks in the same currency. Scoped credits always apply first, then usage falls back to unscoped credits. Setup:
  • Credit block 1: $500 scoped to “API Calls” (expires March 31)
  • Credit block 2: $1000 unscoped (applies to all items, expires March 15)
  • Customer incurs $600 in API usage charges
Result:
  • The first $500 is deducted from block 1 (scoped to “API Calls”)
  • The remaining $100 is deducted from block 2 (unscoped)

​
Modifying scoped credit blocks

Once you create a scoped credit block, you cannot add or remove items from its filter. Plan which items to scope carefully before creating credit blocks. Workaround: If you need to change the scope:
  1. Void the existing credit block
  2. Create a new credit block with the desired item scope
  3. Note that this creates a new block, so any cost basis or metadata from the original block will need to be recreated
Best practice: When setting up scoped credits for a customer, consider their full product suite and whether they’re likely to add products in the future. If uncertain, use unscoped credits initially and transition to scoped credits once their usage patterns are established.

​
Configuration

​
Plan-based allocations

When creating or editing a plan, you can configure recurring credit allocations to be scoped to specific items. In plan settings, navigate to “Add allocation” and use the “Filter builder” to choose which items the credits apply to: Allocation Pn Add Allocation Pn The filter builder lets you include or exclude specific items. The list of available items is pulled from all items on the plan. If you don’t select any items, the allocation applies to all items in the plan. Addfilter Pn

​
Customer-level credit grants

For one-time credit grants (such as prepaid purchases, trials, promotions, or compensation), you can add item filters at the customer level. These scoped credits apply to all subscriptions under that customer. Learn more about managing credits. Use the “Filter builder” to scope which items can draw from the credit block. The list of available items pulls from your entire account catalog. Creation Pn

​
API configuration

For programmatic control, you can include item filters when creating credit blocks and allocations through the API. Use the API when you need to automate credit provisioning based on customer actions or integrate credit management into your application’s workflow. To create a scoped credit block, add a filters array with item_id filters when creating a ledger entry. Filters support includes (credits apply only to specified items) and excludes (credits apply to all items except specified ones) operators: 
POST https://api.withorb.com/v1/credits/ledger_entry
{
  "metadata": {},
  "currency": "USD",
  "entry_type": "increment",
  "amount": 500,
  "expiry_date": "2025-03-31",
  "effective_date": "2025-03-01",
  "per_unit_cost_basis": "0.10",
  "filters": [
    {
      "field": "item_id",
      "operator": "includes",
      "values": ["FszQj7VqS3bbqcEo"]  // Item ID for "API Calls"
    }
  ]
}
You can also scope recurring credit allocations when creating a plan by adding filters to the allocation_price configuration. To view a customer’s credit blocks and their filters, use the fetch credits endpoint.