PurchaseController
An interface for handling Superwall's subscription-related logic with your own purchase implementation.
This interface is not required. By default, Superwall handles all subscription-related logic automatically using Google Play Billing.
When implementing PurchaseController, you must manually update subscriptionStatus whenever the user's entitlements change.
In 2.10.2+, when Superwall manages purchases without a Purchase Controller, it rechecks Google Play purchases whenever the app returns to the foreground. This updates access for subscriptions that expired, were refunded, or were revoked while the app was in the background.
Purpose
Use this interface only if you want complete control over purchase handling, such as when using RevenueCat or other third-party purchase frameworks.
Signature
interface PurchaseController {
suspend fun purchase(
activity: Activity,
product: StoreProduct,
basePlanId: String?,
offerId: String?
): PurchaseResult
suspend fun purchase(
activity: Activity,
product: StoreProduct,
basePlanId: String?,
offerId: String?,
replacement: ProductReplacement?
): PurchaseResult = purchase(activity, product, basePlanId, offerId)
suspend fun restorePurchases(): RestorationResult
}// Java uses the callback-based PurchaseControllerJava interface.
public interface PurchaseControllerJava {
void purchase(
ProductDetails productDetails,
String basePlanId,
String offerId,
kotlin.jvm.functions.Function1<? super PurchaseResult, kotlin.Unit> completion
);
void restorePurchases(
kotlin.jvm.functions.Function2<? super RestorationResult, ? super Throwable, kotlin.Unit> completion
);
}Starting in 2.8.0, Kotlin's PurchaseController.purchase() receives a StoreProduct (instead of the Billing Library's ProductDetails), which also supports custom store products. For Google Play products, access the underlying ProductDetails through product.rawStoreProduct?.underlyingProductDetails. The default implementation of this method routes Google Play products to the older purchase(activity, productDetails, basePlanId, offerId) overload, so existing implementations of that overload keep working unchanged. That older overload is now deprecated; implement the StoreProduct-based method above going forward, and implement it directly if you need to support custom store products.
PurchaseControllerJava remains a callback-based API that receives ProductDetails. It does not support custom store products.
Parameters
Prop
Type
Selecting the purchase offer
The SDK resolves the paywall product's offer before calling your controller, including sw-auto. Pass the supplied offerId to your billing provider. A null offerId means purchase the base plan without an offer; do not choose a free trial, discount, or your provider's default offer instead. This also applies to the deprecated ProductDetails overload and PurchaseControllerJava.
In 2.10.1, the built-in controller also honors :sw-none for subscriptions and one-time products, purchasing without an offer.
Returns / State
purchase()returns aPurchaseResult(.Purchased(),.Failed(errorMessage: String),.Cancelled(), or.Pending())restorePurchases()returns aRestorationResult(.Restored()or.Failed(Throwable?))
When using a PurchaseController, you must also manage subscriptionStatus yourself.
Custom store products
Products configured on a custom store in the Superwall dashboard (e.g. Stripe or your own payment backend) can be attached to paywalls. Their metadata (price, subscription period, trial) is fetched from the Superwall API instead of Google Play, and purchases for them are routed through your PurchaseController, bypassing Google Play Billing entirely.
Revenue reporting is not currently supported for Custom Store Products. Purchases completed through your own checkout, such as Stripe, are tracked as conversions, but proceeds show as $0 in Superwall. Use your billing provider to track revenue from these purchases.
- Kotlin
PurchaseControllerimplementations can checkproduct.isCustomProductinpurchase()to detect a custom product and fulfill and persist it through their own payment flow.PurchaseControllerJavadoes not support custom store products. - In 2.10.0+, after a successful custom purchase, the SDK refreshes server entitlements in the background without delaying the purchase result or paywall dismissal. Your server must report the purchase; the SDK does not fulfill it. Transaction events for these purchases report
store: "CUSTOM". - After your billing system grants the entitlement, call
Superwall.instance.setSubscriptionStatus(...)to synchronize that entitlement state with Superwall. The SDK does not fulfill or persist custom purchases automatically. StoreProduct.customTransactionIdis an SDK-generated identifier you can use as the original transaction identifier in your own analytics.- Requires configuring the SDK with a
PurchaseController.
Usage
For implementation examples and detailed guidance, see Using RevenueCat.
Subscription replacement (2.9.0+)
Configure a paywall's Purchase action to replace an existing subscription when offering an upgrade, downgrade, or plan switch. Superwall replaces an active subscription that shares an entitlement with the new subscription. If no such subscription exists, it makes a normal purchase. If Google Play cannot return the current subscriptions, the SDK fails the purchase so it cannot accidentally buy a second subscription; the user can retry.
The SDK calls the five-argument purchase(activity, product, basePlanId, offerId, replacement) overload for every purchase. replacement is nullable and is only populated when the paywall requests a replacement and an eligible subscription exists. The default implementation ignores replacement and calls the existing four-argument overload, so existing controllers continue to work. Override the new overload to support subscription replacement in your custom controller.
ProductReplacement is in com.superwall.sdk.store:
import com.superwall.sdk.store.ProductReplacement
data class ProductReplacement(
val mode: Mode,
val oldProductId: String?,
val oldPurchaseToken: String?
) {
enum class Mode { DEFAULT, CHARGE_PRORATED, CHARGE_FULL_PRICE }
}Prop
Type
For Google Play purchases, pass oldPurchaseToken to BillingFlowParams.SubscriptionUpdateParams.Builder.setOldPurchaseToken() and map mode as follows:
| Mode | Google Play behavior |
|---|---|
DEFAULT | Leave the replacement mode unset to use the base plan's Play Console setting. |
CHARGE_PRORATED | Set ReplacementMode.CHARGE_PRORATED_PRICE: replace immediately and charge the prorated difference. Google Play supports this only for upgrades where the price per unit of time increases. |
CHARGE_FULL_PRICE | Set ReplacementMode.CHARGE_FULL_PRICE: replace immediately and charge the new product's full price. |
Superwall's built-in purchase controller handles this mapping automatically. For RevenueCat, use your billing library's oldProductId and googleReplacementMode equivalents. The callback-based PurchaseControllerJava has no replacement overload.
For custom store subscriptions, the SDK uses the active entitlements reported through subscriptionStatus to find a shared entitlement. oldProductId comes from that entitlement's latestProductId when available, and oldPurchaseToken is null. Your controller must perform the replacement with your own billing backend and then update subscription status.
How is this guide?