Grant

Grant additional usage to a subject for a specific period and implement top-up and prepaid billing scenarios.

#What is a Grant?

A grant is a record of usage granted to a subject. Grants have an effective date, expiration date, priority, and rollover configuration.

A grant has the following properties:

#Getting Started

To create a feature, you can use one of the OpenMeter SDKs.

// Grant 100 additional AI Tokens to customer-1 every month
const grant = await openmeter.subjects.createEntitlementGrant(
  'customer-1',
  'ai_tokens',
  {
    // Grant 100 additional usage
    amount: 100,
    // Grants with higher priority will be used first
    priority: 1,
    // Can be effective on a future date
    effectiveAt: new Date().toISOString(),
    // When the grant expires if not used
    expiration: {
      duration: 'MONTH',
      count: 1,
    },
    // Rollover exactly 100 every month
    minRolloverAmount: 100,
    maxRolloverAmount: 100,
    // Optional recurrence
    recurrence: {
      interval: 'MONTH',
    },
  },
);

Check out the Get Started guide to get started or use the Cloud UI:

#Expiration

The expiration of the grant is configured by two parameters:

• The expiration period (Day, Month, Year)
• The count of such periods

For example, you can configure the expiration to be in 1 month, 10 days, etc.

We configure expiration with period and period count so the system can re-apply expiration settings for rollover grants. The expiration time of the grant is calculated from the effective date of the grant.

When the grant expires, the remaining credits are removed from the subject's balance.

#Priority

Priority determines which grants are first used: any metered usage will be counted towards the balance of grants with higher priority.

Priority is a positive decimal number. With lower numbers indicating higher importance. For example, a priority of 1 is more urgent than a priority of 2.

Use case: If a system is metered by token on usage, then as part of their subscription each customer gets 10.000 tokens/month. Certian users require more tokens than this, so we are granting them an additional 100.000 tokens/year for extra fees.

We would want the customer to first use their available balance from the 10.000 tokens/month allowed balance, and if they have used all of that, then they should start using the 100.000 tokens/year balance.

To achieve this two grants should be created:

• Grant 1: 10.000 tokens/month priority=10
• Grant 2: 100.000 tokens/year priority=5

Given that we always count usage against the higher priorty grant, first the Grant 1 will be used, then the Grant 2.

In cases where credit grants share the same priority level, the grant closest to its expiration will be used first.

In the case of two credits having identical priorities and expiration dates, the system will use the grant that was created first.

#Rollover

Rollover is an optional configuration for credit grants.

You can configure rollover with the remaining or original amount.

In the case of entitlement reset, a rollover with the remaining amount re-applies the unused amount of the grant from the previous period.

While rollovers with the original amount config re-issue the full grant amount.

Rolled-over grants get a new ID, new effective date and expiration date based on expiration settings.