# Manage entitlements for a feature

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


[Idempotency Supported](/docs/api/idempotency)

Create, update, or remove a set of `entitlement`s for a feature.

The behavior depends on the specified `action`. It tries to create, update, or delete `entitlement` objects. If any of the entitlement objects fail to process, the entire operation stops with an error, and no entitlements are processed. In essence, the request processes either all the provided entitlements or none of them.

### Grandfathering in entitlements[](#grandfathering-in-entitlements)

> **Early Access**
> 
> Grandfathering in entitlements is in early access. Write to [eap@chargebee.com](mailto:eap@chargebee.com) to get this enabled.

By default, this operation impacts all [subscriptions](/docs/api/subscriptions) that contain the item or item price. However, if you set `apply_grandfathering` to `true`, the existing subscriptions are not impacted by the change.

#### Example[](#example)

Consider the following example:

##### On January 1st[](#on-january-1st)

-   You have a [plan price](/docs/api/item_prices/item_price-object#item_type) (`id`: `premium-monthly-usd`) entitled to a [feature](/docs/api/features) (`user_licenses`) at [value](/docs/api/features/feature-object#levels) `10`.
-   You have a subscription (`id`: `AzZjAiTl1btqS2lEj`) that contains the plan price (`premium-monthly-usd`).

##### On January 2nd[](#on-january-2nd)

-   Using this API operation, you change the entitlement level of the plan price `premium-monthly-usd` for the `user_licenses` feature to `value` `20`. You also set `apply_grandfathering` to `true`.
-   After the API operation completes, you [create a new subscription](/docs/api/subscriptions/create-subscription-for-items) (`id`: `6oqNGUlMd9Yn4Ui`) that contains the same plan price (`premium-monthly-usd`).
-   The existing subscription (`id`: `AzZjAiTl1btqS2lEj`) is [grandfathered in](https://en.wikipedia.org/wiki/Grandfather_clause), so it continues to be entitled to `user_licenses` at `value` `10`. The new subscription (`id`: `6oqNGUlMd9Yn4Ui`) is entitled to `user_licenses` at `value` `20`.

##### On January 3rd[](#on-january-3rd)

-   Using this API operation, you change the entitlement level of the plan price `premium-monthly-usd` for the `user_licenses` feature to `value` `30`. You also set `apply_grandfathering` to `false`.
-   After the API operation completes, you create another subscription (`id`: `99CRh8UgMXTq77tl`) that contains the same plan price (`premium-monthly-usd`).
-   Because grandfathering was not enabled, all three subscriptions (`AzZjAiTl1btqS2lEj`, `6oqNGUlMd9Yn4Ui`, and `99CRh8UgMXTq77tl`) are now entitled to `user_licenses` at `value` `30`.

## Sample Request

### Adding entitlements for a feature

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v2/entitlements \
     -u {site_api_key}:\
     -d action="UPSERT" \
     -d "entitlements[value][0]"="true" \
     -d "entitlements[feature_id][0]"="fea-2959f91d-a517-4440-a7d0-b00cf2fcec62" \
     -d "entitlements[entity_id][0]"="enterprise" \
     -d "entitlements[entity_type][0]"="PLAN"
```

#### .NET

```dotnet
using ChargeBee.Api;
using ChargeBee.Models;
using ChargeBee.Models.Enums;

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Entitlement.Create()
		.Action(ActionEnum.Upsert)
		.EntitlementValue(0, "true")
		.EntitlementFeatureId(0, "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62")
		.EntitlementEntityId(0, "enterprise")
		.EntitlementEntityType(0, Entitlement.EntityTypeEnum.Plan)
		.Request();

Entitlement entitlement = result.Entitlement;
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    entitlementAction "github.com/chargebee/chargebee-go/v3/actions/entitlement"
    "github.com/chargebee/chargebee-go/v3/models/entitlement"
    entitlementEnum "github.com/chargebee/chargebee-go/v3/models/entitlement/enum"
    enum "github.com/chargebee/chargebee-go/v3/enum"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := entitlementAction.Create(&entitlement.CreateRequestParams{
        Entitlements : []*entitlement.CreateEntitlementParams{
            {
                Value : "true",
                FeatureId : "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62",
                EntityId : "enterprise",
                EntityType : entitlementEnum.EntityTypePlan,
            },
        },
        Action : enum.ActionUpsert,
    }).Request()
    if err != nil {
        fmt.Println(err)
    } else {
        List := res.List
    }
}
```

#### Go

```go
package main

import (
  "fmt"
  "github.com/chargebee/chargebee-go/v4"
)

func main() {
  config := &chargebee.ClientConfig{
    SiteName: "{site}",
    ApiKey: "{site_api_key}",
  }    
  client := chargebee.NewClient(config)
  req := &chargebee.EntitlementCreateRequest{
    Entitlements : []*chargebee.EntitlementCreateEntitlement{
        {
            Value : "true",
            FeatureId : "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62",
            EntityId : "enterprise",
            EntityType : chargebee.EntitlementEntityTypePlan,
        },
    },
    Action : chargebee.ActionUpsert,
}
  res, err := client.Entitlement.Create(req)
      if err != nil {
        fmt.Println(err)
    } else {
        List := res.List
    }
}
```

#### Java

```java
import com.chargebee.*;
import com.chargebee.ListResult;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
import java.io.IOException;
import java.util.List;

public class Sample {

    public static void main(String args[]) throws IOException, Exception {
        Environment.configure("{site}", "{site_api_key}");
        Result result = Entitlement.create()
            .action(Action.UPSERT)
            .entitlementValue(0, "true")
            .entitlementFeatureId(0, "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62")
            .entitlementEntityId(0, "enterprise")
            .entitlementEntityType(0, Entitlement.EntityType.PLAN)
            .request();

    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.entitlement.params.EntitlementCreateParams;
import com.chargebee.v4.models.entitlement.responses.EntitlementCreateResponse;
import java.util.List;

public class EntitlementCreate {

    public static void main(String[] args) {
        ChargebeeClient client = ChargebeeClient.builder()
            .apiKey("{site_api_key}")
            .siteName("{site}")
            .build();

        EntitlementCreateParams.EntitlementsParams entitlement0 =
            EntitlementCreateParams.EntitlementsParams.builder()
                .value("true")
                .featureId("fea-2959f91d-a517-4440-a7d0-b00cf2fcec62")
                .entityId("enterprise")
                .entityType(EntitlementCreateParams.EntitlementsParams.EntityType.PLAN)
                .build();

        List<EntitlementCreateParams.EntitlementsParams> entitlementsList =
            List.of(entitlement0);

        EntitlementCreateParams params = EntitlementCreateParams.builder()
            .action(EntitlementCreateParams.Action.UPSERT)
            .entitlements(entitlementsList)
            .build();

        EntitlementCreateResponse response = client.entitlements().create(params);

    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

const chargebee = new Chargebee({
    site: "{site}",
    apiKey: "{site_api_key}",
});

try {
    const result = await chargebee.entitlement.create({
        entitlements: [
            {
                value: true,
                feature_id: "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62",
                entity_id: "enterprise",
                entity_type: "plan"
            }
        ],
        action: "upsert"
    });

    console.log(result);
    const list = result.list;
} catch (err) {
    console.log(err);
}
```

#### PHP

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);
$result = $chargebee->entitlement()->create([
    "entitlements" => [
        [
            "value" => true,
            "feature_id" => "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62",
            "entity_id" => "enterprise",
            "entity_type" => "plan"
        ]
    ],
    "action" => "upsert"
]);
$list = $result->list;
```

#### Python

```python
import chargebee
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.Entitlement.create(
    cb_client.Entitlement.CreateParams(
        entitlements=[
            cb_client.Entitlement.CreateEntitlementParams(
              value="true",
              feature_id="fea-2959f91d-a517-4440-a7d0-b00cf2fcec62",
              entity_id="enterprise",
              entity_type=chargebee.Entitlement.EntityType.PLAN
            )
        ],
        action=chargebee.Action.UPSERT
    )
)
entries = response.list
```

#### Ruby

```ruby
require 'chargebee'

ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")

result = ChargeBee::Entitlement.create({
  :action => "UPSERT",
  :entitlements => [
    {
      :value => "true",
      :feature_id => "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62",
      :entity_id => "enterprise",
      :entity_type => "PLAN"
    }
  ]
})

list = result.list
```

### Removal of entitlements from a feature

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v2/entitlements \
     -u {site_api_key}:\
     -d action="REMOVE" \
     -d "entitlements[feature_id][0]"="fea-2959f91d-a517-4440-a7d0-b00cf2fcec62" \
     -d "entitlements[entity_id][0]"="enterprise" \
     -d "entitlements[entity_type][0]"="PLAN"
```

#### .NET

```dotnet
using ChargeBee.Api;
using ChargeBee.Models;
using ChargeBee.Models.Enums;

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Entitlement.Create()
		.Action(ActionEnum.Remove)
		.EntitlementFeatureId(0, "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62")
		.EntitlementEntityId(0, "enterprise")
		.EntitlementEntityType(0, Entitlement.EntityTypeEnum.Plan)
		.Request();

Entitlement entitlement = result.Entitlement;
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    entitlementAction "github.com/chargebee/chargebee-go/v3/actions/entitlement"
    "github.com/chargebee/chargebee-go/v3/models/entitlement"
    entitlementEnum "github.com/chargebee/chargebee-go/v3/models/entitlement/enum"
    enum "github.com/chargebee/chargebee-go/v3/enum"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := entitlementAction.Create(&entitlement.CreateRequestParams{
        Entitlements : []*entitlement.CreateEntitlementParams{
            {
                FeatureId : "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62",
                EntityId : "enterprise",
                EntityType : entitlementEnum.EntityTypePlan,
            },
        },
        Action : enum.ActionRemove,
    }).Request()
    if err != nil {
        fmt.Println(err)
    } else {
        List := res.List
    }
}
```

#### Go

```go
package main

import (
  "fmt"
  "github.com/chargebee/chargebee-go/v4"
)

func main() {
  config := &chargebee.ClientConfig{
    SiteName: "{site}",
    ApiKey: "{site_api_key}",
  }    
  client := chargebee.NewClient(config)
  req := &chargebee.EntitlementCreateRequest{
    Entitlements : []*chargebee.EntitlementCreateEntitlement{
        {
            FeatureId : "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62",
            EntityId : "enterprise",
            EntityType : chargebee.EntitlementEntityTypePlan,
        },
    },
    Action : chargebee.ActionRemove,
}
  res, err := client.Entitlement.Create(req)
      if err != nil {
        fmt.Println(err)
    } else {
        List := res.List
    }
}
```

#### Java

```java
import com.chargebee.*;
import com.chargebee.ListResult;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
import java.io.IOException;
import java.util.List;

public class Sample {

    public static void main(String args[]) throws IOException, Exception {
        Environment.configure("{site}", "{site_api_key}");
        Result result = Entitlement.create()
            .action(Action.REMOVE)
            .entitlementFeatureId(0, "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62")
            .entitlementEntityId(0, "enterprise")
            .entitlementEntityType(0, Entitlement.EntityType.PLAN)
            .request();

    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.entitlement.params.EntitlementCreateParams;
import com.chargebee.v4.models.entitlement.responses.EntitlementCreateResponse;
import java.util.List;

public class EntitlementCreate {

    public static void main(String[] args) {
        ChargebeeClient client = ChargebeeClient.builder()
            .apiKey("{site_api_key}")
            .siteName("{site}")
            .build();

        EntitlementCreateParams.EntitlementsParams entitlement0 =
            EntitlementCreateParams.EntitlementsParams.builder()
                .featureId("fea-2959f91d-a517-4440-a7d0-b00cf2fcec62")
                .entityId("enterprise")
                .entityType(EntitlementCreateParams.EntitlementsParams.EntityType.PLAN)
                .build();

        List<EntitlementCreateParams.EntitlementsParams> entitlementsList =
            List.of(entitlement0);

        EntitlementCreateParams params = EntitlementCreateParams.builder()
            .action(EntitlementCreateParams.Action.REMOVE)
            .entitlements(entitlementsList)
            .build();

        EntitlementCreateResponse response = client.entitlements().create(params);

    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

const chargebee = new Chargebee({
    site: "{site}",
    apiKey: "{site_api_key}",
});

try {
    const result = await chargebee.entitlement.create({
        entitlements: [
            {
                feature_id: "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62",
                entity_id: "enterprise",
                entity_type: "plan"
            }
        ],
        action: "remove"
    });

    console.log(result);
    const list = result.list;
} catch (err) {
    console.log(err);
}
```

#### PHP

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);
$result = $chargebee->entitlement()->create([
    "entitlements" => [
        [
            "feature_id" => "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62",
            "entity_id" => "enterprise",
            "entity_type" => "plan"
        ]
    ],
    "action" => "remove"
]);
$list = $result->list;
```

#### Python

```python
import chargebee
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.Entitlement.create(
    cb_client.Entitlement.CreateParams(
        entitlements=[
            cb_client.Entitlement.CreateEntitlementParams(
              feature_id="fea-2959f91d-a517-4440-a7d0-b00cf2fcec62",
              entity_id="enterprise",
              entity_type=chargebee.Entitlement.EntityType.PLAN
            )
        ],
        action=chargebee.Action.REMOVE
    )
)
entries = response.list
```

#### Ruby

```ruby
require 'chargebee'

ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")

result = ChargeBee::Entitlement.create({
  :action => "REMOVE",
  :entitlements => [
    {
      :feature_id => "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62",
      :entity_id => "enterprise",
      :entity_type => "PLAN"
    }
  ]
})

list = result.list
```

## Sample Response

```json
{
  "list": [
    {
      "entitlement": {
        "feature_id": "fea-38eae836-73b4-4056-9704-254818d145de",
        "feature_name": "Quickbooks Integration_123",
        "id": "ent-56a6f379-f8e1-44f7-9e83-a7d57522fa1b",
        "entity_id": "enterprise",
        "entity_type": "plan",
        "name": "Available",
        "object": "entitlement",
        "value": "true"
      }
    },
    {..}
  ]
}
```

## URL Format

**POST** https://[site].chargebee.com/api/v2/entitlements

## Input Parameters

- `action` (required, enumerated string)
  The specific action to be performed for each `entitlement` specified.
  Possible enum values:
    - `upsert`
      If the `entitlement` already exists for the `feature_id` and `entity_id` combination, the `value` of the `entitlement` is updated. If it doesn't exist, a new `entitlement` is created.
    - `remove`
      Deletes the `entitlement` for the `feature_id` and `entity_id` combination, if it exists.

- `change_reason` (optional, string, max chars=100)
  Comments or reason for this entitlement change.

- `entitlements` (optional, array)
  Parameters for entitlements
  - `entity_id` (required, string, max chars=100)
    The unique identifier of the entity being granted entitlement to a specific `feature`.
    
    **Note** In the case of an `upsert` `action`, if the `entitlement` resource does not already exist, Chargebee does not validate this ID to confirm its correspondence to an existing entity. The `entitlement` is created regardless.
  - `feature_id` (required, string, max chars=50)
    The unique identifier of the `feature` to which the entity gains entitlement.
  - `entity_type` (optional, enumerated string)
    The type of the entity that holds this entitlement.
    Possible enum values:
      - `plan`
        Indicates that the entity is an `item` with `[type](/docs/api/items/item-object#type)` set to `plan`.
      - `addon`
        Indicates that the entity is an `item` with `[type](/docs/api/items/item-object#type)` set to `addon`.
      - `charge`
        Indicates that the entity is an `item` with `[type](/docs/api/items/item-object#type)` set to `charge` .
      - `plan_price`
        Indicates that the entity is an `item_price` associated with an `item` of `[type](/docs/api/items/item-object#type)` `plan`.
      - `addon_price`
        Indicates that the entity is an `item_price` associated with an `item` with `[type](/docs/api/items/item-object#type)` set to `addon`.
  - `value` (optional, string, max chars=50)
    The level of entitlement that the entity 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 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 `available` or `true`.
  - `apply_grandfathering` (optional, boolean)
    **Early Access**
    
    [Grandfathering support](/docs/api/entitlements) for entitlements is in early access. Write to [eap@chargebee.com](mailto:eap@chargebee.com) to get this enabled.
    
    Determines whether to [grandfather in](/docs/api/entitlements) existing subscriptions affected by this entitlement.
    
    -   `true`: Existing subscriptions that contain this entity as one of the [subscription items](/docs/api/subscriptions/subscription-object#subscription_items), are not mapped to this value of the entitlement; their currently mapped value for this entitlement are retained. New subscriptions created in the future that contain this entity, or existing subscriptions updated in the future to include this entity, are mapped to this value of the entitlement.
    -   `false`: All subscriptions that contain this entity are mapped to this version of the entitlement.

## Returns

- `entitlement` (Entitlement object)
  Resource object representing entitlement