Subscription Status

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, 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();
          	switch (premiumEntitlement.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.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
}

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
}

The Entitlement Object

Var Name	Description
`id`	Qonversion entitlements ID. For example, premium
`isActive`	Boolean. `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.
`source`	Source 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
`startedDate`	Initial transaction date. For a subscription with a trial period, the date will be when the trial starts.
`trialStartDate`	The trial start date for current entitlement. Null for entitlement that was unlocked by consumable/non-consumable/lifetime purchase or subscription without a trial period.
`firstPurchaseDate`	The date of the first purchase.
`lastPurchaseDate`	The date of the last purchase.
`autoRenewDisableDate`	The date when auto-renew for the subscription was disabled.
`expirationDate`	The expiration date for a subscription. Null for a consumable/non-consumable in-app purchase or a lifetime subscription
`productId`	Identifier of the product from the Qonversion Dashboard
`renewState`	A 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.
`renewsCount`	Subscription renews count for the entitlement. Renews count starts from the second paid transaction. For example, we have 20 transactions: The first one is the trial started transaction The second one is the first paid transaction, trial converted. All the other - subscription renew transactions, thus renewsCount is equal to 18.
`grantType`	Grant type of entitlement `purchase`: User bought a subscription -`familySharing`: User got entitlement via family sharing `offerCode`: User got entitlement using offer code `manual`: User got entitlement via Qonversion dashboard feature
`lastActivatedOfferCode`	The last activated offer code that unlocks the current entitlement.
`transactions`	An array of Transaction objects that contains information about transactions that unlocked current entitlement.

The Transaction object

Var Name	Description
`originalTransactionId`	The original transaction identifier.
`transactionId`	The transaction identifier.
`offerCode`	The offer code that was used to get the transactions.
`transactionDate`	The date of the transaction.
`expirationDate`	The expiration date for the transaction. Null for a consumable/non-consumable in-app purchase or a lifetime subscription
`transactionRevocationDate`	The date when the transaction was revoked. This field represents the time and date the App Store refunded a transaction or revoked it from family sharing.
`environment`	The environment of the transaction: `sandbox` `production`
`ownershipType`	Type of the ownership for the transaction: `owner`- User owns the transaction `familySharing`- User got transaction via family sharing
`type`	Type of the transaction: `subscriptionStarted` `subscriptionRenewed` `trialStarted` `introStarted` `introRenewed` `nonConsumablePurchase`