Consume Feature usage

Spend units once per action, with retries that do not double-charge.

POSThttps://i.nuxie.ai/feature/consume

Spend units from a customer’s allowance. Give each action an operationId and reuse it on retries so the action is counted once. Start the paid work only after the response says accepted: true.

Request body

apiKeybodystringrequired

Publishable key for the app platform. A pk_test_ key selects test data; a pk_live_ key selects live data. Copy it from Connect your app.

customerIdbodystringrequired

The identified or anonymous customer ID your app supplies to the SDK, rather than Nuxie’s internal customer record ID. See Customer identifiers.

featureIdbodystringrequired

Published Feature key, such as exports.

operationIdbodystringrequired

Stable identifier for this action. Reuse it when retrying the same action.

quantitybodyintegerrequired

Units to consume, or the cumulative total in set_usage mode. Accepts 1 to 9,007,199,254,740,991.

modebodystring

consume (default) adds the quantity to usage. set_usage consumes only the increase from the previously used total.

entityIdbodystring

Identifier for an entity-scoped allowance.

purchasebodyobject

Store evidence to apply a purchase and spend its first units together. Cannot be combined with set_usage.

Purchase fields

typebodystringrequired

appstore or playstore.

signedTransactionbodystring

Required for appstore: the signed StoreKit transaction, up to 2 MiB.

purchaseTokenbodystring

Required for playstore: the Google Play purchase token, up to 16,384 characters.

productIdbodystring

Google Play Product identifier, when relevant.

basePlanIdbodystring

Google Play subscription base plan, when relevant.

purchaseOptionIdbodystring

Google Play one-time purchase option, when relevant.

offerIdbodystring

Google Play selected offer, when relevant.

productTypebodystring

Google Play subscription or one_time, when relevant.

The customer, Feature, operation, and entity identifiers must be non-empty, trimmed, and at most 256 characters. Unknown fields return 400.

For example, after 7 units have been used, set_usage with a quantity of 10 consumes 3 more units. An equal or lower total consumes nothing; it does not restore spent units.

Response

operationIdstringrequired

Identifier for this usage action.

customerIdstringrequired

Customer identity supplied in the request.

featureIdstringrequired

Published Feature key.

acceptedbooleanrequired

Whether the usage succeeded, including when it spent the last unit.

typestringrequired

Feature type returned by the usage decision.

codestringrequired

Result or denial reason, such as consumed.

quantityintegerrequired

Quantity submitted in the request. In set_usage mode, this is the cumulative total, not the number of newly spent units.

balancenumberrequired

Remaining units, or null for unlimited access.

unlimitedbooleanrequired

Whether usage is unlimited.

activebooleanrequired

Whether the access is active after this decision.

occurredAtMsnumberrequired

Unix timestamp in milliseconds, or null if no decision time is available.

idempotentReplaybooleanrequired

Whether this response repeats the saved decision for the operation.

entityIdstring

Returned for entity-scoped commands.

Retries and denied usage

A replay returns the saved decision with idempotentReplay: true. Reusing an operation ID for different input can return 409 with code: "operation_conflict".

A denied command can return 200 with accepted: false and a reason in code. Purchase-backed commands with insufficient balance can return 402. Neither authorizes the paid work.

Purchase evidence here uses camelCase fields, unlike Synchronize a purchase. The purchase and consumption refer to the same customer and Feature. The SDK’s Feature-use methods handle evidence and retries automatically.

curl https://i.nuxie.ai/feature/consume \
  --header 'Content-Type: application/json' \
  --data '{
  "apiKey": "pk_test_example",
  "customerId": "user-456",
  "featureId": "exports",
  "operationId": "export-018f55a9",
  "quantity": 1
}'

{
  "operationId": "export-018f55a9",
  "customerId": "user-456",
  "featureId": "exports",
  "accepted": true,
  "type": "metered",
  "code": "consumed",
  "quantity": 1,
  "balance": 9,
  "unlimited": false,
  "active": true,
  "occurredAtMs": 1787313600000,
  "idempotentReplay": false
}