Update a feature
The features.update operation: PATCH /api/v1/features/{id} in the REST API and the features_update tool in the MCP server.
/api/v1/features/{id}Changes a feature's name, combine rule, default value, perUnit (limits) or (for enum features) its values.
Send only the fields to change. The key and type never change, and enum values can be added but not removed,
so values products already grant stay valid. Customers' entitlements are recomputed after a change of the
combine rule, default value or perUnit (customer.entitlements.updated for each customer whose values move).
At a glance
- REST:
PATCH /api/v1/features/{id} - MCP tool:
features_update - Operation ID:
features.update - Scope: Brand
- Permission:
catalog:write - Risk tier:
write - Dry run: Supported (send
Ownrecord-Dry-Run: true) - Idempotency:
Idempotency-Keyoptional - Modes: Test and live
- Authentication: API key with the
catalog:writescope - Since: M4
Request
Path parameters
| Field | Type | Description |
|---|---|---|
id | feat_… ID |
Body
A JSON object (Content-Type: application/json):
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | |
combine | one of max, sum, or, first | No | How values from several products combine: or or first for booleans, max, sum or first for limits, first for enums. |
defaultValue | boolean or number or string | No | true/false for a boolean feature, a whole number for a limit, one of the values for an enum. |
enumValues | array of string | No | Enum features: the full list of values; existing values must stay (new ones can be added). |
perUnit | boolean | No | Limit features only: multiply granted values by the quantity. Customers' entitlements follow. |
Response
200 OK with a JSON object:
| Field | Type | Description |
|---|---|---|
id | feat_… ID | |
object | "feature" | |
brandId | brd_… ID | |
livemode | boolean | |
key | string | |
name | string | |
type | one of boolean, limit, enum | |
enumValues | array of string or null | |
combine | one of max, sum, or, first | |
defaultValue | boolean or number or string | |
perUnit | boolean | Limit features only: values are multiplied by the item's or purchase's quantity (spec §36.1). |
createdAt | date-time | |
updatedAt | date-time |
Examples
Rename a feature
PATCH /api/v1/features/feat_01m4tx5nj8emwbyf7y9vcf47y6
Authorization: Bearer or_test_…
Content-Type: application/json
{
"name": "Team seats"
}
Response (200):
{
"id": "feat_01m4tx5nj8emwbyf7y9vcf47y6",
"object": "feature",
"brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
"livemode": false,
"key": "seats.max",
"name": "Team seats",
"type": "limit",
"enumValues": null,
"combine": "max",
"defaultValue": 1,
"perUnit": true,
"createdAt": "2026-10-13T12:00:00.000Z",
"updatedAt": "2026-10-14T09:30:00.000Z"
}
Errors
| Code | HTTP status | When | What to do |
|---|---|---|---|
validation_failed | 400 | No field to change was sent, or the new definition breaks a rule (e.g. perUnit on a boolean). | Fix the fields listed in details.issues and send the request again. |
feature_change_not_allowed | 409 | The change removes enum values. | Create a new feature with the new definition, and grant it from your products instead. |
resource_not_found | 404 | No feature with this ID is visible to the request. | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. |
version_conflict | 409 | The feature changed at the same time; retry. | Fetch the object again and retry the change. |
permission_denied | 403 | You can't change this brand's catalog. | Ask an organization owner or admin for a role or scope that allows this action. |
It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, scope_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.