Features & Entitlements
Define capabilities and grant them through product purchases
Features represent the capabilities your app can check at runtime. Entitlements connect features to products – when a customer purchases a product, they receive the entitlements attached to it, granting access to the corresponding features.
Features
Every feature has an external ID that your app uses for access checks (e.g., premium_export, api_calls). Features are scoped to an app and environment (test or live).
Feature types
| Type | Description | Example |
|---|---|---|
| Boolean | Simple on/off access. The customer either has it or does not. | premium_export, dark_mode |
| Metered | Usage-tracked with a numeric balance. Decremented as the customer consumes units. | api_calls, storage_gb, messages_sent |
| Credit system | A pool of credits that can substitute for one or more metered features using conversion ratios. | universal_credits converting to api_calls and storage_gb |
Creating a boolean feature
Navigate to Features in your app’s dashboard and click Create Feature. Select Boolean as the type and provide:
- Name – a display name (e.g., “Premium Export”)
- External ID – the SDK-facing identifier (e.g.,
premium_export)
Boolean features require no additional configuration. Access is determined entirely by whether the customer has an active entitlement.
Creating a metered feature
Select Metered as the type. In addition to name and external ID, configure:
- Usage type – choose single use (balance is consumed and gone) or continuous use (balance represents a current level, like active seats)
- Event name (optional) – the event that triggers usage tracking. When your app sends this event, Nuxie updates the customer’s balance automatically.
- Display units – singular and plural labels for the unit (e.g., “credit” / “credits”)
Creating a credit system
Credit systems are a special feature type that acts as a universal currency across multiple metered features. Navigate to Credits in the dashboard and click Create Credit System.
Configure the conversion schema – a list of mappings that define how credits convert to metered feature units:
| Metered feature | Feature amount | Credit amount |
|---|---|---|
api_calls |
1 | 5 |
storage_gb |
1 | 100 |
In this example, 1 API call costs 5 credits, and 1 GB of storage costs 100 credits.
At runtime, when a customer’s direct entitlement for a metered feature is exhausted, Nuxie automatically checks whether a credit system can cover the cost. The conversion happens transparently – your app only needs to check the original feature.
Feature uniqueness
External IDs must be unique within the same app and environment. Attempting to create a feature with a duplicate external ID returns an error.
Entitlements
Entitlements are rules attached to a product that grant access to a feature. When a customer purchases the product, Nuxie creates customer entitlements based on these rules.
Adding entitlements to a product
Open a product in the dashboard and select the Entitlements tab. Click Add Entitlement and choose a feature. The configuration options depend on the feature type.
Boolean entitlements
For boolean features, the entitlement is straightforward: owning the product grants access. No additional configuration is needed. The interval is automatically set to lifetime.
Metered entitlements
For metered features and credit systems, configure:
| Field | Description |
|---|---|
| Allowance type | Unlimited (always allowed) or Fixed (a numeric balance) |
| Allowance | The amount granted per interval (only when fixed) |
| Reset interval | How often the balance resets: lifetime, month, quarter, semiAnnual, year, or shorter intervals |
| Carry from previous | Whether unused balance rolls over to the next period |
Example: a “Pro Plan” product grants 10,000 API calls per month with no carry-over:
- Feature:
api_calls - Allowance type: Fixed
- Allowance: 10,000
- Reset interval: Month
- Carry from previous: No
Unlimited entitlements
Set the allowance type to Unlimited to grant unrestricted access to a metered feature. The SDK’s entitlement check returns allowed with no balance cap.
Removing entitlements
Removing an entitlement from a product only affects future purchases. Customers who already own the product retain their existing entitlements.
Checking features from the SDK
The iOS SDK provides a single method to check any feature type:
// nuxie-doc-fragment: monetization-boolean-access harness=async-body
// Boolean check
let access = try await NuxieSDK.shared.hasFeature("premium_export")
if access.allowed {
// Feature is unlocked
}// nuxie-doc-fragment: monetization-metered-access harness=async-body
// Metered check with required balance
let access = try await NuxieSDK.shared.hasFeature(
"api_calls",
requiredBalance: 1
)
if access.allowed {
// Sufficient balance remains
print("Balance: \(access.balance ?? 0)")
}The default cache-first policy uses authenticated profile state while fresh and asks the server otherwise. A remote Feature check can evaluate direct Entitlements and an eligible credit-system conversion.
Gate capabilities, not Product ownership
The iOS SDK intentionally exposes Feature checks rather than a Product-ownership
authorization API. Model the app capability as a Feature, attach the appropriate
Product Entitlement, and call hasFeature(). This keeps app code stable when Products,
prices, or providers change.
How entitlements are evaluated
When your app checks a feature, Nuxie evaluates entitlements in this order:
- Find all products the customer currently owns (active or past-due subscriptions).
- Collect entitlement candidates from those products that grant the requested feature.
- For boolean features, allow if any candidate exists.
- For metered features:
- Allow immediately if any candidate is unlimited.
- Otherwise, sum balances across all candidates and compare against the required amount.
- If the metered check fails, look for credit systems that include the feature in their conversion schema. Convert the required amount using the ratio and check the credit balance.
Authenticated cached state supports immediate Boolean and unlimited access. Fixed quota
and credit balances remain server-authoritative; call useFeatureAndWait() before the
protected side effect so the grant and deduction are atomic.
Next steps
- Products & Prices – configure what your customers buy
- Purchases & Subscriptions – understand the subscription lifecycle
- Features & Entitlements (SDK) – integrate entitlement checks in your iOS app
- Cookbook: Feature Gating – step-by-step guide to gating a feature