Iaptic allows you to chose between different entitlement strategies for associating purchases with your application users.
What is an entitlement strategy?
It defines which user have access to a particular purchase.
Why do we need this?
Sometime, the same App Store or Google Play account is used on many devices. In other cases, a device is shared by different persons. As such, many of your users might present the same purchase receipt. The entitlement strategy defines which of those users have access to the content: all of them, only the first or last to present the receipt.
Important Concepts
Purchases vs Receipts
Entitlements are associated with individual purchases, not receipts. A single receipt can contain multiple purchases, and each purchase follows the configured entitlement strategy independently.
Store Account Behavior
With the LAST strategy, when a user opens the app while signed into a Store account (Apple/Google), they become associated with all active purchases for that Store account. This means if multiple users use the same Store account, the purchases will transfer to whoever most recently validated the receipt.
API Priority and Permanence
Manual purchase associations made through the API have higher priority than receipt validation:
- Once a purchase is manually associated using the API, subsequent receipt validations won't change this association
- Only another API call can modify a manual association
- This applies to all strategies, including LAST
Available Strategies
- ALL - All claiming users have access to the feature.
- FIRST - Only the first claiming user has access to the feature. Any later claims will be ignored.
- LAST - Only the last claiming user has access to the feature. The previously entitled user loose access.
A claiming user is a user that presents a valid receipt for a purchase through a receipt validation request.
Strategy Details
All Claimers
This is the default strategy. Anyone presenting a valid receipt for a purchase becomes entitled to it. There is no limit to the number of entitled users for a purchase. This strategy is recommended for new apps as it's the simplest to implement and matches the typical user expectation of having access to their Store purchases.
First claimer
With this strategy, only the first user who presented a valid receipt is entitled to the purchase. Subsequent receipt validation requests won't change the entitled user, so you can think of it as a non transmissible entitlement.
The only way to change the user associated with the purchase is to make a manual purchase association request. When using this endpoint, the last request will always have priority. So you can keep changing the associated user many times.
Implementation Note: This strategy may require implementing purchase migration or subscription groups in your app, especially when handling cases where an existing Store account subscription is already attached to a different user.
Last claimer
With this strategy, only the last user who presented a valid receipt is entitled to the purchase. Subsequent receipt validation request will always update the entitled user (when it's different from the active one), so you can view it as automatically transmitted entitlement.
You can also change the user associated with the purchase by making a manual purchase association request. Those requests have a higher priority, thus, after you've done this with a purchase, subsequent receipt validation request won't update the entitled user anymore.
Implementation Note: This strategy works well for shared devices or accounts but requires your app to handle cases where entitlements might change during usage.
Common Scenarios
sequenceDiagram
participant User1
participant User2
participant Store
participant Iaptic
Note over User1,Iaptic: FIRST Strategy
User1->>Store: Makes Purchase
User1->>Iaptic: Validates Receipt
Note over Iaptic: Associates purchase with User1
User2->>Iaptic: Validates Same Receipt
Note over Iaptic: Purchase remains with User1
Note over User1,Iaptic: LAST Strategy
User1->>Store: Makes Purchase
User1->>Iaptic: Validates Receipt
Note over Iaptic: Associates purchase with User1
User2->>Iaptic: Validates Same Receipt
Note over Iaptic: Purchase transfers to User2