
Photo by Manny Becerra on Unsplash
Introduction
I recently migrated our app from StoreKit v1 to v2, focusing on auto-renewable subscriptions since our app doesn’t support consumable or non-consumable products. In this post, I’ll share pre-migration tips, the challenges I encountered during the process, and how I solved them.
Why Migrate to StoreKit 2?
The original API (StoreKit v1) still works, but most of its APIs are now marked as deprecated. At WWDC 2024, Apple recommended switching to StoreKit v2 for a more modern approach. Around the same time, our backend team migated from App Store Server Notifications V1 to V2, so we saw it as the perfect opportunity to update StoreKit to v2 as well.
Interestingly, these two systems — App Store Server Notifications and StoreKit — are independent; you can use V2 on the backend while sticking with StoreKit v1 on the client side. Still, we chose to upgrade both together for consistency (see: Is App Store Server Notifications v2 compatible with StoreKit v1?).
Pre-Migration Prep
1. Understanding the Differences Between v1 and v2
Minimum supported version: Most StoreKit v2 APIs require iOS 15 or later, so you might need to raise your app’s minimum supported version.
Upgrading to Xcode 16.2: I ran into a bug where purchases failed on iOS 18.2, and it turns out many developers faced the same issue. Based on a solution from Apple Developer Forums. I used this code to fix it, which requires upgrading Xcode 16.2.
if #available(iOS 18.2, *) { result = try await product.purchase(confirmIn: viewController)} else { result = try await product.purchase()}Using Swift Concurrency: StoreKit v2 APIs are built with the latest Swift advancements, including Swift concurrency. Unlike StoreKit v1’s delegate pattern — relying on clunky callbacks like SKPaymentTransactionObserver— StoreKit v2 embraces async/await for cleaner, more readable code.
Subscription-Specific API Shift: In StoreKit v1, tracking subscription transactions was a chore — we couldn’t access transaction objects directly and had to rely on purchase results or observe SKPaymentQueue changes with SKPaymentTransactionObserver. StoreKit v2 changes the game, offering multiple ways to fetch transactions, including all, unfinished, currentEntitlements, and updates. Here’s how they look:
for await result in Transaction.all { /* transaction history */ }for await result in Transaction.unfinished { /* unfinished transactions */ }for await result in Transaction.currentEntitlements { /* user own subscriptions */ }for await result in Transaction.updates { /* listen transaction update or change */ }Documentation Review: I skimmed WWDC sessions and StoreKit v2 documentation, and here are the references I found helpful:
- StoreKit 2 — official documentation
- Auto-renewable subscriptions
- Testing an auto-renewable subscription
- StoreKit — API documentation
- Meet StoreKit 2 — WWDC21
- What’s new in StoreKit and In-App Purchase — WWDC24
2. Building a POC in StoreKit v2 Using StoreKit Configuration
Building a POC for StoreKit v2 helps because it lets you test and understand the new subscription APIs — like Transaction.currentEntitlements and async/await — in a safe, isolated environment before touching your live app. For auto-renewable subscriptions, it’s especially valuable: you can simulate renewals, cancellations, and purchases using tools like StoreKit Configuration, catching issues (e.g., renewal timing) early. This saves time, reduces risks, and boosts confidence during the actual migration.
Official documentation on StoreKit Configuration and Debugging is available — see Setting Up StoreKit Testing in Xcode for details.
The Migration Process
Loading Products
In StoreKit v1, we had to implement a delegate, start listening for events, and receive product results through delegate methods:
class StoreManager: NSObject, SKProductsRequestDelegate { var productRequest: SKProductsRequest? var products: [SKProduct] = []
func fetchProducts() { let productIDs: Set<String> = ["com.example.subscription.monthly"] productRequest = SKProductsRequest(productIdentifiers: productIDs) productRequest?.delegate = self productRequest?.start() }
func productsRequest(_ request: SKProductsRequest, didReceive response: SKProductsResponse) { self.products = response.products for product in products { print("Product found: \(product.localizedTitle), price: \(product.price)") } }
func request(_ request: SKRequest, didFailWithError error: Error) { print("Error fetching products: \(error.localizedDescription)") }}StoreKit v2 simplifies this with Swift concurrency. Instead of delegates, I used an async call to load our subscription product directly — no callbacks, no fuss:
class StoreManager { func fetchProducts() async throws -> [Product] { let productIDs: Set<String> = ["com.example.subscription.monthly"] let products = try await Product.products(for: productIDs) return products }}Purchaing
In StoreKit v1, buying a subscription meant managing transaction states through SKPaymentTransactionObserver. I set up this code to manage purchases for our monthly auto-renewable subscription, and prevent duplicate payments:
class StoreManager: NSObject, SKPaymentTransactionObserver {
override init() { super.init() SKPaymentQueue.default().add(self) }
func purchase(_ product: SKProduct) { guard SKPaymentQueue.canMakePayments() else { return }
if SKPaymentQueue.default().transactions.contains(where: { $0.payment.productIdentifier == product.productIdentifier && $0.transactionState == .purchasing }) { return }
let payment = SKPayment(product: product) SKPaymentQueue.default().add(payment) }
func paymentQueue(_ queue: SKPaymentQueue, updatedTransactions transactions: [SKPaymentTransaction]) { for transaction in transactions { switch transaction.transactionState { case .purchased: // Purchase successful, finish the transaction SKPaymentQueue.default().finishTransaction(transaction) case .failed: // Purchase failed, handle the error if let error = transaction.error { print("Purchase failed: \(error.localizedDescription)") } SKPaymentQueue.default().finishTransaction(transaction) case .restored: SKPaymentQueue.default().finishTransaction(transaction) case .deferred: break default: break } } }}StoreKit v2 simplifies purchasing into one clean async call, eliminating the queue chaos of v1 — though you still need to call finish() to complete the process. Here’s how I handled our subscription purchase in v2:
class StoreManager { func purchase(_ product: Product) async throws -> Transaction? { guard let subscription = product.subscription, let status = try await subscription.status.first, status.state != .subscribed else { return nil }
let result = try await product.purchase() switch result { case let .success(verification): switch verification { case let .verified(transaction): // Purchase successful, finish the transaction await transaction.finish() case let .unverified(transaction, error): // Purchase failed, handle the error await transaction.finish() } case .userCancelled: return nil case .pending: return nil default: return nil } return nil }}Renewing Subscription (Resuming)
In StoreKit v1, we can call the purchase function again to resume a subscription.
In StoreKit v2, we can do the same, but sometimes it may show a duplicate purchasing prompt (I assume this is related to the OS).
According to the official documentation, I modified the behavior to navigate the user to the Manage Subscriptions page instead.
func showManageSubscriptions() async throws { // Get the active window scene (assuming you have a valid scene) guard let windowScene = await UIApplication.shared.connectedScenes.first as? UIWindowScene else { return }
try await AppStore.showManageSubscriptions(in: windowScene)}Restoring
In StoreKit v1, we call restoreCompletedTransactions and wait for the delegate function to respond.
class StoreManager: NSObject, SKPaymentTransactionObserver {
// Restore purchases func restorePurchases() { SKPaymentQueue.default().restoreCompletedTransactions() }
// Handle updated transactions (restored purchases) func paymentQueue(_ queue: SKPaymentQueue, updatedTransactions transactions: [SKPaymentTransaction]) { for transaction in transactions { switch transaction.transactionState { case .restored: // Handle restored product SKPaymentQueue.default().finishTransaction(transaction) default: break } } }
// Handle restore failure func paymentQueue(_ queue: SKPaymentQueue, restoreCompletedTransactionsFailedWithError error: Error) { // Restore failed print("Restore failed: \(error.localizedDescription)") }}In StoreKit v2, manual restoration is generally unnecessary. We can access transactions via Transaction.all or Transaction.unfinished.
However, in rare cases, we can sync transactions manually with the App Store.
func restorePurchases() async throws { try await AppStore.sync()}In-App Purhcase Promotion
In-App Purchases is a feature that allows users to start a purchase even if they haven’t installed the app. This feature increases the discoverability of our app and is supported on iOS 11 and later. See Promoting In-App Purchases for more information. Here’s how we implemented it in StoreKit v1:
class StoreManager: NSObject, SKPaymentTransactionObserver { override init() { super.init() SKPaymentQueue.default().add(self) }
deinit { SKPaymentQueue.default().remove(self) }
// Handle app store-initiated IAP promotion func paymentQueue(_ queue: SKPaymentQueue, shouldAddStorePayment payment: SKPayment, for product: SKProduct) -> Bool { // Handle purchase flow here return true }}In StoreKit v2, Apple initially did not provide a new version of this API.
However, starting from iOS 16.4, we can use PurchaseIntent.intents instead:
class StoreManager {
// Monitor incoming promotions from the App Store func observeIAPPromotion() async { for await product in PurchaseIntent.intents { print("Received promoted product: \(product.id)") // Handle purchase flow here } }}See Supporting promoted In-App Purchases in your app for more information.
Receipt’s Format Changes
In StoreKit v1, we retrieved receipts from Bundle.main.appStoreReceiptURL, uploaded them to our backend, and had the backend verify them with Apple’s servers—a costly and time-consuming process.
StoreKit v2 simplifies this. We can fetch transactions via Transaction.currentEntitlements or from the purchase result, then convert them to JWS format using the jwsRepresentation property for backend upload. The backend verifies these directly, skipping Apple’s servers.
For subscription details like willAutoRenew, I used Product.SubscriptionInfo.RenewalInfo.jsonRepresentation to extract more information.
func retrieveTransactions() async throws { for await result in Transaction.currentEntitlements { let jws = result.jwsRepresentation
switch result { case let .verified(transaction): print(transaction, jws) case let .unverified(transaction, error): throw error } }}
func retrieveSubsriptionInfo(for product: Product) async throws -> Data? { guard let subscription = product.subscription, let status = try await subscription.status.first else { return nil }
switch status.renewalInfo { case let .verified(renewalInfo): return renewalInfo.jsonRepresentation case let .unverified(renewalInfo, error): throw error }}Testing in the Sandbox
Even though testing with StoreKit Configuration is convenient, testing in the Sandbox is essential. In my experience, the Sandbox behaves differently from StoreKit Configuration and is more similar to production.
For example, after making a purchase in StoreKit Configuration, I didn’t receive the transaction in Transaction.all. However, when testing in the Sandbox, I did receive transaction updates.
Therefore, I believe fully testing in the Sandbox is necessary. See Testing In-App Purchases with Sandbox to learn how to set up a sandbox environment.
Okay, that’s it. I met some troubles when migrating and do some researching in the process. I hope this post can help you if you’re migrating your code to StoreKit v2 as well as. Thank you! 🎉🎉🎉