Subscription Status

Check subscription status and manage user access

You can check subscription status and manage user access to the premium content on your app by checking user entitlements with the checkEntitlements() method.

Entitlement is access to the premium features of your application.
β†’ Read more about creating and using entitlements here.

You need to call the checkEntitlements() method at the start of your app to check if a user has the required entitlement. This method will check the user's receipt and return current entitlements.

In addition to it, Qonversion can manage cross-platform entitlements with the User Identity concept (e.g. after your users subscribe using the IOS app, you can use Qonversion to check their entitlements in your Android or Web applications)

πŸ“˜

Qonversion SDK caches all required data on products, offerings, and entitlements. The data is still immediately available when the internet connection is lost, or there are server-side delays.

🚧

Note, please, that the entitlement object is available only in case the user has made a purchase, or you granted the entitlement manually using the Customer tab or Grant Entitlement API. In other cases, you will receive an empty result.

Qonversion.shared().checkEntitlements { (entitlements, error) in
  if let error = error {
    // handle error
    return
  }
  
  if let premium: Qonversion.Entitlement = entitlements["premium"], premium.isActive {
    switch premium.renewState {
      case .willRenew, .nonRenewable:
        // .willRenew is the state of an auto-renewable subscription 
        // .nonRenewable is the state of consumable/non-consumable IAPs that could unlock lifetime access
        break
      case .billingIssue:
        // Grace period: entitlement is active, but there was some billing issue.
        // Prompt the user to update the payment method.
        break
      case .cancelled:
        // The user has turned off auto-renewal for the subscription, but the subscription has not expired yet.
        // Prompt the user to resubscribe with a special offer.
        break
      default: break
    }
  }
}
[[Qonversion sharedInstance] checkEntitlements:^(NSDictionary<NSString *, QONEntitlement *> * _Nonnull entitlements,
                                NSError * _Nullable error) {
    QONEntitlement *premiumEntitlement = entitlements[@"premium"];
    if (premiumEntitlement && premiumEntitlement.isActive) {
      switch (premiumEntitlement.renewState) {
        case QONEntitlementRenewStateWillRenew:
        case QONEntitlementRenewStateNonRenewable:
          // QONEntitlementRenewStateWillRenew is state for auto-renewable purchases
          // QONEntitlementRenewStateNonRenewable is state for in-app purchases that unlock the entitlement lifetime
          break;
        case QONEntitlementRenewStateBillingIssue:
          // Grace period: entitlement is active, but there was some billing issue.
          // Prompt the user to update the payment method.
          break;
        case QONEntitlementRenewStateCancelled:
          // The user canceled the subscription, but the subscription has not expired yet.
          // Prompt the user to resubscribe with some special offer.
          break;
        default:
          break;
      }
    }
}];
Qonversion.getSharedInstance().checkEntitlements(new QonversionEntitlementsCallback() {
    @Override
    public void onSuccess(@NotNull Map<String, QEntitlement> entitlements) {
        final QEntitlement premiumEntitlement = entitlements.get("premium");

        if (premiumEntitlement != null && premiumEntitlement.isActive()) {
            // handle active entitlement here

            // also you can check renew state if needed
            // for example to check if user has canceled subscription and offer him a discount            final QEntitlement.Product.Subscription subscription = premiumEntitlement.getProduct().getSubscription();
            if (subscription != null) {
                switch (subscription.getRenewState()) {
										case.NonRenewable:
		                    // NonRenewable is the state of a consumable or non-consumable in-app purchase
												break;
                    case WillRenew:
                        // WillRenew is the state of an auto-renewable subscription
                        break;
                    case BillingIssue:
                        // Prompt the user to update the payment method.
                        break;
                    case Canceled:
                        // The user has turned off auto-renewal for the subscription, but the subscription has not expired yet.
                        // Prompt the user to resubscribe with a special offer.
                        break;
                    default: break;
                }
            }
        }
    }

    @Override
    public void onError(@NotNull QonversionError error) {
        // handle error here
    }
});
Qonversion.shared.checkEntitlements(object: QonversionEntitlementsCallback {
    override fun onSuccess(entitlements: Map<String, QEntitlement>) {
        val premiumEntitlement = entitlements["premium"]
        if (premiumEntitlement != null && premiumEntitlement.isActive) {
            // handle active entitlement here

            // also you can check renew state if needed
            // for example to check if user has canceled subscription and offer him a discount
            when (premiumEntitlement.product.subscription?.renewState) {
                QEntitlementRenewState.NonRenewable -> {
                    // NonRenewable is the state of a consumable or non-consumable in-app purchase
                }
                QEntitlementRenewState.WillRenew -> {
                    // WillRenew is the state of an auto-renewable subscription
                }
                QEntitlementRenewState.BillingIssue -> {
                    // Prompt the user to update the payment method.
                }
                QEntitlementRenewState.Canceled -> {
                    // The user has turned off auto-renewal for the subscription, but the subscription has not expired yet.
                    // Prompt the user to resubscribe with a special offer.
                }
                else -> {

                }
            }
        }
    }

    override fun onError(error: QonversionError) {
        // handle error here
    }
})
try {
  final Map<String, QEntitlement> entitlements = await Qonversion.getSharedInstance().checkEntitlements();
  final premium = entitlements['premium'];
  if (premium != null && premium.isActive) {
    switch (premium.renewState) {
      case QEntitlementRenewState.willRenew:
      case QEntitlementRenewState.nonRenewable:
      // .willRenew is the state of an auto-renewable subscription
      // .nonRenewable is the state of consumable/non-consumable IAPs that could unlock lifetime access
        break;
      case QEntitlementRenewState.billingIssue:
      // Grace period: entitlement is active, but there was some billing issue.
      // Prompt the user to update the payment method.
        break;
      case QEntitlementRenewState.canceled:
      // The user has turned off auto-renewal for the subscription, but the subscription has not expired yet.
      // Prompt the user to resubscribe with a special offer.
        break;
      default:
        break;
    }
  }
} catch (e) {
  print(e);
}
try {
  const entitlements = await Qonversion.getSharedInstance().checkEntitlements();

  const premiumEntitlement = entitlements.get('premium');
  if (premiumEntitlement != null) {
    switch (premiumEntitlement.renewState) {
      case EntitlementRenewState.NON_RENEWABLE:
        // NON_RENEWABLE is the state of consumable/non-consumable IAPs that could unlock lifetime access
        break;
      case EntitlementRenewState.WILL_RENEW:
        // WILL_RENEW is the state of an auto-renewable subscription
        break;
      case EntitlementRenewState.CANCELED:
        // The user has turned off auto-renewal for the subscription, but the subscription has not expired yet.
        // Prompt the user to resubscribe with a special offer.
        break;
      case EntitlementRenewState.BILLING_ISSUE:
        // Grace period: entitlement is active, but there was some billing issue.
        // Prompt the user to update the payment method.
        break;
      case EntitlementRenewState.UNKNOWN:
        // We were unable to determine subscription renew state
        break;
    }
  }
} catch (e) {
  // handle error here
}
Qonversion.GetSharedInstance().CheckEntitlements((entitlements, error) =>
{
    if (error == null)
    {
        if (entitlements.TryGetValue("premium", out Entitlement premium) && premium.IsActive)
        {
            switch(premium.RenewState)
            {
                case QEntitlementRenewState.WillRenew:
                case QEntitlementRenewState.NonRenewable:
                    // .willRenew is the state of an auto-renewable subscription 
                    // .nonRenewable is the state of consumable/non-consumable IAPs that could unlock lifetime access
                    break;
                case QEntitlementRenewState.BillingIssue:
                    // Grace period: entitlement is active, but there was some billing issue.
                    // Prompt the user to update the payment method.
                    break;
                case QEntitlementRenewState.Canceled:
                    // The user has turned off auto-renewal for the subscription, but the subscription has not expired yet.
                    // Prompt the user to resubscribe with a special offer.
                    break;
                default:
                    break;
            }
        }
    }
    else
    {
        // Handle the error  
        Debug.Log("Error" + error.ToString());
    }
});
try {
    const entitlements = await Qonversion.getSharedInstance().checkEntitlements();

    const premiumEntitlement = entitlements.get('premium');
    if (premiumEntitlement != null) {
        switch (premiumEntitlement.renewState) {
            case Qonversion.EntitlementRenewState.NON_RENEWABLE:
                // NON_RENEWABLE is the state of consumable/non-consumable IAPs that could unlock lifetime access
                break;
            case Qonversion.EntitlementRenewState.WILL_RENEW:
                // WILL_RENEW is the state of an auto-renewable subscription
                break;
            case Qonversion.EntitlementRenewState.CANCELED:
                // The user has turned off auto-renewal for the subscription, but the subscription has not expired yet.
                // Prompt the user to resubscribe with a special offer.
                break;
            case Qonversion.EntitlementRenewState.BILLING_ISSUE:
                // Grace period: entitlement is active, but there was some billing issue.
                // Prompt the user to update the payment method.
                break;
            case Qonversion.EntitlementRenewState.UNKNOWN:
                // We were unable to determine subscription renew state
                break;
        }
    }
} catch (e) {
    // handle error here
}

The Entitlement Object

Var NameDescription
idQonversion entitlements ID. For example, premium
isActiveBoolean. true means a user has active entitlement.
Please note that isActive = true does not mean a subscription will be renewed. A user can have active entitlement while auto-renewal for the subscription is switched off.
sourceSource of the purchase via which the entitlement was activated.
Values:
– appstore: App Store
– playstore: Play Store
– stripe: Stripe
– unknown: unable to detect the source
– manual: the entitlement was activated manually
startedDateInitial transaction date. For a subscription with a trial period, the date will be when the trial starts.
expirationDateThe expiration date for a subscription.
Null for a consumable/non-consumable in-app purchase or a lifetime subscription
productIdIdentifier of the product from the Qonversion Dashboard
renewStateA renewal state of the subscription. It can have the following values:
nonRenewable - consumable or non-consumable in-app purchase,
willRenew – subscription is active, and auto-renew status is on,
billingIssue – there was some billing issue,
canceled – the subscription was cancelled,
unknown - if we don't have information about the renewal state.