Entitlements

Overview

Entitlements is the service that ensures a player’s ownership of a specific item that they have purchased or otherwise 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, meaning they do not disappear after use. Examples include game skins or unlockable characters.

  • Consumable items disappear after use, like ammo or potions. 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.

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

Tutorials

Get a Player’s Entitlements

Get a Player’s Entitlements Using API

You can retrieve a player’s entitlements by following the steps below:

  1. Use the Get User Entitlement: GET /admin/namespaces/{namespace}/users/{userId}/entitlements/{entitlementId} endpoint.
  2. Input the Namespace with the publisher namespace.
  3. Input the player’s User ID.
  4. Input the Entitlement ID. Upon successful request, the entitlements will be retrieved.

Get a Player’s Entitlements Through the Admin Portal

  1. In the E-Commerce section of the Admin Portal, open the Entitlements menu.

    entitlement

  2. Filter the search by User ID and input the player’s User ID. the player’s entitlements will be listed.

    entitlement

    You can also see the History of each Item by clicking View next to that item.

    entitlement

Grant an Entitlement to a Player

Grant an Entitlement to a Player Using API

To grant an entitlement to a player, follow the steps below:

  1. Use the Grant User Entitlement: POST /admin/namespaces/{namespace}/users/{userId}/entitlements endpoint.
  2. Input the Namespace with the publisher namespace.
  3. Fill out the Request Body:
    • Input the relevant item’s Item ID.
    • Input the Granted Code if the item type is code. For other entitlement types, leave this field empty.
    • Input the Item Namespace with the namespace where the Item belongs.
    • Input the Quantity of the item you want to grant.
    • Input the Source of the entitlement. Options include Purchase, Promotion, Referral Bonus, Redeem Code, and Other.
    • Input the Region of the item. This should match the player’s region.
    • Input the Language of the item. This should match the player’s language.

Upon successful request, the entitlement will be granted.

Grant an Entitlement to a Player Through the Admin Portal

  1. In the E-Commerce section of the Admin Portal, open the Entitlement menu. To grant an item, click the Grant Item button.

    entitlement

  2. After the form appears, fill in the required fields.

    entitlement

    • Select the Item you want to grant.
    • Select the player you want to grant the item to by typing their User ID. Then, click Add.
    • Input the Quantity of the item you want to grant to the player.
  3. When you’re done, click the Grant button and the entitlement will be granted to the player.

    entitlement

    The entitlement will appear in the player’s account in the Player Portal.

    entitlement

Disable a Player’s Entitlement

Disable a Player’s Entitlement Using API

You can disable a player’s entitlements, so that they cannot be used or consumed. Only active entitlements can be disabled.

  1. Use the Disable User Entitlement: PUT /admin/namespaces/{namespace}/users/{userId}/entitlements/{entitlementId}/disable endpoint.
  2. Input the Namespace with the publisher namespace.
  3. Input the player’s User ID.
  4. Input the Entitlement ID of the entitlement you want to disable. Upon successful request, the entitlement will be disabled.

Disable a Player’s Entitlement Through the Admin Portal

  1. In the Admin Portal, find the player whose entitlement you want to disable. Their Entitlements information will appear. Click Disable in the Actions column next to the item you want to disable.

    entitlement

    In the Admin Portal, the Status of the item will be changed to Inactive.

    entitlement

    Meanwhile, the item will be removed from the player’s account in the Player Portal.

    entitlement

Revoke a Player’s Entitlement

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.

Revoke a Player’s Entitlement Using API

  1. Use the Revoke User Entitlement: PUT /admin/namespaces/{namespace}/users/{userId}/entitlements/{entitlementId}/revoke endpoint.
  2. Input the Namespace with the publisher namespace.
  3. Input the player’s User ID.
  4. Input the Entitlement ID of the entitlement you want to revoke. Upon successful request, the entitlement will be revoked.

Revoke a Player’s Entitlement Through the Admin Portal

  1. Find the player whose entitlement you want to revoke. Their Entitlements information will appear. Click Revoke in the Actions column next to the item you want to revoke.

    entitlement

    In the Admin Portal, the Status of the item will be changed to Revoked.

    entitlement

    Meanwhile, the item will be removed from the player’s account in the Player Portal.

    entitlement

What’s Next?

  • 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.