Nuxie/Docs
Monetization

Features & Entitlements

Define capabilities and grant them through product purchases

Features & Entitlements

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

TypeDescriptionExample
BooleanSimple on/off access. The customer either has it or does not.premium_export, dark_mode
MeteredUsage-tracked with a numeric balance. Decremented as the customer consumes units.api_calls, storage_gb, messages_sent
Credit systemA 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 featureFeature amountCredit amount
api_calls15
storage_gb1100

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:

FieldDescription
Allowance typeUnlimited (always allowed) or Fixed (a numeric balance)
AllowanceThe amount granted per interval (only when fixed)
Reset intervalHow often the balance resets: lifetime, month, quarter, semiAnnual, year, or shorter intervals
Carry from previousWhether 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:

swift
// Boolean check
let result = Nuxie.shared.entitled(feature: "premium_export")
if result.allowed {
    // Feature is unlocked
}
swift
// Metered check with required balance
let result = Nuxie.shared.entitled(feature: "api_calls", requiredBalance: 1)
if result.allowed {
    // Sufficient balance remains
    print("Balance: \(result.balance ?? 0)")
}

The SDK evaluates entitlements using the customer's cached profile, so checks are fast and work offline. When a metered feature check fails against the direct entitlement, Nuxie automatically attempts credit system conversion before returning the result.

Product-level checks

You can also check whether a customer owns a specific product:

swift
let result = Nuxie.shared.entitled(product: "pro_monthly")
if result.allowed {
    // Customer has an active subscription to this product
}

Product checks consider subscriptions with active or pastDue status as valid.

How entitlements are evaluated

When your app checks a feature, Nuxie evaluates entitlements in this order:

  1. Find all products the customer currently owns (active or past-due subscriptions).
  2. Collect entitlement candidates from those products that grant the requested feature.
  3. For boolean features, allow if any candidate exists.
  4. For metered features:
    • Allow immediately if any candidate is unlimited.
    • Otherwise, sum balances across all candidates and compare against the required amount.
  5. 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.

This evaluation happens on-device using the cached profile. The profile stays in sync with the server as purchases, renewals, and usage events are processed.

Next steps