Entitlements

Overview

Entitlements is a service that ensures player’s ownership of a specific item that they have purchased or earned. You can use Entitlements to grant or revoke items to or from players. There are two types of entitlements, as explained below:

  • Durable items are non-stackable and permanent. They do not disappear after use. Examples of durable items are, but 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 are, but not limited to: ammo, potions, and food.

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

Prerequisites

Permission

Make sure you’re authorized to use our services and have the following permissions before you attempt to manage players’ entitlements:

UsageResourceAction
Get User EntitlementADMIN:NAMESPACE:{namespace}:USER:{userId}:ENTITLEMENTRead
Get User Entitlement HistoryADMIN:NAMESPACE:{namespace}:USER:{userId}:ENTITLEMENTRead
Grant User EntitlementADMIN:NAMESPACE:{namespace}:USER:{userId}:ENTITLEMENTCreate
Disable User EntitlementADMIN:NAMESPACE:{namespace}:USER:{userId}:ENTITLEMENTUpdate
User EntitlementADMIN:NAMESPACE:{namespace}:USER:{userId}:ENTITLEMENTUpdate

Here’s the list of Action in Permission:

Entitlement Source

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

Entitlement SourceDescription
PurchaseEntitlement from normal purchase via real currency or virtual currency
PromotionEntitlement grant from some promotion/activity
Referral BonusEntitlement grant from inviting someone
Redeem CodeEntitlement from code redemption
OtherAnother kind of entitlement source that not belong to above

Please note that for now you can only choose between Purchase, Redeem_Code, and Other. If you choose any other source of entitlement except those three, you’ll only make a record that doesn’t affect anything.

Managing Entitlements in the Admin Portal

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

Get a Player’s Entitlements

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

  1. In the AccelByte Admin Portal, click the E-Commerce section and click the Entitlements menu.

    entitlement

  2. Specify the filter to search the player's entitlement by Full Entitlement ID, User ID, or Email. After that, input the keyword based on the chosen filter. Then, press the Enter button from your keyboard.

    entitlement

  3. Results appeared. Here you can see the information about the player’s entitlement.

    entitlement

List a Player’s Entitlement History

You can see the list of the player's entitlement history from the AccelByte Admin Portal. To do so, follow steps below:

  1. In the AccelByte Admin Portal, click the E-Commerce section and click the Entitlements menu.

    entitlement

  2. Specify the filter to search the player's entitlement by Full Entitlement ID, User ID, or Email. After that, input the keyword based on the chosen filter. Then, press the Enter button from your keyboard.

    entitlement

  3. The player’s entitlement information appeared. Choose the record in which you want to view the entitlement history, then click View.

    entitlement

  4. The Entitlement History pop up appears and displays the transaction history in descending order.

    entitlement

Grant an Entitlement to a Player

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

  1. In the AccelByte Admin Portal, click the E-Commerce section and click the Entitlements menu.

    entitlement

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

    entitlement

  3. The Grant Item form appears. Fill in the required fields:

    entitlement

    • Input the Add Item with the item you want to grant to a player.
    • Input the User ID with the player's id that you want to grant an entitlement. Then, click Add.
    • Input the Quantity of the item you want to grant to the player.
  4. When you’re finished, 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.

    entitlement

    entitlement

Disable a Player’s Entitlement

  1. In the AccelByte Admin Portal, click the E-Commerce section and click the Entitlements menu.

    entitlement

  2. Specify the filter to search the player's entitlement by Full Entitlement ID, User ID, or Email. After that, input the keyword based on the chosen filter. Then, press the Enter button from your keyboard.

    entitlement

  3. The player’s entitlement information appeared. Choose the record in which you want to disable.

    entitlement

  4. Click the three-dot button of the desired entitlement and click Disable.

    entitlement

  5. In the Admin Portal, 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.

    entitlement

    entitlement

Revoke a Player’s Entitlement

  1. In the AccelByte Admin Portal, click the E-Commerce section and click the Entitlements menu.

    entitlement

  2. Specify the filter to search the player's entitlement by Full Entitlement ID, User ID, or Email. After that, input the keyword based on the chosen filter. Then, press the Enter button from your keyboard.

    entitlement

  3. The player’s entitlement information appeared. Choose the record in which you want to revoke.

    entitlement

  4. Click the three-dot button of the desired entitlement and click Revoke.

    entitlement

  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.

    entitlement

    entitlement

Managing Entitlements with the SDK

An entitlement is granted automatically when a player places an order for an item. If this process is successful, the item will be granted to their account.

Check a Player’s Entitlements

For Players with a Subscriptions

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.

...
FRegistry::User.GetUserEligibleToPlay(THandler<bool>::CreateLambda([](bool result)
{
if(result)
{
UE_LOG(LogTemp, Log, TEXT("User eligible to play."));
}
else
{
UE_LOG(LogTemp, Log, TEXT("User is not eligible to play, no App or Subscription found in user's entitlements"));
}
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
UE_LOG(LogTemp, Log, TEXT("Failed to check user entitlements ownership. Error: %d | Message: %s"), ErrorCode, *ErrorMessage);
}));
...

For Players without a Subscription

If you don’t offer subscriptions, you can use the following code to check a player’s entitlements.

string itemId = "22c2bc2924d84755a7fd52fe300f231d";
Result<EntitlementPagingSlicedResult> entitlementResult = null;
AccelBytePlugin.GetEntitlement().QueryUserEntitlements("", itemId, 0, 0, result =>
{
entitlementResult = result;
});
while(entitlementResult == null){ yield return new WaitForSeconds(0.1f); }
if(entitlementResult.Value.data[0].status == EntitlementStatus.REVOKED)
{
//Quit the game
}

Managing Entitlements using API

You can also use our API endpoints to manage players’ entitlements.

Get a Player’s Entitlements

You can see the player's entitlement using the API. To do so, follow steps below:

  1. Use the Get User Entitlement: GET - admin/namespaces/{namespace}/users/{userId}/entitlements/{entitlementId} endpoint.
  2. Fill out the Namespace with Publisher Namespace.
  3. Fill out the User ID of the player whose entitlement you want to retrieve.
  4. Fill out the Entitlement ID with the entitlement you want to retrieve.

Upon a successful request, the player’s entitlement will appear. Here is the response example of the successful request:

Response Code: 200
{
"id": "string",
"namespace": "string",
"clazz": "APP",
"type": "DURABLE",
"status": "ACTIVE",
"appId": "string",
"appType": "GAME",
"sku": "string",
"userId": "string",
"storeId": "string",
"itemId": "string",
"grantedCode": "string",
"itemNamespace": "string",
"name": "string",
"features": [
"string"
],
"useCount": 0,
"quantity": 0,
"source": "PURCHASE",
"distributedQuantity": 0,
"targetNamespace": "string",
"itemSnapshot": {
"itemId": "string",
"appId": "string",
"appType": "GAME",
"baseAppId": "string",
"sku": "string",
"namespace": "string",
"name": "string",
"entitlementType": "DURABLE",
"useCount": 0,
"stackable": true,
"itemType": "APP",
"thumbnailUrl": "string",
"targetNamespace": "string",
"targetCurrencyCode": "string",
"targetItemId": "string",
"title": "string",
"description": "string",
"regionDataItem": {
"price": 0,
"discountPercentage": 0,
"discountAmount": 0,
"discountedPrice": 0,
"currencyCode": "USD",
"currencyType": "REAL",
"currencyNamespace": "string",
"trialPrice": 0,
"purchaseAt": "2021-04-26T01:19:10.294Z",
"expireAt": "2021-04-26T01:19:10.294Z",
"discountPurchaseAt": "2021-04-26T01:19:10.294Z",
"discountExpireAt": "2021-04-26T01:19:10.294Z"
},
"recurring": {
"cycle": "WEEKLY",
"fixedFreeDays": 0,
"fixedTrialCycles": 0,
"graceDays": 0
},
"itemIds": [
"string"
],
"features": [
"string"
],
"maxCountPerUser": 0,
"maxCount": 0,
"boothName": "string",
"region": "string",
"language": "string",
"createdAt": "2021-04-26T01:19:10.294Z",
"updatedAt": "2021-04-26T01:19:10.294Z"
},
"startDate": "2021-04-26T01:19:10.294Z",
"endDate": "2021-04-26T01:19:10.294Z",
"stackable": true,
"grantedAt": "2021-04-26T01:19:10.294Z",
"createdAt": "2021-04-26T01:19:10.294Z",
"updatedAt": "2021-04-26T01:19:10.294Z"
}

List a Player’s Entitlement History

You can see the player's entitlement history using the API. To do so, follow steps below:

  1. Use the Get User Entitlement History: GET - /admin/namespaces/{namespace}/users/{userId}/entitlements/{entitlementId}/history endpoint.
  2. Fill out the Namespace with Publisher Namespace.
  3. Fill out the User ID of the player whose entitlement you want to retrieve.
  4. Fill out the Entitlement ID with the entitlement you want to retrieve.

Upon a successful request, the player’s entitlement history will appear. Here is the response example of the successful request:

Response Code: 200
[
{
"entitlementId": "string",
"namespace": "string",
"action": "GRANT",
"operator": "string",
"userId": "string",
"useCount": 0,
"quantity": 0,
"createdAt": "2021-04-26T01:35:09.107Z",
"updatedAt": "2021-04-26T01:35:09.107Z"
}
]

Grant an Entitlement to a Player

You can grant an entitlement to a player using the API. To do so, follow steps below:

  1. Use the Grant User Entitlement: POST - /admin/namespaces/{namespace}/users/{userId}/entitlements endpoint.
  2. Fill out the Namespace with Publisher Namespace.
  3. Fill out the Request Body:
    • Fill out the relevant item’s Item ID.
    • Fill out the Granted Code if the item type is code. For other entitlement types, leave this field empty.
    • Fill out the Item Namespace with the namespace where the Item belongs.
    • Fill out the Quantity of the item you want to grant.
    • Fill out the Source of the entitlement.** **Please refer to the Entitlement Source list above for the details.
    • Fill out the Region of the item. This should match the player’s region.
    • Fill out the Language of the item. This should match the player’s language.

Upon a successful request, player’s will be granted with an entitlement. Here is the response example of the successful request:

Response: 200
[
{
"storeId": "string",
"itemId": "string",
"grantedCode": "string",
"itemNamespace": "string",
"quantity": 0,
"source": "PURCHASE",
"startDate": "2021-04-26T02:18:40.035Z",
"endDate": "2021-04-26T02:18:40.035Z",
"region": "string",
"language": "string"
}
]

Disable a Player’s Entitlement

You can disable a player’s entitlements using the API. Disabled entitlement can’t be used or consumed. Only active entitlements can be disabled. To do so, follow steps below:

  1. Use the Disable User Entitlement: PUT - /admin/namespaces/{namespace}/users/{userId}/entitlements/{entitlementId}/disable endpoint.
  2. Fill out the Namespace with Publisher Namespace.
  3. Fill out the User ID of the player whose entitlement you want to disable.
  4. Fill out the Entitlement ID with the entitlement you want to disable.

Upon a successful request, player’s entitlement will be disabled. Here is the response example of the successful request:

Response Code: 200
{
"id": "string",
"namespace": "string",
"clazz": "APP",
"type": "DURABLE",
"status": "ACTIVE",
"appId": "string",
"appType": "GAME",
"sku": "string",
"userId": "string",
"storeId": "string",
"itemId": "string",
"grantedCode": "string",
"itemNamespace": "string",
"name": "string",
"features": [
"string"
],
"useCount": 0,
"quantity": 0,
"source": "PURCHASE",
"distributedQuantity": 0,
"targetNamespace": "string",
"itemSnapshot": {
"itemId": "string",
"appId": "string",
"appType": "GAME",
"baseAppId": "string",
"sku": "string",
"namespace": "string",
"name": "string",
"entitlementType": "DURABLE",
"useCount": 0,
"stackable": true,
"itemType": "APP",
"thumbnailUrl": "string",
"targetNamespace": "string",
"targetCurrencyCode": "string",
"targetItemId": "string",
"title": "string",
"description": "string",
"regionDataItem": {
"price": 0,
"discountPercentage": 0,
"discountAmount": 0,
"discountedPrice": 0,
"currencyCode": "USD",
"currencyType": "REAL",
"currencyNamespace": "string",
"trialPrice": 0,
"purchaseAt": "2021-04-26T02:40:12.308Z",
"expireAt": "2021-04-26T02:40:12.308Z",
"discountPurchaseAt": "2021-04-26T02:40:12.308Z",
"discountExpireAt": "2021-04-26T02:40:12.308Z"
},
"recurring": {
"cycle": "WEEKLY",
"fixedFreeDays": 0,
"fixedTrialCycles": 0,
"graceDays": 0
},
"itemIds": [
"string"
],
"features": [
"string"
],
"maxCountPerUser": 0,
"maxCount": 0,
"boothName": "string",
"region": "string",
"language": "string",
"createdAt": "2021-04-26T02:40:12.308Z",
"updatedAt": "2021-04-26T02:40:12.308Z"
},
"startDate": "2021-04-26T02:40:12.308Z",
"endDate": "2021-04-26T02:40:12.308Z",
"stackable": true,
"grantedAt": "2021-04-26T02:40:12.308Z",
"createdAt": "2021-04-26T02:40:12.308Z",
"updatedAt": "2021-04-26T02:40:12.308Z"
}

Revoke a Player’s Entitlement

You can revoke a player’s entitlements using the API. Revoking an entitlement causes it to be permanently disabled. This action cannot be undone, so ensure that the item won’t need to be enabled again before choosing to revoke it. To do so, follow steps below:

  1. Use the Revoke User Entitlement: PUT - /admin/namespaces/{namespace}/users/{userId}/entitlements/{entitlementId}/revoke endpoint.
  2. Fill out the Namespace with Publisher Namespace.
  3. Fill out the User ID of the player whose entitlement you want to revoke.
  4. Fill out the Entitlement ID with the entitlement you want to revoke.

Upon successful request, the player's entitlement will be revoked. Here is the response example of the successful request:

Response Code: 200
{
"id": "string",
"namespace": "string",
"clazz": "APP",
"type": "DURABLE",
"status": "ACTIVE",
"appId": "string",
"appType": "GAME",
"sku": "string",
"userId": "string",
"storeId": "string",
"itemId": "string",
"grantedCode": "string",
"itemNamespace": "string",
"name": "string",
"features": [
"string"
],
"useCount": 0,
"quantity": 0,
"source": "PURCHASE",
"distributedQuantity": 0,
"targetNamespace": "string",
"itemSnapshot": {
"itemId": "string",
"appId": "string",
"appType": "GAME",
"baseAppId": "string",
"sku": "string",
"namespace": "string",
"name": "string",
"entitlementType": "DURABLE",
"useCount": 0,
"stackable": true,
"itemType": "APP",
"thumbnailUrl": "string",
"targetNamespace": "string",
"targetCurrencyCode": "string",
"targetItemId": "string",
"title": "string",
"description": "string",
"regionDataItem": {
"price": 0,
"discountPercentage": 0,
"discountAmount": 0,
"discountedPrice": 0,
"currencyCode": "USD",
"currencyType": "REAL",
"currencyNamespace": "string",
"trialPrice": 0,
"purchaseAt": "2021-04-26T02:43:07.696Z",
"expireAt": "2021-04-26T02:43:07.696Z",
"discountPurchaseAt": "2021-04-26T02:43:07.696Z",
"discountExpireAt": "2021-04-26T02:43:07.696Z"
},
"recurring": {
"cycle": "WEEKLY",
"fixedFreeDays": 0,
"fixedTrialCycles": 0,
"graceDays": 0
},
"itemIds": [
"string"
],
"features": [
"string"
],
"maxCountPerUser": 0,
"maxCount": 0,
"boothName": "string",
"region": "string",
"language": "string",
"createdAt": "2021-04-26T02:43:07.696Z",
"updatedAt": "2021-04-26T02:43:07.696Z"
},
"startDate": "2021-04-26T02:43:07.696Z",
"endDate": "2021-04-26T02:43:07.696Z",
"stackable": true,
"grantedAt": "2021-04-26T02:43:07.696Z",
"createdAt": "2021-04-26T02:43:07.696Z",
"updatedAt": "2021-04-26T02:43:07.696Z"
}

Related Concepts

  • Check out the API Reference for more information about entitlements.
  • Learn more about our Fulfillments service, which is used to grant players entitlements.
  • One way you can grant your players entitlements is through promotional campaigns. Learn more about our Campaign service here.