iOS SDK 5.0 and StoreKit 2: Setup, Observer Mode, and Data Changes
iOS SDK 5.0 makes StoreKit 2 the default on both the client SDK and the backend for users running iOS 16 and later. For most teams the switch is transparent. The remaining work is narrow but specific: upload an in-app purchase key configuration, and adjust any app that completes purchases itself. This guide walks through what StoreKit 2 is, what changed in this release, and the exact configuration and API differences you need to check.
What is StoreKit 2?
StoreKit 2, also called the Swift-based In-App Purchase API, is a Swift-only reimplementation of the original StoreKit framework. It supports modern Swift concurrency through async/await, exposes the underlying JSON backing values so newer features can be backported to older iOS versions, and includes built-in local transaction verification.
Apple has announced the deprecation of the original StoreKit 1 APIs, so migrating to StoreKit 2 is the path to continuing to receive bug fixes and updates from Apple.
On the backend, StoreKit 2 introduced the App Store Server API for accessing transaction data. Instead of a single Receipt entity, StoreKit 2 splits data into Transaction and AppTransaction, both signed in JSON Web Signature (JWS) format. Rather than one verifyReceipt call, developers can query a Transaction, Transaction History, Subscription Statuses, Refund History, and Notification History. StoreKit 2 also includes pricing information in the Transaction entity, which was not previously available in a Receipt.
What changed in this release
Most SDK features were reimplemented on top of StoreKit 2: listing and purchasing products, checking free trial, introductory price and promo offer eligibility, and testing purchases with StoreKit Config files in Xcode. Observer Mode was updated to work with StoreKit 2. Receipt files were replaced with JWS tokens for purchase validation.
On the backend, StoreKit 2 API performance was compared against StoreKit 1, bugs and performance issues were reported to Apple, and customers were then migrated to the StoreKit 2 APIs behind the scenes. The StoreKit 2 entities were mapped to the Receipt entity to keep the transition seamless and to allow fallback to StoreKit 1 when needed, which was used during a StoreKit 2 incident with missing information. StoreKit 2 config file support was also added so developers can test without connecting to the App Store.
Fewer unexpected errors than StoreKit 1
The deprecated StoreKit 1 APIs sometimes threw unexpected errors about missing receipts or products missing from the receipt, usually during sandbox development. Because StoreKit 2 no longer relies on the old receipt object, those inconsistent errors should no longer appear, which should make in-app purchase testing more reliable.
The one required action: upload your in-app purchase key configuration
Most of the migration happens automatically. The one important step is uploading your in-app purchase key configuration file. All iOS apps require it, and the upload should take less than 5 minutes.
If your project does not have this file yet, upload it by:
- Going to the dashboard.
- Opening your project's settings.
- Selecting your iOS app under "Apps". In the "In-app purchase key configuration" section, add your .p8 file from App Store Connect and fill in your Key ID and Issuer ID.
Once that is done, the platform has what it needs to use the StoreKit 2 APIs and retrieve more accurate data from App Store Connect.
Changes to Observer Mode
SDK 5.0 removes the term "Observer Mode" and updates the APIs to more clearly reflect what is happening. If you previously configured the SDK only to observe purchases so your own code could complete them, the old configuration looked like this (Version 4.0 and earlier):
[code0001]
In SDK 5.0, the equivalent configuration is:
[code0002]
This is functionally the same, but more clearly represents that the SDK is configured to let you complete purchases yourself.
On macOS, when purchases are completed by your app using StoreKit 2, the SDK does not detect a customer's purchase until the user foregrounds the app after the purchase. To have the SDK detect the purchase immediately, call Purchases.shared.recordPurchase(purchaseResult) right after completing the purchase:
[code0003]
This ensures the platform always has immediate access to the user's purchase data. It only applies when the SDK is configured with purchasesAreCompletedBy: .myApp.
If purchases are still completed by your app using StoreKit 1, explicitly configure the SDK to use StoreKit 1:
[code0004]
Historical transaction data may change
The backend migration to StoreKit 2 APIs is already done automatically. Nothing is required here as long as your in-app purchase key configuration file is in the dashboard.
You may notice some changes to historical transaction data. Because the platform now has access to more accurate pricing and country information, some historical data has been corrected. More details are available in the historical data announcement.
Why this is a major version, and what's next
Major SDK version changes usually signal breaking changes developers must fix before integrating. This update is different: the large changes happened under the hood to switch customers to StoreKit 2 APIs with little developer work. Because the changes are foundational, the release was marked as a major version so slight changes are expected.
This update covers the native iOS SDK. StoreKit 2 support in cross-platform SDKs such as React Native and Flutter is described as coming soon. The migration guide covers everything that changed in this SDK update.
| Situation | Required action | Source basis |
|---|---|---|
| Any iOS app | Upload the in-app purchase key configuration (.p8 file, Key ID, Issuer ID) in the dashboard | unit00036, unit00042 |
| App completes purchases itself with StoreKit 2 | Configure with purchasesAreCompletedBy: .myApp and storeKitVersion: .storeKit2 | code0002 |
| App completes purchases itself on macOS with StoreKit 2 | Call Purchases.shared.recordPurchase(purchaseResult) after purchase for immediate detection | unit00055 |
| App still completes purchases with StoreKit 1 | Explicitly configure storeKitVersion: .storeKit1 | code0004 |
| Backend / historical data | No action beyond the key upload; some historical pricing and country data may be corrected | unit00063, unit00064 |
Based on the published SDK 5.0 announcement; verify current behavior against the latest SDK documentation.
Frequently asked questions
Do I need to change code to use StoreKit 2 with SDK 5.0?
For most apps, no. StoreKit 2 becomes the default for users on iOS 16 and later. The main required step is uploading your in-app purchase key configuration. Apps that complete purchases themselves need the updated builder configuration, and macOS apps using self-completed StoreKit 2 purchases should call recordPurchase for immediate detection.
What is the difference between the old observerMode flag and the new configuration?
The old .with(observerMode: true) flag is replaced by .with(purchasesAreCompletedBy: .myApp, storeKitVersion: .storeKit2). The behavior is functionally the same; the new API names more clearly state that your app completes purchases.
Why did my historical transaction data change?
The platform now has access to more accurate pricing and country information through StoreKit 2, and has corrected some historical data accordingly. No action is needed beyond having the in-app purchase key configuration uploaded.
Does this update apply to React Native or Flutter?
No. The 5.0 update described here is for the native iOS SDK. StoreKit 2 support in cross-platform SDKs such as React Native and Flutter was described as coming soon at the time of the announcement.