iOS Setup Guide

Setting up in-app purchases for iOS requires configuration in both Xcode and App Store Connect.

Prerequisites#

Before you can successfully implement and test in-app purchases, you must complete these essential steps in App Store Connect:

1. Sign All Agreements#

  • Sign in to App Store Connect
  • Navigate to Business section
  • Sign ALL pending agreements - This is crucial!
  • If agreements are not signed, products won't appear in your app
  • Go to Business → Banking
  • Fill out ALL required banking information
  • Complete ALL legal and tax forms
  • Wait for Apple's approval - This can take several days
  • Products will not be available until Apple approves all information

App Store Connect Configuration#

1. Create Your App Record#

  • Sign in to App Store Connect
  • Navigate to "My Apps"
  • Create a new app or select your existing app
  • Fill in the required app information

2. Create In-App Purchase Products#

  • In your app's page, go to Features → In-App Purchases
  • Click the + button to create a new product
  • Choose your product type:
    • Consumable: Can be purchased multiple times (coins, lives, etc.)
    • Non-Consumable: One-time purchase (premium features)
    • Auto-Renewable Subscription: Recurring subscription
    • Non-Renewable Subscription: Time-limited subscription

3. Configure Product Details#

For each product, provide:

  • Product ID: Unique identifier (e.g., com.yourapp.premium)
  • Reference Name: Internal name for your team
  • Pricing: Select price tier or custom pricing
  • Display Name: Name shown to users
  • Description: Product description for users

4. Submit for Review#

  • Add product screenshot (1024x1024px)
  • Submit for review (first-time products need approval)

Xcode Configuration#

Use Xcode 16.4 or later. Compile with Xcode 27 when you need the StoreKit 27 fields documented by OpenIAP 3, and complete the UIScene migration below before shipping that build.

1. Adopt UIScene when building with Xcode 27#

Apple requires apps linked with the iOS 27 SDK to use the scene-based lifecycle. A build that still creates its window only from UIApplicationDelegate terminates during launch before OpenIAP or StoreKit can run.

  • Add a non-empty UIApplicationSceneManifest with a UIWindowSceneSessionRoleApplication configuration.
  • Implement application(_:configurationForConnecting:options:) and create the app window from a UIWindowSceneDelegate.
  • Keep a launch screen through UILaunchStoryboardName, UILaunchScreen, or another Apple-supported launch-screen key.
  • Re-run a physical-device sandbox purchase after the migration; compiling the native OpenIAP package alone does not migrate the host app lifecycle.

See Apple's scene-lifecycle migration guide and Xcode 27 launch-screen requirement. SwiftUI App hosts already use scenes; UIKit, React Native, Expo prebuild, Flutter, Godot, and MAUI hosts must be checked in the generated native project.

2. Enable In-App Purchase Capability#

  • Open your project in Xcode
  • Select your app target
  • Go to Signing & Capabilities
  • Click + Capability
  • Add In-App Purchase

3. Configure Bundle Identifier#

Ensure your bundle identifier in Xcode matches the one in App Store Connect:

  • Select your target
  • Go to General tab
  • Verify Bundle Identifier matches App Store Connect

4. Code Signing#

Make sure you have proper code signing set up:

  • Go to Signing & Capabilities
  • Select your development team
  • Choose appropriate provisioning profile

Testing Setup#

1. Create Sandbox Test User#

  • In App Store Connect, go to Users and Access
  • Click Sandbox Testers
  • Create a new sandbox test user with a unique email
  • Important: Use a different email than your developer account

2. Configure Test Environment#

On your iOS device:

  • Important: You don't need to sign into the App Store app with your sandbox account
  • Instead, use the dedicated sandbox login:
    • Go to Settings → Developer (Developer mode must be enabled)
    • Tap Sandbox Apple Account
    • Sign in with your sandbox test user credentials
  • Install your app via Xcode or TestFlight
  • When making a purchase, it will automatically use the sandbox account

Integration with OpenIAP Libraries#

To implement in-app purchases on iOS, use one of the OpenIAP specification libraries:

These libraries implement the OpenIAP specification and handle iOS-specific requirements — refer to each library's documentation for implementation details.

iOS-Specific Requirements#

Purchase Verification#

aka. Receipt Validation - the legacy term used by Apple in StoreKit 1

iOS requires purchase verification to validate purchases. StoreKit 2 (iOS 15+) provides JWS (JSON Web Signature) for enhanced security, while older versions use base64-encoded receipts. See the Purchase Verification guide for server-side and IAPKit verification flows.

Transaction Finishing#

All transactions must be explicitly finished using finishTransaction() to remove them from the payment queue. Unfinished transactions will be re-delivered on app launch.

Restore Purchases#

iOS requires apps to provide a "Restore Purchases" button for users to recover their non-consumable purchases and active subscriptions on new devices — wire it to restorePurchases and read results with getAvailablePurchases.

Subscription Management#

iOS subscriptions require special handling including:

  • Introductory offers and promotional offers
  • Grace periods for billing issues
  • Subscription groups for upgrade/downgrade
  • Family Sharing support (iOS 14+)

OpenIAP libraries handle these iOS-specific requirements automatically. Consult the library documentation for your chosen framework to ensure proper implementation.

Common Issues#

Product IDs Not Found#

Problem: Products return empty or undefined

Solutions:

Check Prerequisites (Most common cause):#

  • Verify ALL agreements are signed in App Store Connect → Business
  • Ensure ALL banking, legal, and tax information is completed AND approved by Apple
  • These are the most commonly overlooked requirements

Verify Product Configuration:#

  • Product IDs match exactly between code and App Store Connect
  • Products are in "Ready to Submit" or "Approved" state
  • Bundle identifier matches

Use Proper Sandbox Testing:#

  • Sign in via Settings → Developer → Sandbox Apple Account
  • NOT through the App Store app

Sandbox Testing Issues#

Problem: "Cannot connect to iTunes Store" error

Solution:

  • Use a dedicated sandbox test user
  • Sign out of regular App Store account
  • Verify internet connection
  • Try on a real device (simulator may have issues)

Purchase Verification Failures#

Problem: Purchase verification returns invalid

Solution:

  • Check if app is properly signed
  • Verify receipt data is not corrupted
  • Ensure proper error handling for network issues

Best Practices#

  • Always validate receipts server-side for production apps
  • Handle all error cases gracefully
  • Test thoroughly with sandbox users
  • Cache purchase state to handle app restarts
  • Provide restore functionality for non-consumable products