Entitlements

The entitlement service provides a way to verify whether a user is still owed rewards after a purchase. This is useful when the checkout flow is interrupted or when the client needs to restore rewards that were not granted successfully.

Overview

Entitlements can be created from two sources:

• Google / Apple validation

• AppCharge grant-award callback

The service stores pending entitlements for a user, and the client is responsible for:

1. Retrieving any pending entitlements

2. Granting the corresponding in-game rewards

3. Marking the entitlement as consumed once the reward has been successfully granted

Apple / Google

When using the Lion Validator, an entitlement is created automatically after a successful purchase validation.

AppCharge

AppCharge can also create entitlements through its grant-award server callback.

Reference: AppCharge grant-award callback

---

Enable Entitlements

To use the entitlement system, it must first be enabled in the Lion Settings Manager.

In Unity, go to:

Lion Studios → Settings Manager

Under the Purchase Validator section, enable the Entitlements option by checking the box.

Once enabled, the entitlement system will initialize automatically at runtime.

---

Initialize

The Entitlement Service is initialized automatically once the WhoAmI Service receives a unique user ID for the player.

No manual initialization is required.

---

Consume an Entitlement

After the client successfully grants the reward, mark the entitlement as consumed.

You can consume entitlements in any of the following ways:

EntitlementHandler.ConsumeEntitlement(string entitlementId)
EntitlementHandler.ConsumeEntitlements(PendingEntitlements pendingEntitlements)
EntitlementHandler.ConsumeEntitlement(List<string> entitlementList)

When entitlements are enabled, you must consume every entitlement after its reward has been granted. If an entitlement is not consumed, it may be returned again in future pending entitlement requests, which could cause the player to receive the reward multiple times.

Do not consume the entitlement before the reward has been granted successfully on the client. Consuming too early may cause the player to lose access to a reward that was never delivered.

Lion Validator

If you use the Lion Validator to validate Apple or Google receipts, the validation response may include an entitlementId.

After the purchase has been validated and the reward has been granted successfully, use the returned entitlementId to consume the entitlement.

AppCharge

When processing an AppCharge purchase, use the OrderResponseModel information to grant and consume the purchase entitlement.

private void ProcessAppChargePurchase(OrderResponseModel orderInfo) 
{
    // Grant the reward associated with orderInfo.offerSku.
    GrantReward(orderInfo.offerSku);
    EntitlementHandler.ConsumeEntitlement(orderInfo.purchaseId);
}

For AppCharge purchases, orderInfo.purchaseId is used as the entitlement identifier.

Important

When entitlements are enabled, every granted reward must be followed by a consume call. If the entitlement is not consumed, the reward may be returned again later as a pending entitlement.

---

Retrieve Pending Entitlements

When the Entitlements service initializes, it automatically requests all unconsumed entitlements for the current user from Lion servers.

You can listen for pending entitlements using the following event:

EntitlementHandler.OnEntitlementsRetrieved += HandlePendingEntitlements;

Example:

private void HandlePendingEntitlements(PendingEntitlements pendingEntitlements)
{
    foreach (var entitlement in pendingEntitlements.entitlements)
    {
        // Grant the reward associated with entitlement.sku.
        GrantReward(entitlement.sku);
    }
    
    EntitlementHandler.ConsumeEntitlements(pendingEntitlements);
}

PendingEntitlement Data Structure

The PendingEntitlements data structure contains a simple list of entitlements waiting to be consumed.

entitlements	List<Entitlement>	List of pending entitlements for the current user.

Entitlement Data Structure

entitlementId	string	Unique identifier for the entitlement record. Required when consuming the entitlement.
sku	string	Product SKU associated with the reward that should be granted.

---

Behavior Notes

What the service does

• Tracks whether a purchase resulted in a pending entitlement

• Returns any unconsumed entitlements for a user

• Marks entitlements as consumed when the client confirms the reward was granted

What the service does not do

• It does not grant in-game rewards automatically on the client

• It does not know how each game wants to map SKUs to rewards

Reward delivery must be implemented by the game.

---