---
title: "Create Feature"
openapi: "openapi POST /v1/features.create"
---

import { DynamicParamField } from "/components/dynamic-param-field.jsx";
import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";

### Body Parameters

<DynamicParamField body="name" type="string" required>
  The name of the feature.
</DynamicParamField>

<DynamicParamField body="type" type="'boolean' | 'metered' | 'credit_system'" required>
  The type of the feature. 'single_use' features are consumed, like API calls, tokens, or messages. 'continuous_use' features are allocated, like seats, workspaces, or projects. 'credit_system' features are schemas that unify multiple 'single_use' features into a single credit system.
</DynamicParamField>

<DynamicParamField body="consumable" type="boolean">
  Whether this feature is consumable. A consumable feature is one that periodically resets and is consumed rather than allocated (like credits, API requests, etc.). Applicable only for 'metered' features.
</DynamicParamField>

<DynamicParamField body="display" type="object">
  Singular and plural display names for the feature in your user interface.
  <Expandable title="properties">
    <DynamicParamField body="singular" type="string" required />

    <DynamicParamField body="plural" type="string" required />

  </Expandable>
</DynamicParamField>

<DynamicParamField body="credit_schema" type="object[]">
  A schema that maps 'single_use' feature IDs to credit costs. Applicable only for 'credit_system' features.
  <Expandable title="properties">
    <DynamicParamField body="metered_feature_id" type="string" required />

    <DynamicParamField body="credit_cost" type="number" required />

  </Expandable>
</DynamicParamField>

<DynamicParamField body="event_names" type="string[]" />

<DynamicParamField body="feature_id" type="string" required>
  The ID of the feature to create.
</DynamicParamField>


### Response

<DynamicResponseField name="id" type="string">
  The unique identifier for this feature, used in /check and /track calls.
</DynamicResponseField>

<DynamicResponseField name="name" type="string">
  Human-readable name displayed in the dashboard and billing UI.
</DynamicResponseField>

<DynamicResponseField name="type" type="'boolean' | 'metered' | 'credit_system'">
  Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools.
</DynamicResponseField>

<DynamicResponseField name="consumable" type="boolean">
  For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
</DynamicResponseField>

<DynamicResponseField name="event_names" type="string[]">
  Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
</DynamicResponseField>

<DynamicResponseField name="credit_schema" type="object[]">
  For credit_system features: maps metered features to their credit costs.
  <Expandable title="properties">
    <DynamicResponseField name="metered_feature_id" type="string">
      ID of the metered feature that draws from this credit system.
    </DynamicResponseField>

    <DynamicResponseField name="credit_cost" type="number">
      Credits consumed per unit of the metered feature.
    </DynamicResponseField>

  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="display" type="object">
  Display names for the feature in billing UI and customer-facing components.
  <Expandable title="properties">
    <DynamicResponseField name="singular" type="string | null">
      Singular form for UI display (e.g., 'API call', 'seat').
    </DynamicResponseField>

    <DynamicResponseField name="plural" type="string | null">
      Plural form for UI display (e.g., 'API calls', 'seats').
    </DynamicResponseField>

  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="archived" type="boolean">
  Whether the feature is archived and hidden from the dashboard.
</DynamicResponseField>


<ResponseExample>
```json 200
{
  "id": "api-calls",
  "name": "API Calls",
  "type": "metered",
  "consumable": true,
  "archived": false,
  "display": {
    "singular": "API call",
    "plural": "API calls"
  }
}
```
</ResponseExample>