---
title: "Consume Feature usage"
description: "Spend units once per action, with retries that do not double-charge."
api: POST https://i.nuxie.ai/feature/consume
authMethod: none
playground: simple
search:
  tags: ["api", "app", "reference"]
  keywords: ["consumeFeature", "useFeature", "operationId", "set_usage", "credits", "idempotentReplay"]
---

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

- **`apiKey`** · body · `string` · required

  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**.

- **`customerId`** · body · `string` · required

  The identified or anonymous customer ID your app supplies to the SDK, rather than Nuxie's internal customer record ID. See [Customer identifiers](/docs/api-reference/rest-api#customer-identifiers).

- **`featureId`** · body · `string` · required

  Published Feature key, such as `exports`.

- **`operationId`** · body · `string` · required

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

- **`quantity`** · body · `integer` · required

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

- **`mode`** · body · `string`

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

- **`entityId`** · body · `string`

  Identifier for an entity-scoped allowance.

- **`purchase`** · body · `object`

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

  **Purchase fields**

  - **`type`** · body · `string` · required

    `appstore` or `playstore`.

  - **`signedTransaction`** · body · `string`

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

  - **`purchaseToken`** · body · `string`

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

  - **`productId`** · body · `string`

    Google Play Product identifier, when relevant.

  - **`basePlanId`** · body · `string`

    Google Play subscription base plan, when relevant.

  - **`purchaseOptionId`** · body · `string`

    Google Play one-time purchase option, when relevant.

  - **`offerId`** · body · `string`

    Google Play selected offer, when relevant.

  - **`productType`** · body · `string`

    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

- **`operationId`** · `string` · required

  Identifier for this usage action.

- **`customerId`** · `string` · required

  Customer identity supplied in the request.

- **`featureId`** · `string` · required

  Published Feature key.

- **`accepted`** · `boolean` · required

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

- **`type`** · `string` · required

  Feature type returned by the usage decision.

- **`code`** · `string` · required

  Result or denial reason, such as `consumed`.

- **`quantity`** · `integer` · required

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

- **`balance`** · `number` · required

  Remaining units, or `null` for unlimited access.

- **`unlimited`** · `boolean` · required

  Whether usage is unlimited.

- **`active`** · `boolean` · required

  Whether the access is active after this decision.

- **`occurredAtMs`** · `number` · required

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

- **`idempotentReplay`** · `boolean` · required

  Whether this response repeats the saved decision for the operation.

- **`entityId`** · `string`

  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](/docs/api-reference/app/purchase). The purchase and consumption refer to the same customer and Feature. The SDK's Feature-use methods handle evidence and retries automatically.

```sh title="cURL"
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
}'
```

```json title="200"
{
  "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
}
```