Skip to main content

​
Overview

Create a new feature to track usage, control access, or manage unified credit systems. Features are the building blocks of your pricing model and determine what customers can access and consume.

​
Endpoint

POST /v1/features.create

​
Request Body

​
feature_id
string
required
The unique identifier for this feature. Used in /check and /track API calls. Must match the pattern ^[a-z0-9-_]+$.Example: "api-calls", "seats", "credits"
​
name
string
required
Human-readable name displayed in the dashboard and billing UI.Example: "API Calls", "Team Seats", "Credits"
​
type
enum
required
The type of feature. Determines how the feature is tracked and consumed.
​
consumable
boolean
Whether this feature is consumable. Required for metered features.
  • true - Usage resets periodically (e.g., monthly API calls, credits)
  • false - Allocated persistently (e.g., seats, workspaces, storage slots)
Note: Credit system features must be consumable.
​
credit_schema
array
Required for credit_system features. Maps metered features to their credit costs.
​
display
object
Display names for the feature in billing UI and customer-facing components.
​
event_names
array
Event names that trigger this feature’s balance. Allows multiple features to respond to a single event.Example: ["api.request", "api.call"]

​
Response

Returns the created feature object.
​
id
string
The unique identifier for this feature.
​
name
string
Human-readable name of the feature.
​
type
enum
Feature type: "boolean", "metered", or "credit_system".
​
consumable
boolean
Whether the feature is consumable.
​
archived
boolean
Whether the feature is archived (always false for newly created features).
​
display
object
Display names for UI rendering.
​
credit_schema
array
Credit schema mapping (only for credit_system features).
​
event_names
array
Event names that trigger this feature.

​
Examples

const response = await fetch('https://api.autumn.com/v1/features.create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    feature_id: 'api-calls',
    name: 'API Calls',
    type: 'metered',
    consumable: true,
    display: {
      singular: 'API call',
      plural: 'API calls'
    }
  })
});

const feature = await response.json();
console.log(feature);

​
Metered Feature (Consumable)

Request
{
  "feature_id": "api-calls",
  "name": "API Calls",
  "type": "metered",
  "consumable": true,
  "display": {
    "singular": "API call",
    "plural": "API calls"
  }
}
Response
{
  "id": "api-calls",
  "name": "API Calls",
  "type": "metered",
  "consumable": true,
  "archived": false,
  "display": {
    "singular": "API call",
    "plural": "API calls"
  }
}

​
Metered Feature (Non-Consumable)

Request
{
  "feature_id": "seats",
  "name": "Team Seats",
  "type": "metered",
  "consumable": false,
  "display": {
    "singular": "seat",
    "plural": "seats"
  }
}
Response
{
  "id": "seats",
  "name": "Team Seats",
  "type": "metered",
  "consumable": false,
  "archived": false,
  "display": {
    "singular": "seat",
    "plural": "seats"
  }
}

​
Boolean Feature

Request
{
  "feature_id": "advanced-analytics",
  "name": "Advanced Analytics",
  "type": "boolean"
}
Response
{
  "id": "advanced-analytics",
  "name": "Advanced Analytics",
  "type": "boolean",
  "consumable": false,
  "archived": false
}

​
Credit System Feature

Request
{
  "feature_id": "credits",
  "name": "Credits",
  "type": "credit_system",
  "consumable": true,
  "credit_schema": [
    {
      "metered_feature_id": "api-calls",
      "credit_cost": 1
    },
    {
      "metered_feature_id": "image-generations",
      "credit_cost": 10
    }
  ],
  "display": {
    "singular": "credit",
    "plural": "credits"
  }
}
Response
{
  "id": "credits",
  "name": "Credits",
  "type": "credit_system",
  "consumable": true,
  "archived": false,
  "credit_schema": [
    {
      "metered_feature_id": "api-calls",
      "credit_cost": 1
    },
    {
      "metered_feature_id": "image-generations",
      "credit_cost": 10
    }
  ],
  "display": {
    "singular": "credit",
    "plural": "credits"
  }
}

​
Feature Types Explained

​
Boolean Features

Boolean features provide simple on/off access control. Use them for:
  • Premium feature flags (e.g., “Advanced Analytics”, “Custom Branding”)
  • Access tiers (e.g., “API Access”, “Premium Support”)
  • Binary capabilities that don’t track usage

​
Metered Features

Metered features track quantifiable usage or allocations. Configure as: Consumable (consumable: true) - Usage resets periodically:
  • API calls per month
  • Messages sent
  • Credits consumed
  • Compute hours
Non-Consumable (consumable: false) - Persistent allocations:
  • Team seats
  • Workspaces
  • Projects
  • Storage slots

​
Credit Systems

Credit systems unify multiple metered features under a single credit pool. Customers spend credits on different actions at different rates:
  • 1 credit per API call
  • 10 credits per image generation
  • 5 credits per video render
This simplifies pricing by giving customers flexibility in how they use their allocation.

​
Best Practices

Use lowercase with hyphens for feature IDs (e.g., "api-calls", not "API_CALLS" or "apiCalls").
Feature IDs cannot be changed after creation if the feature is in use by customers. Choose meaningful, stable identifiers.
Credit system features require you to create the underlying metered features first. Create "api-calls" and "image-generations" before creating the credit system that references them.

​
Error Responses

​
code
string
Error code identifying the type of error.
​
message
string
Human-readable error message.

​
Common Errors

  • feature_already_exists - A feature with this ID already exists
  • invalid_feature_id - Feature ID contains invalid characters
  • consumable_required - Consumable field is required for metered features
  • credit_schema_required - Credit schema is required for credit_system features
  • invalid_credit_schema - Referenced metered feature does not exist

Build docs developers (and LLMs) love

Get started for freeTalk to us