# Upsert or remove item entitlements for an item

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


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

**Deprecated** This operation is deprecated and no longer maintained. Migrate your integration to [Manage entitlements](/docs/api/entitlements/upsert-or-remove-entitlements-for-a-feature).

**Warning** This operation is not supported when [grandfathering](/docs/api/entitlements) is enabled.

Upserts or removes a set of `item_entitlements` for an `[item](/docs/api/items)` depending on the `action` specified. The API returns the upserted or deleted `item_entitlements` after successfully completing the operation. The operation returns an error when the first `item_entitlement` fails to be processed. Either all the `item_entitlement`s provided in the request are processed or none.

## Sample Request

### Adding item entitlements for an item

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v2/items/basic/item_entitlements \
     -X POST  \
     -u {site_api_key}:\
     -d action="UPSERT" \
     -d "item_entitlements[value][0]"="true" \
     -d "item_entitlements[feature_id][0]"="fea-2959f91d-a517-4440-a7d0-b00cf2fcec62"
```

#### .NET

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

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = ItemEntitlement.UpsertOrRemoveItemEntitlementsForItem("basic")
		.Action(ActionEnum.Upsert)
		.ItemEntitlementValue(0, "true")
		.ItemEntitlementFeatureId(0, "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62")
		.Request();

ItemEntitlement itemEntitlement = result.ItemEntitlement;
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    itementitlementAction "github.com/chargebee/chargebee-go/v3/actions/itementitlement"
    "github.com/chargebee/chargebee-go/v3/models/itementitlement"
    enum "github.com/chargebee/chargebee-go/v3/enum"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := itementitlementAction.UpsertOrRemoveItemEntitlementsForItem("basic", &itementitlement.UpsertOrRemoveItemEntitlementsForItemRequestParams{
        ItemEntitlements : []*itementitlement.UpsertOrRemoveItemEntitlementsForItemItemEntitlementParams{
            {
                Value : "true",
                FeatureId : "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62",
            },
        },
        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.ItemEntitlementUpsertOrRemoveItemEntitlementsForItemRequest{
    ItemEntitlements : []*chargebee.ItemEntitlementUpsertOrRemoveItemEntitlementsForItemItemEntitlement{
        {
            Value : "true",
            FeatureId : "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62",
        },
    },
    Action : chargebee.ActionUpsert,
}
  res, err := client.ItemEntitlement.UpsertOrRemoveItemEntitlementsForItem("basic", 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 = ItemEntitlement.upsertOrRemoveItemEntitlementsForItem("basic")
            .action(Action.UPSERT)
            .itemEntitlementValue(0, "true")
            .itemEntitlementFeatureId(0, "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62")
            .request();

    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.itemEntitlement.params.UpsertOrRemoveItemEntitlementsForItemParams;
import com.chargebee.v4.models.itemEntitlement.responses.UpsertOrRemoveItemEntitlementsForItemResponse;
import java.util.List;

public class UpsertOrRemoveItemEntitlementsForItem {

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

        UpsertOrRemoveItemEntitlementsForItemParams.ItemEntitlementsParams itemEntitlement0 =
            UpsertOrRemoveItemEntitlementsForItemParams.ItemEntitlementsParams.builder()
                .value("true")
                .featureId("fea-2959f91d-a517-4440-a7d0-b00cf2fcec62")
                .build();

        List<UpsertOrRemoveItemEntitlementsForItemParams.ItemEntitlementsParams> itemEntitlementsList =
            List.of(itemEntitlement0);

        UpsertOrRemoveItemEntitlementsForItemParams params = UpsertOrRemoveItemEntitlementsForItemParams.builder()
            .action(UpsertOrRemoveItemEntitlementsForItemParams.Action.UPSERT)
            .itemEntitlements(itemEntitlementsList)
            .build();

        UpsertOrRemoveItemEntitlementsForItemResponse response = client
            .itemEntitlements()
            .upsertOrRemoveItemEntitlementsForItem("basic", params);

    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

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

try {
    const result = await chargebee.itemEntitlement.upsertOrRemoveItemEntitlementsForItem("basic", {
        item_entitlements: [
            {
                value: true,
                feature_id: "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62"
            }
        ],
        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->itemEntitlement()->upsertOrRemoveItemEntitlementsForItem("basic", [
    "item_entitlements" => [
        [
            "value" => true,
            "feature_id" => "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62"
        ]
    ],
    "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.ItemEntitlement.upsert_or_remove_item_entitlements_for_item("basic",
    cb_client.ItemEntitlement.UpsertOrRemoveItemEntitlementsForItemParams(
        item_entitlements=[
            cb_client.ItemEntitlement.UpsertOrRemoveItemEntitlementsForItemItemEntitlementParams(
              value="true",
              feature_id="fea-2959f91d-a517-4440-a7d0-b00cf2fcec62"
            )
        ],
        action=chargebee.Action.UPSERT
    )
)
entries = response.list
```

#### Ruby

```ruby
require 'chargebee'

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

result = ChargeBee::ItemEntitlement.upsert_or_remove_item_entitlements_for_item("basic",{
  :action => "UPSERT",
  :item_entitlements => [
    {
      :value => "true",
      :feature_id => "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62"
    }
  ]
})

list = result.list
```

### Remove item entitlements for an item

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v2/items/enterprise/item_entitlements \
     -X POST  \
     -u {site_api_key}:\
     -d action="REMOVE" \
     -d "item_entitlements[feature_id][0]"="fea-3be1c4bf-cd37-4c93-adf5-823db1db3130"
```

#### .NET

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

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = ItemEntitlement.UpsertOrRemoveItemEntitlementsForItem("enterprise")
		.Action(ActionEnum.Remove)
		.ItemEntitlementFeatureId(0, "fea-3be1c4bf-cd37-4c93-adf5-823db1db3130")
		.Request();

ItemEntitlement itemEntitlement = result.ItemEntitlement;
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    itementitlementAction "github.com/chargebee/chargebee-go/v3/actions/itementitlement"
    "github.com/chargebee/chargebee-go/v3/models/itementitlement"
    enum "github.com/chargebee/chargebee-go/v3/enum"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := itementitlementAction.UpsertOrRemoveItemEntitlementsForItem("enterprise", &itementitlement.UpsertOrRemoveItemEntitlementsForItemRequestParams{
        ItemEntitlements : []*itementitlement.UpsertOrRemoveItemEntitlementsForItemItemEntitlementParams{
            {
                FeatureId : "fea-3be1c4bf-cd37-4c93-adf5-823db1db3130",
            },
        },
        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.ItemEntitlementUpsertOrRemoveItemEntitlementsForItemRequest{
    ItemEntitlements : []*chargebee.ItemEntitlementUpsertOrRemoveItemEntitlementsForItemItemEntitlement{
        {
            FeatureId : "fea-3be1c4bf-cd37-4c93-adf5-823db1db3130",
        },
    },
    Action : chargebee.ActionRemove,
}
  res, err := client.ItemEntitlement.UpsertOrRemoveItemEntitlementsForItem("enterprise", 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 = ItemEntitlement.upsertOrRemoveItemEntitlementsForItem("enterprise")
            .action(Action.REMOVE)
            .itemEntitlementFeatureId(0, "fea-3be1c4bf-cd37-4c93-adf5-823db1db3130")
            .request();

    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.itemEntitlement.params.UpsertOrRemoveItemEntitlementsForItemParams;
import com.chargebee.v4.models.itemEntitlement.responses.UpsertOrRemoveItemEntitlementsForItemResponse;
import java.util.List;

public class UpsertOrRemoveItemEntitlementsForItem {

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

        UpsertOrRemoveItemEntitlementsForItemParams.ItemEntitlementsParams itemEntitlement0 =
            UpsertOrRemoveItemEntitlementsForItemParams.ItemEntitlementsParams.builder()
                .featureId("fea-3be1c4bf-cd37-4c93-adf5-823db1db3130")
                .build();

        List<UpsertOrRemoveItemEntitlementsForItemParams.ItemEntitlementsParams> itemEntitlementsList =
            List.of(itemEntitlement0);

        UpsertOrRemoveItemEntitlementsForItemParams params = UpsertOrRemoveItemEntitlementsForItemParams.builder()
            .action(UpsertOrRemoveItemEntitlementsForItemParams.Action.REMOVE)
            .itemEntitlements(itemEntitlementsList)
            .build();

        UpsertOrRemoveItemEntitlementsForItemResponse response = client
            .itemEntitlements()
            .upsertOrRemoveItemEntitlementsForItem("enterprise", params);

    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

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

try {
    const result = await chargebee.itemEntitlement.upsertOrRemoveItemEntitlementsForItem("enterprise", {
        item_entitlements: [
            {
                feature_id: "fea-3be1c4bf-cd37-4c93-adf5-823db1db3130"
            }
        ],
        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->itemEntitlement()->upsertOrRemoveItemEntitlementsForItem("enterprise", [
    "item_entitlements" => [
        [
            "feature_id" => "fea-3be1c4bf-cd37-4c93-adf5-823db1db3130"
        ]
    ],
    "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.ItemEntitlement.upsert_or_remove_item_entitlements_for_item("enterprise",
    cb_client.ItemEntitlement.UpsertOrRemoveItemEntitlementsForItemParams(
        item_entitlements=[
            cb_client.ItemEntitlement.UpsertOrRemoveItemEntitlementsForItemItemEntitlementParams(
              feature_id="fea-3be1c4bf-cd37-4c93-adf5-823db1db3130"
            )
        ],
        action=chargebee.Action.REMOVE
    )
)
entries = response.list
```

#### Ruby

```ruby
require 'chargebee'

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

result = ChargeBee::ItemEntitlement.upsert_or_remove_item_entitlements_for_item("enterprise",{
  :action => "REMOVE",
  :item_entitlements => [
    {
      :feature_id => "fea-3be1c4bf-cd37-4c93-adf5-823db1db3130"
    }
  ]
})

list = result.list
```

## Sample Response

```json
{
  "list": [
    {
      "item_entitlement": {
        "feature_id": "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62",
        "feature_name": "Quickbooks Integration_aie",
        "id": "item-ent-50a3657a-1452-4f7f-bb50-a8e5ac0a9907",
        "item_id": "basic",
        "item_type": "plan",
        "name": "Available",
        "object": "item_entitlement",
        "value": "true"
      }
    },
    {..}
  ]
}
```

## URL Format

**POST** https://[site].chargebee.com/api/v2/items/{item-id}/item_entitlements

## Input Parameters

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

- `item_entitlements` (optional, array)
  Parameters for item\_entitlements
  - `feature_id` (required, string, max chars=50)
    The `id` of the feature towards which this entitlement 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 `available` or `true`.

## Returns

- `item_entitlement` (Item entitlement object)
  Resource object representing item\_entitlement