Delete an entitlement override

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`	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`	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`	409	The override changed at the same moment; retry.	Fetch the object again and retry the change.
`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`	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`	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: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

End a goodwill grant early#

Errors#