Skip to main content
Before you handle purchases with the Qonversion SDK, configure Products and Entitlements in the Qonversion dashboard. product in every example below is a Qonversion Product you created in the dashboard; see Displaying Products to fetch and display them.

Make a purchase

Start a purchase with the purchase() method (Swift), purchaseWithResult: (Objective-C), or purchase() on Android and the cross-platform SDKs. The method returns a purchase result object; when the purchase succeeds, look up the granted entitlement on result.entitlements.

Handle a purchase result

The purchase method returns a single result object on every platform — it does not throw for a user cancellation or a pending purchase. Inspect the status flags and branch on all four cases:
  • SuccessisSuccess (isSuccessful on iOS/Android; IsSuccess on Unity). Grant access; read the granted entitlement from result.entitlements.
  • Canceled by the userisCanceled (isCanceledByUser on iOS/Android; IsCanceled on Unity). Do not grant access.
  • PendingisPending (IsPending on Unity). The transaction is queued and awaiting an external action (for example, Ask to Buy or a deferred payment); do not grant access yet.
  • Error — none of the above. Handle the error (see Purchase errors).
Entitlement IDs are the keys to the entitlements map. The values are Qonversion.Entitlement objects.

Purchase errors

When a purchase fails, the SDK returns an error rather than an entitlement. The full list of purchase error codes, their iOS QONErrorCode names, and Android names is on the Handling Errors page. The most common purchase errors and where to fix them:

Restore purchases

When a user switches to a new device, call restore() so they keep access to premium features. Restoring returns the user’s current entitlements; it does not create a new purchase or charge the user.

Check user entitlements

To check a user’s entitlements separately from a purchase — for example, on app launch — use the checkEntitlements() method. See Check user entitlements for details.

Consumable in-app purchases

Consumable in-app purchases are not tied to an entitlement, so when you make a consumable purchase you only look at the outcome (success or error), not at entitlements. On success, grant the bonus; on error, do not. The flow is:
  1. The customer initiates the consumable in-app purchase.
  2. You call the Qonversion purchase method.
  3. You receive the purchase response:
    1. Successful response — grant the user the bonus.
    2. Error — do not grant any bonus.
On iOS and Android you can also read the completed store transaction from the result (result.transaction on iOS, result.purchase on Android, result.storeTransaction on the cross-platform SDKs):

Android: choose a specific offer

Android only. The Google Play Billing Library lets you sell a subscription with different offers. Read the available offers from QProduct.storeDetails, then pass the chosen offer through QPurchaseOptions. This is not available on iOS — App Store offers are selected by StoreKit, not by the SDK.
If you provide an offer ID, the SDK tries to find and purchase the offer with that ID for the requested Qonversion product; if no offer with that ID exists, an error is returned. If you do not provide an offer ID for a subscription purchase of a Qonversion product with a specified base plan ID, the SDK chooses the most profitable offer for the client from all available offers — it compares all trial or intro phases and the base plan and picks the cheapest price. For old Qonversion products (no base plan ID specified) and for in-app products, the offer ID is ignored. You can also remove any intro/trial offer from the purchase to keep only the base plan by calling removeOffer on the purchase options builder:

Android: update a subscription

Android only. Upgrading, downgrading, or changing a subscription on the Google Play Store requires setting the old product and, optionally, a replacement mode through the QPurchaseOptions builder. See the Google Play upgrade/downgrade documentation for details. Subscription updates through this API are not supported on iOS.
Qonversion supports any replacement mode for the old purchase. Provide the update policy while building the purchase options:
The update policy can be one of the following values. The default is WithTimeProration.

iOS: multi-quantity purchases

iOS only. For in-app products you can choose how many items to buy. On Android the quantity is adjusted directly in the purchase pop-up, so no SDK option is needed; on iOS you must set the quantity beforehand while building the purchase options: