Usage keys

Usage keys group limited or value-based entitlements into one shared consumable balance.

They are useful when a customer can receive credits or usage amounts from multiple sources, such as a subscription allowance, one-time credit pack, recurring add-on, or manual grant.

Why usage keys exist

Use usage keys when multiple Limited Value entitlements should behave like one shared balance in your app.

For example, a customer may buy different credit packs over time. Instead of checking every credit pack separately, your app can track usage against one usage key.

• one-time credit packs

• fixed top-ups

• bonus credits

• multiple Limited Value entitlements that should be consumed together

A usage key groups these limited entitlement sources under one logical identifier.

What usage keys are not for

Usage keys are not used for feature access, subscription allowances, or renewable values.

Use usage keys only when the customer has a consumable amount, such as credits, exports, tokens, AI generations, downloads, or API calls.

Example

A customer may receive multiple fixed credit packs:

Your app can track usage against credits instead of manually checking every Limited Value entitlement separately.

Example
Flutter
Copy
final result = await Revenipe.instance.track(
  id: 'credits',
  value: 1,
);

Limited Value entitlement vs usage key

The id passed to track can be either a direct Limited Value entitlement ID or a usage key.

If your app has only one Limited Value entitlement, tracking by entitlement ID can be enough.

If your app sells multiple packs or grants multiple fixed credit sources, use a usage key.

Track usage with a usage key

Use the shared usage key when the customer performs an action that should consume from the shared Limited Value balance.

Example
Flutter
Copy
final result = await Revenipe.instance.track(
  id: 'credits',
  value: 1,
);

if (result.success) {
  // Allow the action.
} else {
  // Show an upgrade prompt or block the action.
}

Revenipe resolves the usage key and consumes from the customer's available Limited Value entitlement sources.

Display remaining usage

Use entitlement data from the Revenipe SDK to show the customer's remaining balance in your app.

Example
Flutter
Copy
final entitlement = Revenipe.instance.getEntitlement('500_credits_pack');

If your app uses a usage key, display the balance in a way that matches your product experience.

For example, you may show one credit balance even when the customer has multiple Limited Value credit packs.

Naming usage keys

Use short, stable, lowercase identifiers for usage keys.

credits
tokens
downloads
ai_generations

Names like premium_access or support_access should usually be flag entitlements.

Names like monthly_credits usually describe a renewable Value entitlement, not a usage key.

Important

Usage keys should only be used for Limited Value entitlements.

Do not use usage keys for flag entitlements, renewable Value entitlements, subscription allowances, or simple feature access.

Do not build complex client-side logic to decide which credit pack or limited grant should be consumed first. Let Revenipe resolve usage through the usage key.

Only track usage after the customer is logged in, and only allow the action after Revenipe confirms that usage was successfully tracked.

Next steps

After understanding usage keys, continue with customers, entitlements, and usage tracking to understand how limited balances are granted and consumed.