# Override an entitlement > The customers.entitlement_overrides.create operation: POST /api/v1/customers/{id}/entitlement_overrides in the REST API and the customers_entitlement_overrides_create tool in the MCP server. Grants a customer a value of one feature, with a reason and an optional expiry, e.g. 20 extra seats while a team migrates or `feature.export = true` as a goodwill gesture. The override is one more source of the customer's entitlements and merges with the others by the feature's combine rule: with `max` it raises a limit, with `sum` it adds to it, with `or` it can only switch a feature on, and with `first` it decides (the newest override comes first). It applies until `expiresAt` (exclusive), or until deleted; for a customer on a test clock, `expiresAt` is a time on the clock (#541). The customer's entitlements are recomputed within one job cycle, and `customer.entitlements.updated` is sent when a value changes. Needs `customers:write` (owners, admins and support); the reason goes to the override and the audit log. ## At a glance - **REST:** `POST /api/v1/customers/{id}/entitlement_overrides` - **MCP tool:** `customers_entitlement_overrides_create` - **Operation ID:** `customers.entitlement_overrides.create` - **Scope:** Brand - **Permission:** `customers:write` - **Risk tier:** `write` - **Dry run:** Supported (send `Ownrecord-Dry-Run: true`) - **Idempotency:** `Idempotency-Key` required - **Modes:** Test and live - **Authentication:** API key with the `customers:write` scope - **Since:** M5 ## Request ### Path parameters | Field | Type | Description | | ----- | ---------- | ---------------------------- | | `id` | `cus_…` ID | The customer's ID (`cus_…`). | ### Body A JSON object (`Content-Type: application/json`): | Field | Type | Required | Description | | ------------ | --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `featureKey` | string | Yes | The feature to grant a value of, e.g. `seats.max`. | | `value` | boolean or number or string | Yes | The value to grant: true/false for a boolean feature, a whole number ≥ 0 for a limit, one of the values of an enum feature. It merges with the customer's other values by the feature's combine rule. | | `reason` | string | Yes | Why the customer gets this; stored on the override and in the audit log. | | `expiresAt` | date-time | No | When the override stops applying (exclusive). Must be in the future. Omit for no expiry. | ## Response `201 Created` with a JSON object: | Field | Type | Description | | ------------ | --------------------------- | ---------------------------------------------------------------------- | | `id` | `ceo_…` ID | | | `object` | `"entitlement_override"` | | | `customerId` | `cus_…` ID | | | `brandId` | `brd_…` ID | | | `livemode` | boolean | | | `featureKey` | string | | | `value` | boolean or number or string | | | `reason` | string | | | `setBy` | object | Who granted it. | | `setBy.type` | string | | | `setBy.id` | string | | | `expiresAt` | date-time or null | | | `active` | boolean | Whether the override applies at the time of the request (not expired). | | `createdAt` | date-time | | ## Examples ### Extra seats for a month ```http POST /api/v1/customers/cus_01m4ty3c2b5qx7mhd9k8w6s0aa/entitlement_overrides Authorization: Bearer or_test_… Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14 Content-Type: application/json { "featureKey": "seats.max", "value": 20, "reason": "Goodwill while their team migrates (ticket 4821)", "expiresAt": "2026-11-14T00:00:00.000Z" } ``` Response (`201`): ```json { "id": "ceo_01m4ty3c2b5qx7mhd9k8w6s0b2", "object": "entitlement_override", "customerId": "cus_01m4ty3c2b5qx7mhd9k8w6s0aa", "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4", "livemode": false, "featureKey": "seats.max", "value": 20, "reason": "Goodwill while their team migrates (ticket 4821)", "setBy": { "type": "user", "id": "usr_01m4ty3c2b5qx7mhd9k8w6s0b4" }, "expiresAt": "2026-11-14T00:00:00.000Z", "active": true, "createdAt": "2026-10-14T10:00:00.000Z" } ``` ### Switch a feature on for good ```http POST /api/v1/customers/cus_01m4ty3c2b5qx7mhd9k8w6s0aa/entitlement_overrides Authorization: Bearer or_test_… Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14 Content-Type: application/json { "featureKey": "feature.export", "value": true, "reason": "Beta tester" } ``` Response (`201`): ```json { "id": "ceo_01m4ty3c2b5qx7mhd9k8w6s0b3", "object": "entitlement_override", "customerId": "cus_01m4ty3c2b5qx7mhd9k8w6s0aa", "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4", "livemode": false, "featureKey": "feature.export", "value": true, "reason": "Beta tester", "setBy": { "type": "user", "id": "usr_01m4ty3c2b5qx7mhd9k8w6s0b4" }, "expiresAt": null, "active": true, "createdAt": "2026-10-14T10:00:00.000Z" } ``` ## Errors | Code | HTTP status | When | What to do | | -------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | A field is missing or malformed, the reason is empty, or `expiresAt` isn't in the future. | Fix the fields listed in `details.issues` and send the request again. | | [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404 | This brand has no such customer in this mode (customers belong to one brand and one mode). | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. | | [`customer_deleted`](https://ownrecord.io/docs/reference/errors.md#customer_deleted) | 400 | The customer was deleted. | Create a new customer for this buyer. Deleted customers stay readable for the records they belong to, but can't be changed. | | [`entitlement_feature_not_found`](https://ownrecord.io/docs/reference/errors.md#entitlement_feature_not_found) | 400 | The brand has no feature with this key in this mode. | Check the feature key against `features.list` (test and live mode have separate features), or create the feature first with `features.create`. | | [`entitlement_value_invalid`](https://ownrecord.io/docs/reference/errors.md#entitlement_value_invalid) | 400 | The value doesn't fit the feature: true/false for booleans, a whole number ≥ 0 for limits, a listed value for enums. | Use true or false for boolean features, a whole number of 0 or more for limits, and one of the listed values for enum features. | | [`entitlement_override_limit`](https://ownrecord.io/docs/reference/errors.md#entitlement_override_limit) | 409 | The customer already has 100 active overrides. | Delete overrides the customer no longer needs (`customers.entitlement_overrides.delete`), or let expiring ones run out, then try again. | | [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused) | 409 | The idempotency key was used before with another input. | Use a new Idempotency-Key for a different request, or resend the original request unchanged. | | [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required) | 400 | The request names no brand (an org or entity key without `Ownrecord-Brand`). | Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`). | | [`livemode_not_allowed`](https://ownrecord.io/docs/reference/errors.md#livemode_not_allowed) | 403 | You have no live-mode access, so you can't act on live customers. | Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin. | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You can't change this brand's customers' entitlements (`customers:write`: owners, admins and support). | Ask an organization owner or admin for a role or scope that allows this action. | It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).