---
title: "Add Feature to Subscription"
method: POST
path: "/api/v1/subscriptions/{id}/add-feature"
tags: ["Subscriptions"]
---

# Add Feature to Subscription

`POST /api/v1/subscriptions/{id}/add-feature`

Add a feature to a subscription. For toggle features, this is idempotent. For usage credit features, amounts accumulate. Optionally grant credits immediately for the current billing period.

## Path parameters

- `id` string, required — The subscription ID

## Request body

- object
  - `featureId` string — The feature ID to add. Exactly one of featureId or featureSlug must be provided.
  - `featureSlug` string — The feature slug to add. The feature will be resolved from the subscription pricing model. Exactly one of featureId or featureSlug must be provided.
  - `grantCreditsImmediately` boolean — If true and the feature is a usage credit grant, credits will be granted immediately for the current billing period

## Response `200`

Successful response

- AddFeatureToSubscriptionOutput
  - `subscriptionItemFeature` union, required
    - object
      - `id` string, required
      - `createdAt` integer, required — Epoch milliseconds.
      - `updatedAt` integer, required — Epoch milliseconds.
      - `livemode` boolean, required
      - `subscriptionItemId` string, required
      - `featureId` string, required
      - `productFeatureId` string, nullable
      - `type` 'toggle', required
      - `amount` unknown
      - `usageMeterId` unknown
      - `renewalFrequency` unknown
      - `expiredAt` integer, nullable — Epoch milliseconds.
      - `detachedAt` integer, nullable — Epoch milliseconds.
      - `detachedReason` string, nullable
      - `manuallyCreated` boolean, required
      - `pricingModelId` string, required
      - `resourceId` unknown
      - `name` string, required
      - `slug` string, required
    - object
      - `id` string, required
      - `createdAt` integer, required — Epoch milliseconds.
      - `updatedAt` integer, required — Epoch milliseconds.
      - `livemode` boolean, required
      - `subscriptionItemId` string, required
      - `featureId` string, required
      - `productFeatureId` string, nullable
      - `type` 'usage_credit_grant', required
      - `amount` integer, required
      - `usageMeterId` string, required
      - `renewalFrequency` 'once' | 'every_billing_period', required
      - `expiredAt` integer, nullable — Epoch milliseconds.
      - `detachedAt` integer, nullable — Epoch milliseconds.
      - `detachedReason` string, nullable
      - `manuallyCreated` boolean, required
      - `pricingModelId` string, required
      - `resourceId` unknown
      - `name` string, required
      - `slug` string, required
    - object
      - `id` string, required
      - `createdAt` integer, required — Epoch milliseconds.
      - `updatedAt` integer, required — Epoch milliseconds.
      - `livemode` boolean, required
      - `subscriptionItemId` string, required
      - `featureId` string, required
      - `productFeatureId` string, nullable
      - `type` 'resource', required
      - `amount` integer, required
      - `usageMeterId` unknown
      - `renewalFrequency` unknown
      - `expiredAt` integer, nullable — Epoch milliseconds.
      - `detachedAt` integer, nullable — Epoch milliseconds.
      - `detachedReason` string, nullable
      - `manuallyCreated` boolean, required
      - `pricingModelId` string, required
      - `resourceId` string, required
      - `name` string, required
      - `slug` string, required

## Other responses

- `400` — Invalid input data
- `401` — Authorization not provided
- `403` — Insufficient access
- `500` — Internal server error

---

[API](https://skmtc.dev/flowglad/apis/flowglad-api-2.md) · [All operations](https://skmtc.dev/flowglad/apis/flowglad-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/flowglad/flowglad-api-2/revisions/c838c92c3606/schema)