Metered usage

Grant and consume units of an app capability.

Metered Features let you offer a set amount of something in your app: 100 exports, 50 image generations, or a limited number of API calls. Products grant the allowance, and your app tells Nuxie when the customer uses it.

Each metered Feature has its own balance. If several actions should spend from the same pool instead, use Credits.

Create a metered Feature

Open Features, choose Create Feature, and select Metered usage. Give it a name and a stable Feature key, then choose Create Feature to save. Your integration uses that key to check and consume the allowance.

You decide what a unit represents. One export can cost one unit; a larger operation can cost more. Nuxie records the quantity your app sends.

Product grants

Open the Product’s Entitlements tab and choose Grant Feature. Select your metered Feature, then choose Fixed units for an allowance or Unlimited for usage without a balance cap.

For example, a starter pack can include 100 exports while a subscription offers unlimited exports. Several active fixed grants contribute to the customer’s balance. An active unlimited grant takes precedence over those fixed balances.

The Feature’s Products tab shows where it’s included. You can edit a grant to change the Product’s allowance, but that doesn’t directly rewrite existing customer grants. Those continue to follow their purchase or subscription lifecycle. See Feature entitlements.

Consume units

Use an access check to show the balance or enable a button. When the customer starts the action, submit the Feature key and quantity for consumption. Nuxie checks that the amount is available and deducts it in the same operation.

For a customer with 100 exports, consuming one unit leaves 99. Start the export only after the request succeeds, then show the new balance. Checking the balance before the request doesn’t reserve that unit.

On iOS, useFeatureAndWait() returns a result with success. When it is true, perform the action and read authoritativeAccess.balance or usage.remaining for the updated allowance. The lower-level consumeFeature() returns accepted and balance instead. See your SDK reference for the equivalent methods on other platforms.

Retry a usage request

Save an operation ID with work that might be retried. Send the same ID, customer, Feature, quantity, and entity when trying again. Nuxie returns the previous decision instead of charging twice.

On iOS, use consumeFeature() when your app needs to supply that ID. useFeatureAndWait() handles a usage request without an app-supplied operation ID. Your SDK reference documents the equivalent consumption call for other platforms.

Keep that ID even after a timeout: the deduction may have succeeded before the response was lost. Your app also needs to recognize work it has already performed, so receiving the same accepted result doesn’t run the action twice.

Report a cumulative total

You can report a running total with set_usage in the REST API or the corresponding SDK option. Nuxie charges only the increase above usage already recorded.

For example, if the customer has used 7 units and you submit a total of 10, Nuxie consumes 3 more. Sending 10 again, or a lower total, consumes nothing and doesn’t refund units. You can’t combine this option with purchase evidence in a purchase-and-first-use request.

See Feature access for iOS usage options and POST /feature/consume for direct requests.