> ## Documentation Index
> Fetch the complete documentation index at: https://docs.integrateledger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a feature

> Create one metered feature without replacing other catalog items.

Create one metered feature without replacing other catalog items. A feature names an action in your application and sets how many credits one successful use costs. For example, a feature with ID `api_call` and `creditCost: 1` charges one credit per tracked API call.

## Define the meter

`creditCost` must be a positive integer. The feature ID is your stable identifier for [Check credits](https://docs.integrateledger.com/api-reference/usage/check.md) and [Record usage](https://docs.integrateledger.com/api-reference/usage/track.md). It accepts letters, numbers, underscores, and hyphens, up to 100 characters. `name` is a display label of at most 120 characters.

The API returns the created `item` with `changed: true`. Creating another active feature with the same ID returns `409 already_exists`. Feature creation is independent of plans and credit packs and does not call Stripe.

## Use it from your backend

Call `check` before your application performs the action, then call `track` after the action succeeds. A check does not reserve credits; `track` makes its own balance decision. Give every logical action a unique `request_id`, and reuse that ID only for a retry of the same action. A repeated track returns `idempotent: true` without another charge.

[Update a feature](https://docs.integrateledger.com/api-reference/features/update.md) changes the cost of future tracked events. Previously recorded usage keeps its original charge. [Archive a feature](https://docs.integrateledger.com/api-reference/features/archive.md) removes it from active lists and future checks while retaining usage history. See [Credits and usage](https://docs.integrateledger.com/credits.md) for concurrency and error handling.


## OpenAPI

````yaml openapi.json POST /v1/features
openapi: 3.1.0
info:
  title: Ledger API
  version: 0.1.0
servers:
  - url: https://api.integrateledger.com
    description: Hosted Ledger API
security: []
paths:
  /v1/features:
    post:
      tags:
        - Features
      summary: Create a feature
      operationId: createFeature
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFeatureInput'
      responses:
        '201':
          description: Feature created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureMutation'
              example:
                item:
                  id: api_call
                  name: API call
                  creditCost: 1
                changed: true
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        '401':
          description: Invalid Ledger API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        '409':
          description: Item ID already exists or add-on Checkout is pending
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
      security:
        - ApiKey: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --request POST 'https://api.integrateledger.com/v1/features' \
              -H "Authorization: Bearer $LEDGER_API_KEY" \
              -H 'Content-Type: application/json' \
              --data '{"id":"api_call","name":"API call","creditCost":1}'
        - lang: python
          label: Python SDK (source only)
          source: |-
            import os
            from ledger_sdk import Ledger

            ledger = Ledger(api_key=os.environ["LEDGER_API_KEY"])
            ledger.create_feature(id="api_call", name="API call", credit_cost=1)
        - lang: typescript
          label: TypeScript SDK (source only)
          source: >-
            import { Ledger } from "@ledger/sdk";


            const ledger = new Ledger({ apiKey: process.env.LEDGER_API_KEY ?? ""
            });

            await ledger.createFeature({ id: "api_call", name: "API call",
            creditCost: 1 });
components:
  schemas:
    CreateFeatureInput:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 100
          pattern: ^[a-zA-Z0-9_-]+$
        name:
          type: string
          minLength: 1
          maxLength: 120
        creditCost:
          type: integer
          exclusiveMinimum: 0
          maximum: 2147483647
      required:
        - id
        - name
        - creditCost
      additionalProperties: false
    FeatureMutation:
      type: object
      properties:
        item:
          $ref: '#/components/schemas/FeatureItem'
        changed:
          type: boolean
      required:
        - item
        - changed
    FeatureItem:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 100
          pattern: ^[a-zA-Z0-9_-]+$
        name:
          type: string
          minLength: 1
          maxLength: 120
        creditCost:
          type: integer
          exclusiveMinimum: 0
          maximum: 2147483647
      required:
        - id
        - name
        - creditCost
      additionalProperties: false
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.