Entitlements

Entitlements are the access levels your app understands. They let you change products, prices, trials, store offers, and packages without rewriting premium-access logic in every client. Most apps start with one entitlement:

premium

Use more only when the product truly has different access tiers, such as pro, teams, maps_europe, or credits_pack.

Why entitlements matter

Without entitlements, app code tends to become product-ID logic:

if user bought com.example.fitness.pro_monthly or pro_annual or pro_lifetime...

With entitlements, app code stays stable:

if user has premium...

That is the whole point. Your dashboard owns product mapping; your app owns access behavior.

Attach products to entitlements

Every product that should unlock premium must be attached to the entitlement.

Product	Entitlement
`com.example.fitness.pro_monthly`	`premium`
`com.example.fitness.pro_annual`	`premium`
`pro_monthly`	`premium`
`pro_annual`	`premium`

If the product is not attached, purchase can finish while access remains locked.

Dashboard creation checklist

When you create the first entitlement, keep it boring and stable:

Name it for humans, such as Premium.
Set the app-facing key to premium.
Attach every monthly, annual, lifetime, or winback product that should unlock that access.
Do not encode store IDs, prices, or platform names into the entitlement key.
Document what screens/features the entitlement unlocks so support and engineering use the same language.

The key is what appears in CustomerInfo and what your app checks with hasActiveEntitlement("premium").

Check the entitlement

let info = try await AppActor.shared.getCustomerInfo()
if info.hasActiveEntitlement("premium") {
    showPremiumHome()
}

val info = AppActor.shared.getCustomerInfo()
if (info.hasActiveEntitlement("premium")) {
    showPremiumHome()
}

final info = await AppActor.instance.getCustomerInfo();
if (info.hasActiveEntitlement('premium')) {
  showPremiumHome();
}

const info = await AppActor.instance.getCustomerInfo();
if (info.hasActiveEntitlement('premium')) {
  showPremiumHome();
}

Status and access

Status	Access?
`active`	Yes
`grace`	Yes, while grace is valid
`billing_retry`	No
`expired`	No
`revoked`	No

The SDK helper hasActiveEntitlement(...) is the normal path. Use raw status only when you are building support tooling or backend-specific policy.

Product-to-entitlement failure mode

The most common issue is this:

Offering loads.
Package renders.
Purchase succeeds.
premium does not unlock.

When that happens, check whether the purchased product is attached to premium. AppActor cannot unlock an entitlement that the catalog never mapped.

After defining entitlements, continue with Products and Packages and Offerings.

Overview

Configure Products

Notifications & Webhooks

Why entitlements matter

Attach products to entitlements

Dashboard creation checklist

Check the entitlement

Status and access

Product-to-entitlement failure mode

​Why entitlements matter

​Attach products to entitlements

​Dashboard creation checklist

​Check the entitlement

​Status and access

​Product-to-entitlement failure mode

Why entitlements matter

Attach products to entitlements

Dashboard creation checklist

Check the entitlement

Status and access

Product-to-entitlement failure mode