Skip to main content
Item-scoped credits provide fine-grained control over how prepaid balances are consumed across products and SKUs. When creating a credit, you can optionally scope it to specific item(s), so those credits apply only to the prices that are part of those items. If left blank, a credit remains global and applies to all in-arrears fees (usage + fixed) in the same currency, preserving existing behavior. This feature also introduces flexible credit management for customers who want both product-specific budgets and organization-wide credits. Scoped credits are applied first to matching line items, ensuring each product draws from its own designated credits. Once those scoped credits are exhausted, any remaining usage for that product automatically draws from the global (unscoped) credits.

​
Core Behavior & Credit Priority Logic

If no filter is applied, the credit applies to all in-arrears fees (usage + fixed) in the same currency as the credit. If one or more items are specified in the filter, the credit applies only to in-arrears fees that reference those items and share the same currency. Note that structurally, the credit balance consists of blocks, which are initialized with an amount and expiry_date. At any given time, the total credit balance for a customer is the sum of the remaining amount in their unexpired credit blocks (more detail here). When multiple credit blocks could apply, filtered blocks take precedence over unfiltered ones. The priority logic is as follows:
  1. Filtered: blocks take priority over unfiltered blocks
  2. Expiration: blocks expiring sooner are used first
  3. Cost basis: among equally expiring blocks, cheaper credits are used before more expensive credits
Below are some more nuanced scenarios and Orb’s behavior. #1: Overlapping Filters - When a product is included in multiple credit filters, Orb determines which credit block to apply based on Orb’s existing precedence logic. Example Consider the below example where item A appears in two different filtered blocks. 
  • Credit block 1 - filtered to item A
  • Credit block 2 - filtered to items A & B
Orb resolves which credit block to apply using the following logic:
  1. Filtered vs. Unfiltered - Credits from filtered blocks (those tied to specific items) take priority over unfiltered blocks that apply to all items.
  2. Expiration - Among the two filtered blocks, those expiring sooner are applied first.
  3. Cost basis - If multiple of the filtered credit blocks expire at the same time, Orb applies cheaper credits before more expensive ones.
#2: Hierarchy setup - You can configure your credits so that Orb automatically applies them in a hierarchical order; when filtered blocks are depleted, usage draws on unfiltered/general blocks. This setup ensures that once product-specific credits are consumed, usage then draws from a general credit pool in the same currency.  Consider the below example where item A is tied to a filtered block, and there is also a general block in the same currency.
  • Credit block 1 - filtered to item A
  • Credit block 2 - unfiltered (applies to all items in the same currency)
Orb applies credits using the following logic:
  • Filtered vs. unfiltered - Credits from Block 1 get applied to item A’s usage first 
  • Once Block 1 depleted, Block 2 will get applied to item A’s remaining usage
#3: Adding a new item to an existing filtered block: You can’t directly add new items to an active item-scoped (filtered) credit block. To include additional items under the same credit, you must first void the existing block and then create a new one that references the updated set of items. Consider the below example, where you want to expand an existing filtered block to include a new item:
  • Credit block 1- filtered to item A
  • New desired scope- filtered to item A + item B
You need to void credit block 1, create a new credit block (e.g. credit block 2) filtered to item A + item B

​
Configuration

​
Credit granting workflows 

You can grant filtered credits in a similar fashion and via the same UI and API surfaces as the existing credit flows (docs).  1. UI: Recurring credit allocations (plan-based) In plan setting, under “Add allocation” Allocation Pn You can now add filters via the “Filter builder” Add Allocation Pn You can choose which items that filter includes and/or excludes (Note: The list of available items here are pulled from all the items on the specific plan). If you do not pick any items, the allocation will apply to all items in the plan. Addfilter Pn 2. UI: Manual credit increments These credits are typically manually granted for prepaid purchases, one-time grants (such as trials, promotions, or compensation), contract-based variable amounts, or invoiced credits with a defined cost basis (more detail here). You can add items via the “Filter builder” for credit grants given at the customer level (these apply to all the subscriptions under a customer). The list of available items here pulls from the entire account including any items that have been created under the item creation flow in account settings.  Creation Pn 3. API You can include item filters when creating credit blocks and allocations through the API. Item filters are supported in both: Allocation creation (for example, in the plan creation API) and Credit ledger entry creation (docs) To see the balance on credits (docs)