# Entitlement overrides

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


`subscriptions` inherit `entitlement`s from `item`s and/or `item price`s that are in them. Even so, there are many reasons why you may want to override the inherited entitlements on a subscription:

-   A customer wants access to a `feature` that the `item`s on their `subscription` are not entitled to.
-   A customer wants a higher `feature.level` without having to pay more.
-   A customer does not want to see or access a `feature` because it is irrelevant to them.
-   You offer customized `feature` bundles for each `subscription` instead of grouping `feature`s into a product catalog of `item`s.

This API helps you implement each of the above use cases, offering a method to override the entitlements for a subscription at the subscription, [item price](/docs/api/item_prices/item-price-object), or [charge-item](/docs/api/items#charge-items-or-charges) level.

**`entitlement_override` expiry**

If `[expires_at](/docs/api/entitlement_overrides/entitlement_override-object#expires_at)` has been set, then the `entitlement_override` object is no longer returned after `expires_at` has passed. The expiration of an `entitlement_override` does not trigger any event immediately. However, after expiry, the `entitlement_override` record gets deleted within 12 hours. This deletion triggers the `entitlement_overrides_auto_removed` event which can be considered as a notification, albeit delayed, for one or more `entitlement_overrides` having expired.

## Sample Entitlement override

```json
{
  "entitlement_override": {
    "entity_id": "Jdf63vkLssSDFdb",
    "entity_type": "subscription",
    "feature_id": "fea-7259be6f-43fd-4564-ae0b-d98386f38071",
    "feature_name": "API call limit",
    "id": "override-bf37fcff-c402-4811-a0b2-a675ed859b17",
    "name": "",
    "object": "entitlement_override",
    "value": "50"
  }
}
```

## Entitlement overrides attributes

## Input Parameters

- `id` (required, string, max chars=50)
  Unique identifier for the entitlement override. This is always auto-generated.

- `subscription_id` (optional, string, max chars=50)
  The `id` of the [subscription](/docs/api/subscriptions) to which this entitlement override belongs.

- `entity_id` (optional, string, max chars=100)
  -   When omitted, the entitlement override applies at the subscription level. See [subscription-level entitlement overrides](/docs/api/subscription_entitlements/subscription-entitlement-object#subscription-level-override).
  -   When provided, this is the ID of the entity whose contribution to the subscription entitlement is overridden. If the entity is not yet part of the subscription, the override takes effect when the entity is added. See [entity-level entitlement overrides](/docs/api/subscription_entitlements/subscription-entitlement-object#entity-level-overrides).

- `entity_type` (optional, string, max chars=50)
  The type of the entity at whose level the entitlement override is being set for the subscription.

- `feature_id` (optional, string, max chars=50)
  The `id` of the `feature` for which the entitlement override is being set.

- `feature_name` (optional, string, max chars=50)
  The `name` of the `feature` towards which this entitlement override has been granted.

- `value` (optional, string, max chars=50)
  The level of entitlement that the item has towards the feature. The possible values depend on the value of `feature.type` :
  
  -   When `feature.type` is `quantity` and:
      
  -   If `feature.levels[is_unlimited]` is not `true` for any one of `feature.levels[]`, then the value can be any one of `feature.levels[value][]`.
      
  -   If `feature.levels[is_unlimited]` is `true` for one of the `feature.levels[]`, then the value can also be:
      
      -   any one of `feature.levels[value][]`
      -   or it can be `unlimited` (case-insensitive), indicating unlimited entitlement.
  -   When `type` is `range` and:
      
  -   If `feature.levels[is_unlimited]` is not `true` for any one of `feature.levels[]`, then the value can be any whole number between `levels[value][0]` and `levels[value][1]` (inclusive).
      
  -   If `feature.levels[is_unlimited]` is `true` for one of the `feature.levels[]`, then the value can be:
      
      -   any whole number equal to or greater than `levels[value][0]`
      -   or it can be `unlimited` (case-insensitive), indicating unlimited entitlement.
  -   When `type` is `custom`, then the value can be any one of `feature.levels[value][]`.
      
  -   When `type` is `switch`, then the value is set as `true` if the feature is available; it is set as `false` when the feature is unavailable.

- `name` (optional, string, max chars=50)
  The display name for the entitlement level. The default values are auto-generated based on `feature.type` as follows:
  
  -   When `feature.type` is `quantity` or `range`, then `name` is the space-separated concatenation of `value` and the pluralized version of `feature.unit`. For example, if `value` is `20` and `feature.unit` is `user`, then `name` becomes `20 users`.
  -   When `feature.type` is `custom`, then `name` is the same as `value`.
  -   When `feature.type` is `switch`, the `name` is set to `Available` when `value` is `true`; it's set to `Not Available` when `value` is `false`.

- `expires_at` (optional, timestamp(UTC) in seconds)
  The expiry date for the `entitlement_override`. The `entitlement_override` object is no longer returned after this date has passed.
  
  **Constraints**
  
  Applicable only for subscription-level entitlement overrides. i.e. Not applicable when `entity_id` and `entity_type` are set.

- `effective_from` (optional, timestamp(UTC) in seconds)
  The starting date and time for the entitlement override. It indicates when the override becomes effective.
  
  **Constraints**
  
  Applicable only for subscription-level entitlement overrides. i.e. Not applicable when `entity_id` and `entity_type` are set.

- `is_enabled` (required, boolean)
  Indicates the feature availability.