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 directly set the value
for any subscription_entitlement
.
entitlement_override
expiry
If 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-be1a9281-d8df-48ce-82e2-294667eb4d94",
"feature_name": "Quickbooks Integration_123",
"id": "override-1935f8d6-b791-4181-9fa2-65fd8bfbd7ae",
"name": "Available",
"object": "entitlement_override",
"value": "true"
}
}
API Index URL GET
https://{site}.chargebee.com/api/v2/entitlement_overrides
Model Class
ChargeBee::EntitlementOverride
string, max chars=50 Unique identifier for the entitlement override. This is always auto-generated.
optional, string, max chars=50 The id
of the subscription to which this entitlement override belongs.
optional, string, max chars=50 The name of Chargebee resource that this entitlement override is associated with. The value is always subscription
.
optional, string, max chars=50 The id
of the feature
towards which this entitlement override has been granted.
optional, string, max chars=50 The name
of the feature
towards which this entitlement override has been granted.
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.
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
.
optional, timestamp(UTC) in seconds The expiry date for the entitlement_override
. Once expired, the entitlement_override
object is no longer returned.
optional, timestamp(UTC) in seconds
string, max chars=50 Unique identifier for the entitlement override. This is always auto-generated.
optional, string, max chars=50 The id
of the subscription to which this entitlement override belongs.
optional, string, max chars=50 The name of Chargebee resource that this entitlement override is associated with. The value is always subscription
.
optional, string, max chars=50 The id
of the feature
towards which this entitlement override has been granted.
optional, string, max chars=50 The name
of the feature
towards which this entitlement override has been granted.
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.
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
.
optional, timestamp(UTC) in seconds The expiry date for the entitlement_override
. Once expired, the entitlement_override
object is no longer returned.
optional, timestamp(UTC) in seconds Upserts or removes a set of entitlement_overrides
for a subscription
depending on the action
specified. The API returns the upserted or deleted entitlement_overrides
after successfully completing the operation. The operation returns an error when the first entitlement_override
fails to be processed. Either all the entitlement_overrides
provided in the request are processed or none.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Adding entitlement overrides for a feature
require 'chargebee'
ChargeBee.configure(:site => "{site}",
:api_key => "{site_api_key}")
result = ChargeBee::EntitlementOverride.add_entitlement_override_for_subscription("Jdf63vklssSDFdb",{
:action => "UPSERT",
:entitlement_overrides => [
{
:feature_id => "fea-be1a9281-d8df-48ce-82e2-294667eb4d94",
:value => "true"
}]
})
entitlement_override = result.entitlement_override
Adding entitlement overrides for a feature
require 'chargebee'
ChargeBee.configure(:site => "{site}",
:api_key => "{site_api_key}")
result = ChargeBee::EntitlementOverride.add_entitlement_override_for_subscription("Jdf63vklssSDFdb",{
:action => "UPSERT",
:entitlement_overrides => [
{
:feature_id => "fea-be1a9281-d8df-48ce-82e2-294667eb4d94",
:value => "true"
}]
})
entitlement_override = result.entitlement_override
Adding entitlement overrides for a feature
require 'chargebee'
ChargeBee.configure(:site => "{site}",
:api_key => "{site_api_key}")
result = ChargeBee::EntitlementOverride.add_entitlement_override_for_subscription("Jdf63vklssSDFdb",{
:action => "UPSERT",
:entitlement_overrides => [
{
:feature_id => "fea-be1a9281-d8df-48ce-82e2-294667eb4d94",
:value => "true",
:expires_at => 1649243933
}]
})
entitlement_override = result.entitlement_override
Removing entitlement overrides from a subscription
require 'chargebee'
ChargeBee.configure(:site => "{site}",
:api_key => "{site_api_key}")
result = ChargeBee::EntitlementOverride.add_entitlement_override_for_subscription("Jdf63vkLssSDFdb",{
:action => "REMOVE",
:entitlement_overrides => [
{
:feature_id => "fea-49bdaffa-1a71-429c-b2f7-5be5f89a37eb"
}]
})
entitlement_override = result.entitlement_override
Sample Result [ JSON ]
Show more...
{
"list": [
{
"entitlement_override": {
"entity_id": "Jdf63vklssSDFdb",
"entity_type": "subscription",
"feature_id": "fea-be1a9281-d8df-48ce-82e2-294667eb4d94",
"feature_name": "Quickbooks Integration_123",
"id": "override-1935f8d6-b791-4181-9fa2-65fd8bfbd7ae",
"name": "Available",
"object": "entitlement_override",
"value": "true"
}
},
{..}
]
}
URL Format
POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/entitlement_overrides
Method
ChargeBee::EntitlementOverride.add_entitlement_override_for_subscription(<subscription_id>,{<param name> => <value>,<param name> => <value> ...})
optional, enumerated string The specific action to be performed for each entitlement_override
specified. . Possible values are
upsertIf the entitlement_override
already exists for the feature_id
and {subscription_id}
combination, the value
of the entitlement_override
is updated. If it doesn’t exist, a new entitlement_override
is created.removeDeletes the entitlement_override
for the feature_id
and item_id
combination, if it exists.
upsertIf the entitlement_override
already exists for the feature_id
and {subscription_id}
combination, the value
of the entitlement_override
is updated. If it doesn’t exist, a new entitlement_override
is created.removeDeletes the entitlement_override
for the feature_id
and item_id
combination, if it exists.
Show all values[+]
optional, array Array containing hash of parameters for entitlement_overrides
Array containing hash of parameters for entitlement_overrides
pass parameters as entitlement_overrides => [{"<param name>" => "<value>",...}, {..}...]
required, string, max chars=50 The id
of the feature
towards which this entitlement override has been granted. 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.
optional, timestamp(UTC) in seconds The expiry date for the entitlement_override
. When not passed, the entitlement_override
does not expire. This must be a value in the future and is relevant only when the action
is upsert
. The entitlement_override
object is no longer returned after this date has passed. optional, timestamp(UTC) in seconds
always returned required
Resource object representing entitlement_override
Sample admin console URL
https://{site}.chargebee.com/admin-console/entitlement_overrides/123x
Retrieve the list of entitlement overrides for a subscription.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
require 'chargebee'
ChargeBee.configure(:site => "{site}",
:api_key => "{site_api_key}")
list = ChargeBee::EntitlementOverride.list_entitlement_override_for_subscription("Jdf63vkLssSDFdb")
:limit => 1,
:offset => "0"
})
list.each do |entry|
entitlement_override = entry.entitlement_override
end
require 'chargebee'
ChargeBee.configure(:site => "{site}",
:api_key => "{site_api_key}")
list = ChargeBee::EntitlementOverride.list_entitlement_override_for_subscription("Jdf63vkLssSDFdb")
:limit => 1,
:offset => "0"
})
list.each do |entry|
entitlement_override = entry.entitlement_override
end
Sample Result [ JSON ]
Show more...
{
"list": [
{
"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"
}
},
{..}
]
}
URL Format
GET
https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/entitlement_overrides
Method
ChargeBee::EntitlementOverride.list_entitlement_override_for_subscription(<subscription_id>,{<param name> => <value>,<param name> => <value> ...})
optional, integer, default=10, min=1, max=100 The number of resources to be returned.
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.
always returned required
Resource object representing entitlement_override
always returned 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`.
Sample admin console URL
https://{site}.chargebee.com/admin-console/entitlement_overrides/123x