Access to content is the fundamental basis of subscription entitlement. And access may vary depending on the level of service, geography, and other factors. As was shown above, a subscription can have several states. The entitlement process needs to account for all of the potential subscription states. 

To be able to manage user access, power tailored communication with your users, win lapsed users back, and so on, you need to build server-side logic that digests all subscription state data. Apple refers to this as the Entitlement Engine. (Note: Apple provided the sample Entitlement Engine code in node.js.)

The data digested by the Entitlement Engine is used to calculate the user’s entitlement. The Engine needs to calculate the correct entitlement info using the receipt data, app insights, and server-to-server notifications. The output of the Entitlement Engine is a simple JSON payload that you can use to entitle service and update your user database.

Key processes of the Entitlement Engine:

• Prepare data: The app receipt is the source of truth for transactional data. So you need to fetch the most up-to-date info for the receipt from App Store to make sure it’s not outdated. Get server-to-server notifications.

• Synthesize data: Digest transactional data, detect where the user is in the subscriber journey. Add data from the app, for example, hours watched, upcoming events a user is interested in, etc.

• Condense the data into actionable insights, that will be used in the response.

• Build the Response Object

Entitlement Engine Response Object

Distinguish cohorts of subscribers based on the subscription state and sub-state as shown below. 

You can assign positive values for cases where you would unlock access and negative values for cases where access would not be provided. Add substates using the decimal values to enhance the entitlement process. By combining state and substate you can have a value to represent the exact state of the product. You can send this value to the client. It can be used as a simple signal to unlock the service when it’s positive.

Subscription states and sub-states – Entitlement Code Example

For example, entitlement code 4.1 represents a subscriber who is currently in a trial period and has disabled auto-renewal: 

Another example, based on 4.0 code (user with standard subscription turned-off auto-renewal) you can trigger a retention message and link the user to a specific product offer.

Entitlement code example: trigger promotional offer