Entitlements

Overview

AccelByte Cloud’s Entitlements service manages player’s ownership of items that they have purchased or earned. You can use Entitlements to grant or revoke items to or from players.

There are two types of entitlement, as explained below:

• Durable items are non-stackable and permanent. They do not disappear after use. Examples of durable items include, but are not limited to, game skins, weapons, and unlockable characters.
• Consumable items disappear after use. Consumables can be stackable or non-stackable; multiple stackable items will be under the same entitlement whereas multiple non-stackable items will each have their own entitlement, even if they’re identical items. Examples of consumable items include, but are not limited to: ammo, potions, and food.

Entitlement management lets you see the entitlement history of a particular player.

Permissions

Permissions (opens new window) are used to grant access to specific resources within our services. Make sure your account has the following permissions before you attempt to manage entitlement in the Admin Portal. For a full list of permissions that impact entitlement management, see the Platform/Commerce tab of the permissions reference (opens new window).

Usage	Resource	Action
Get User Entitlement	ADMIN:NAMESPACE:{namespace}:USER:{userId}:ENTITLEMENT	READ
Get User Entitlement History	ADMIN:NAMESPACE:{namespace}:USER:{userId}:ENTITLEMENT	READ
Grant User Entitlement	ADMIN:NAMESPACE:{namespace}:USER:{userId}:ENTITLEMENT	CREATE
Disable User Entitlement	ADMIN:NAMESPACE:{namespace}:USER:{userId}:ENTITLEMENT	UPDATE
User Entitlement	ADMIN:NAMESPACE:{namespace}:USER:{userId}:ENTITLEMENT	UPDATE

Permissions work slightly differently depending on whether they are assigned to IAM clients or are roles assigned to users. For more information, read the Authentication and Authorization documentation.

Entitlement Source

There are many different types of entitlement sources that can be applied to players. Here is a description of each entitlement source:

Entitlement Source	Description
Purchase	Entitlement from normal purchase via real currency or virtual currency
Promotion	Entitlement grant from some promotion/activity
Referral_Bonus	Entitlement grant from inviting someone
Redeem_Code	Entitlement from code redemption
Other	Another kind of entitlement source that not belong to above

NOTE

For now, you can only choose Purchase, Redeem_Code or Other. If you choose any other source of entitlement, your record will not affect anything.

Manage Entitlements in the Admin Portal

The Admin Portal gives community managers and game admins an easy way to manage players’ entitlements.

Search for a Player’s Entitlements

You can retrieve the list of the player's entitlements through the AccelByte Admin Portal. To do so, follow the steps below:

1. In the AccelByte Admin Portal, click the E-Commerce section and click Entitlements from the options underneath.

   

2. In the Search field of the Entitlements panel, choose to search by Full Entitlement ID, User ID, or Email.

   

3. Input the search words, for example, for Email you would input the player’s email address.

   

4. If you choose User ID or Email as a filter, you can also filter the result based on the Entitlement Class and Features Name.

   

   • Entitlement Class filters results based on their item type. You can choose All, App, Entitlement, Code, Subscription, Media, and Option Box.

     NOTE

     The Entitlement option in the Entitlement Class field gives you the option to choose an item type other than App, Code, Subscription, Media, or Option Box. To read more about item types, see the E-Commerce (opens new window) documentation.

   • Use Features Name to filter results based on their features. You can enter multiple feature names by pressing Enter then adding another feature.

     NOTE

     To read more about adding feature names, including adding a feature to an item, see Create an Item in a Store (opens new window).

5. When you’re done, click the Apply Filter button.

   

List a Player’s Entitlement History

You can see the history of a player's entitlements through the AccelByte Admin Portal. To do so, follow the steps below:

1. In the AccelByte Admin Portal, click the E-Commerce section and click Entitlements from the options underneath.

   

2. In the Search field of the Entitlements panel, search for the player’s entitlement (opens new window).

   

3. Choose the record you want to view from the list of entitlements by clicking View.

   

   The Entitlement History pop-up displays the entitlement history in descending order.

   

Grant an Entitlement to a Player

You can grant an entitlement to a player through the AccelByte Admin Portal. To do so, follow the steps below:

1. In the AccelByte Admin Portal, click the E-Commerce section and click Entitlements from the options underneath.

   

2. In the Entitlements page, click the Grant Item button.

   

   The Grant Item form appears.

   

3. Fill in the required fields:

   • In the Add Item field, select the item you want to grant to a player.
   • Input the User ID of the player that you want to grant an entitlement to in the Select User field. Then, click Add.
   • Input the Quantity of the item you want to grant to the player.

4. Once you have completed all the fields, click the Grant button. The new entitlement will be granted to the player and will appear in the player’s account in the Player Portal.

Disable a Player’s Entitlement

You can disable a player’s entitlement through the AccelByte Admin Portal. To do so, follow the steps below:

1. In the AccelByte Admin Portal, click the E-Commerce section and click Entitlements from the options underneath.

   

2. In the Entitlements panel, search (opens new window) for the record you want to disable.

   

3. In the selected record, click the More Actions (...) icon under the Action column, then click Disable.

   

4. The Disable Entitlement form appears. Click Confirm.

   

5. The Status of the item will be changed to Inactive and the item will be removed from the player’s account in the Player Portal.

Revoke a Player’s Entitlement

You can revoke a player’s entitlement through the AccelByte Admin Portal. To do so, follow the steps below:

1. In the AccelByte Admin Portal, click the E-Commerce section and click Entitlements from the options underneath.

   

2. In the Entitlements panel, search (opens new window) for the entitlements for that player.

   

3. In the selected record, click the More Actions (...) icon under the Action row, then click Disable.

   

4. The Revoke Entitlement form appears. Click Confirm.

   

5. In the Admin Portal, the Status of the item will be changed to Revoked and the item will be removed from the player’s account in the Player Portal.

Implement Entitlements with the Client SDKs

An entitlement is granted automatically when a player places an order for an item. The item is added to their account.

Check a Player’s Entitlements

For Players with a Subscription

If your game or platform offers a subscription to your players, you can use the following code to check a player’s entitlements and subscription plan.

For Players without a Subscription

If you don’t offer subscriptions, you can use the following code to check a player’s entitlements. To get all of the player’s entitlements, set the EntitlementNameand ItemIdto "" (empty string).

The response object from QueryUserEntitlements() contains an array of entitlement info that includes all entitlement-related IDs such as EntitlementId, ItemId and SKUId. These IDs can later be used to get item or specific entitlement information.

NOTE

In some cases, we recommend using the SKU-related functions if you have your own item id that isn't namespace and environment dependent. You can define the SKU ID manually in the Admin Portal, unlike ItemId which is generated automatically. See our Create an Item (opens new window) documentation for more details.

Check Redeemed Items in Entitlements

To check redeemed items, you can call getUserEntitlementById from the Entitlement API. The response includes itemSnapshot which contains detailed information regarding the redeemed item. When the entitlement is a result of a redeem code process, the entitlement source shown in the response should be REDEEM_CODE.

Get User Entitlements By SKU

This function is not yet supported by our SDKs, although the endpoint API (opens new window) is available.

3rd Party Item Entitlement Synchronization

Apple

To synchronize Apple entitlement, use the following function.

Google Play

To synchronize Google Play entitlement, use the following function.

Twitch

To synchronize Twitch Drop entitlement, use the following function.