# Delete an entitlement override

> The customers.entitlement_overrides.delete operation: DELETE /api/v1/customers/{id}/entitlement_overrides/{overrideId} in the REST API and the customers_entitlement_overrides_delete tool in the MCP server.

Removes an override from a customer; the response is the override as it was. The customer's entitlements
are recomputed within one job cycle, and `customer.entitlements.updated` is sent when a value changes. An
expired override no longer applies anyway; deleting it only tidies the list.

Give a `reason`: it goes to the audit log with the removed override. Needs `customers:write` (owners, admins
and support).

## At a glance

- **REST:** `DELETE /api/v1/customers/{id}/entitlement_overrides/{overrideId}`
- **MCP tool:** `customers_entitlement_overrides_delete`
- **Operation ID:** `customers.entitlement_overrides.delete`
- **Scope:** Brand
- **Permission:** `customers:write`
- **Risk tier:** `write`
- **Dry run:** Supported (send `Ownrecord-Dry-Run: true`)
- **Idempotency:** `Idempotency-Key` optional
- **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_…`). |
| `overrideId` | `ceo_…` ID | The override's ID (`ceo_…`). |

### Body

A JSON object (`Content-Type: application/json`):

| Field    | Type   | Required | Description                                             |
| -------- | ------ | -------- | ------------------------------------------------------- |
| `reason` | string | Yes      | Why the override is removed; recorded in the audit log. |

## Response

`200 OK` 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

### End a goodwill grant early

```http
DELETE /api/v1/customers/cus_01m4ty3c2b5qx7mhd9k8w6s0aa/entitlement_overrides/ceo_01m4ty3c2b5qx7mhd9k8w6s0b2
Authorization: Bearer or_test_…
Content-Type: application/json

{
  "reason": "Migration finished"
}
```

Response (`200`):

```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"
}
```

## Errors

| Code                                                                                         | HTTP status | When                                                                                                   | What to do                                                                                                                                         |
| -------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed)       | 400         | An ID is malformed, or the reason is missing or too long.                                              | 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, or the customer has no override with this `overrideId`.  | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.                                               |
| [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict)         | 409         | The override changed at the same moment; retry.                                                        | Fetch the object again and retry the change.                                                                                                       |
| [`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_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`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).