Overriding Introductory Offer Eligibility

Overview

Starting with iOS SDK 4.11.0, you can override the default introductory offer eligibility logic to control when users see free trials and intro offers on your paywalls. This allows you to show intro offers to returning users (as "promo offers") or to prevent them from appearing entirely.

This feature is configured entirely through the Paywall Editor in the Superwall Dashboard. No code changes are required in your app.

Requirements

• iOS SDK: Version 4.11.0 or later
• Platform: iOS 18.2+ only (App Store products)
• Xcode Version: 16.3+
• You must have set up the App Store Connect API and the In App Purchase Configuration.

If you're using a PurchaseController

PurchaseController support for intro offer eligibility override was added in SDK version 4.12.8. You'll need to add the JWS token that we generate for the product in a PurchaseOption that you pass to StoreKit when you purchase:

func purchase(product: StoreProduct) async -> PurchaseResult {
  guard let sk2Product = product.sk2Product else {
    return .cancelled
  }

  var options: Set<StoreKit.Product.PurchaseOption> = []

  // Grab the introOfferToken
  if let introOfferToken = product.introOfferToken {
    // Add it as a PurchaseOption
    options.insert(.introductoryOfferEligibility(compactJWS: introOfferToken.token))
  }

  // Pass it in to the StoreKit purchase function
  let result = try await sk2Product.purchase(options: options)

  // etc...
}

How It Works

By default, Superwall uses Apple's StoreKit to determine if a user is eligible for an introductory offer. Apple's rules state that users can only claim an introductory offer once per subscription group.

With this feature, you can override this behavior to:

• Show intro offers to returning users who have already used a trial (useful for win-back campaigns)
• Hide intro offers entirely even if users are eligible
• Use the default behavior (let StoreKit decide)

Configuration

1. Open your paywall in the Paywall Editor
2. Go to the Products menu in the left sidebar
3. Select an option from the "Introductory Offer Eligibility" dropdown
4. Publish your paywall

Options

Automatic (Default) Uses Apple's default eligibility rules

Always Eligible Allows users to see and claim intro offers, even if they've used one before

Always Ineligible Prevents users from seeing intro offers