Entitlements

API Version

Product Catalog

Library

The entitlement resource establishes a connection between a feature and an item or an item_price in Chargebee Billing. By defining this relationship, it specifies the scope of access or rights the item or item price has in relation to that particular feature.

Sample entitlement [ JSON ]

{
    "entitlement": {
        "feature_id": "fea-66ee05d2-2800-449f-a418-eaa863a67f9f",
        "feature_name": "Quickbooks Integration_1234",
        "id": "ent-15292c03-0b77-426a-aa5b-a18bb0acafdc",
        "entity_id": "enterprise",
        "entity_type": "plan",
        "name": "Available",
        "object": "entitlement",
        "value": "true"
    }
}

Model Class

Chargebee\Resources\Entitlement\Entitlement

id

string, max chars=100
A unique identifier for the entitlement. This is auto-generated.

entity_id

optional, string, max chars=100

The unique identifier of the entity being granted entitlement to a specific feature.

entity_type

optional, enumerated string
The type of the entity that holds this entitlement.

Possible values are

plan

Indicates that the entity is an item with type set to plan.

addon

Indicates that the entity is an item with type set to addon.

charge

Indicates that the entity is an item with type set to charge.

plan_price

Indicates that the entity is an item_price associated with an item of type plan.

addon_price

Indicates that the entity is an item_price associated with an item with type set to addon.

feature_id

optional, string, max chars=50

The unique identifier of the feature to which the entity gains entitlement.

feature_name

optional, string, max chars=50
The name of the feature associated with this entitlement.

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.

name

optional, string, max chars=50

The display name for the entitlement level. The value is automatically generated based on feature.type:

When feature.type is quantity or range, the name is the space-separated concatenation of value and the plural form of feature.unit. For instance, if value is 20 and feature.unit is user, the name will be 20 users.
When feature.type is custom, the name matches the 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.

id

string, max chars=100
A unique identifier for the entitlement. This is auto-generated.

entity_id

optional, string, max chars=100

The unique identifier of the entity being granted entitlement to a specific feature.

entity_type

optional, enumerated string
The type of the entity that holds this entitlement.

Possible values are

plan

Indicates that the entity is an item with type set to plan.

addon

Indicates that the entity is an item with type set to addon.

charge

Indicates that the entity is an item with type set to charge.

plan_price

Indicates that the entity is an item_price associated with an item of type plan.

addon_price

Indicates that the entity is an item_price associated with an item with type set to addon.

feature_id

optional, string, max chars=50

The unique identifier of the feature to which the entity gains entitlement.

feature_name

optional, string, max chars=50
The name of the feature associated with this entitlement.

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.

name

optional, string, max chars=50

The display name for the entitlement level. The value is automatically generated based on feature.type:

When feature.type is quantity or range, the name is the space-separated concatenation of value and the plural form of feature.unit. For instance, if value is 20 and feature.unit is user, the name will be 20 users.
When feature.type is custom, the name matches the 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.

Retrieves a list of all the entitlements associated with the specified feature.

Sample Codes

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

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
  "site" => "{site}",
  "apiKey" => "{apiKey}",
]);

$result = $chargebee->entitlement()->all([
    "limit" => 2,
    "offset" => "0"
]);
foreach($result->list as $entry){
  $entitlement = $entry->entitlement;
}

copy

Click to Copy

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

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
  "site" => "{site}",
  "apiKey" => "{apiKey}",
]);

$result = $chargebee->entitlement()->all([
    "limit" => 2,
    "offset" => "0"
]);
foreach($result->list as $entry){
  $entitlement = $entry->entitlement;
}

Sample Result [ JSON ]

{
    "list": [
        {
            "entitlement": {
                "feature_id": "fea-66ee05d2-2800-449f-a418-eaa863a67f9f",
                "feature_name": "Quickbooks Integration_1234",
                "id": "ent-15292c03-0b77-426a-aa5b-a18bb0acafdc",
                "entity_id": "enterprise",
                "entity_type": "plan",
                "name": "Available",
                "object": "entitlement",
                "value": "true"
            }
        },
        {..}
    ]
}

Method

$chargebee->entitlement->all([<param name> : <value>,<param name> : <value> ...])

limit[]

optional, integer, default=10, min=1, max=100
The number of resources to be returned.

offset[]

optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.

Filter Params

For operator usages, see the Pagination and Filtering section.

feature_id[<operator>]

optional, string filter
The id of the feature associated with this entitlement.
Supported operators : is, in

Example → "feature_id[is] = "user-licenses"

entity_type[<operator>]

optional, enumerated string filter
The type of the entity to which this entitlement belongs. Possible values are : plan, addon, charge, plan_price, addon_price
Supported operators : is, in

Example → "entity_type[is] = "plan_price"

entity_id[<operator>]

optional, string filter
The id of the entity to which this entitlement belongs. .
Supported operators : is, in

Example → "entity_id[is] = "usd-professional-monthly"

entitlement

always returned
Resource object representing entitlement

next_offset

optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.

Create, update, or remove a set of entitlements 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.

Sample Codes

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

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
  "site" => "{site}",
  "apiKey" => "{apiKey}",
]);

$result = $chargebee->entitlement()->create([
    "action" => "upsert",
    "entitlements" => [
    [
      "value" => "true",
      "feature_id" => "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62",
      "entity_id" => "enterprise",
      "entity_type" => "plan"
    ]
  ]
]);
$entitlement = $result->entitlement;

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

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
  "site" => "{site}",
  "apiKey" => "{apiKey}",
]);

$result = $chargebee->entitlement()->create([
    "action" => "remove",
    "entitlements" => [
    [
      "feature_id" => "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62",
      "entity_id" => "enterprise",
      "entity_type" => "plan"
    ]
  ]
]);
$entitlement = $result->entitlement;

copy

Click to Copy

Adding entitlements for a feature

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

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
  "site" => "{site}",
  "apiKey" => "{apiKey}",
]);

$result = $chargebee->entitlement()->create([
    "action" => "upsert",
    "entitlements" => [
    [
      "value" => "true",
      "feature_id" => "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62",
      "entity_id" => "enterprise",
      "entity_type" => "plan"
    ]
  ]
]);
$entitlement = $result->entitlement;

Removal of entitlements from a feature

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

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
  "site" => "{site}",
  "apiKey" => "{apiKey}",
]);

$result = $chargebee->entitlement()->create([
    "action" => "remove",
    "entitlements" => [
    [
      "feature_id" => "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62",
      "entity_id" => "enterprise",
      "entity_type" => "plan"
    ]
  ]
]);
$entitlement = $result->entitlement;

Sample Result [ 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"
            }
        },
        {..}
    ]
}

Method

$chargebee->entitlement->create([<param name> : <value>,<param name> : <value> ...])

action[]

required, enumerated string
The specific action to be performed for each entitlement specified.

Possible values are

upsertIf 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.removeDeletes the entitlement for the feature_id and entity_id combination, if it exists.

entitlements

Array containing object of parameters for entitlements
pass parameters as entitlements => [{"<param name>" => "<value>",...}, {..}...]

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 values are

plan

Indicates that the entity is an item with type set to plan.

addon

Indicates that the entity is an item with type set to addon.

chargeIndicates that the entity is an item with type set to charge.

plan_price

Indicates that the entity is an item_price associated with an item of type plan.

addon_price

Indicates that the entity is an item_price associated with an item with 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.

entitlement

always returned
Resource object representing entitlement

Sample entitlement [ JSON ]

API Index URL GET

Model Class

Entitlement attributes

Consent Fields for Entitlement

Custom Fields for Entitlement

List entitlements ¶

Notes

Sample Result [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Manage entitlements for a feature ¶

Notes

Sample Result [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL