Storekit

StoreKit 2 In-App Purchases and Subscriptions

Implement in-app purchases, subscriptions, paywalls, and StoreKit testing using StoreKit 2 on iOS 26+. Use the modern Swift-based Product, Transaction, PurchaseAction, StoreView, and SubscriptionStoreView APIs. Avoid original In-App Purchase APIs (SKProduct, SKPaymentQueue) unless legacy OS support requires them.

When reviewing StoreKit code, explicitly separate "preferred SwiftUI path" from "invalid API": PurchaseAction is the preferred custom SwiftUI button path, but direct product.purchase(options:) is still valid for lower-level custom StoreKit flows.

Contents

• Implementation Review Minimums
• Product Types
• Loading Products
• Purchase Flow
• Transaction.updates Listener
• Entitlement Checking
• SubscriptionStoreView (iOS 17+)
• StoreView (iOS 17+)
• Subscription Status Checking
• Restore Purchases
• App Transaction (App Purchase Verification)
• Purchase Options
• SwiftUI Purchase Callbacks
• Common Mistakes
• Review Checklist
• References

Implementation Review Minimums

When reviewing a paywall, purchase manager, or entitlement gate, include these points explicitly:

• Standard SwiftUI paywalls should prefer StoreView, ProductView, or

SubscriptionStoreView; custom SwiftUI buy buttons should prefer PurchaseAction; direct product.purchase(options:) is valid for lower-level custom StoreKit flows.

• Transaction.updates must start at app launch because it catches purchases

from other devices, Family Sharing changes, renewals, Ask to Buy approvals, refunds, revocations, and unfinished transactions.

• Include this entitlement-scope sentence verbatim when reviewing

Transaction.currentEntitlements: "It covers non-consumables, active or grace-period auto-renewable subscriptions, and non-renewing subscriptions; it does not include consumable purchase or delivery history."

• Verify every VerificationResult before granting access. Deliver or persist

the entitlement first, then call transaction.finish().

• Pending purchases and user cancellations never unlock content; pending Ask to

Buy approvals unlock only after a verified transaction arrives through the launch-time listener.

• Exclude refunded or revoked transactions from active entitlement state and

re-check entitlements when refunds or revocations arrive through Transaction.updates.

• Provide a visible restore purchases path and Terms of Service / Privacy

Policy links on subscription paywalls.

Product Types

Loading Products

Define product IDs as constants. Fetch products with Product.products(for:).

import StoreKit

enum ProductID {
    static let premium = "com.myapp.premium"
    static let gems100 = "com.myapp.gems100"
    static let monthlyPlan = "com.myapp.monthly"
    static let yearlyPlan = "com.myapp.yearly"
    static let all: [String] = [premium, gems100, monthlyPlan, yearlyPlan]
}

let products = try await Product.products(for: ProductID.all)
for product in products {
    print("\(product.displayName): \(product.displayPrice)")
}

Purchase Flow

Prefer StoreKit views for standard paywalls because they initiate purchases, restore purchases, and display policy controls. For custom SwiftUI purchase buttons, prefer PurchaseAction from the environment. Use direct product.purchase(options:) only for lower-level custom flows, and use purchase(confirmIn:options:) for UIKit or AppKit confirmation. Always handle every PurchaseResult, verify before access, deliver durably, then finish.

Review wording: do not call product.purchase(options:) inherently wrong. Say "prefer PurchaseAction for SwiftUI buttons; keep product.purchase(options:) for lower-level custom flows that need direct StoreKit control."

@Environment(\.purchase) private var purchase

func purchaseProduct(_ product: Product) async throws {
    let result = try await purchase(product, options: [
        .appAccountToken(userAccountToken)
    ])
    switch result {
    case .success(let verification):
        let transaction = try checkVerified(verification)
        await deliverContent(for: transaction)
        await transaction.finish()
    case .userCancelled:
        break
    case .pending:
        // Ask to Buy or deferred approval: show pending UI, no unlock yet.
        showPendingApprovalMessage()
    @unknown default:
        break
    }
}

func checkVerified<T>(_ result: VerificationResult<T>) throws -> T {
    switch result {
    case .verified(let value): return value
    case .unverified(_, let error): throw error
    }
}

Transaction.updates Listener

Start at app launch, not when a paywall appears. Catches purchases from other devices, Family Sharing changes, renewals, Ask to Buy approvals, refunds, revocations, and unfinished transactions Apple emits once immediately after launch. Keep the task retained for the app lifetime.

In implementation reviews, name the launch-time coverage explicitly: purchases made on other devices, Family Sharing changes, subscription renewals, Ask to Buy approvals, refunds, revocations, and unfinished transactions.

@main
struct MyApp: App {
    private let transactionListener: Task<Void, Never>

    init() {
        transactionListener = Self.listenForTransactions()
    }

    var body: some Scene {
        WindowGroup { ContentView() }
    }

    static func listenForTransactions() -> Task<Void, Never> {
        Task(priority: .background) {
            for await result in Transaction.updates {
                guard case .verified(let transaction) = result else { continue }
                await StoreManager.shared.updateEntitlements()
                await transaction.finish()
            }
        }
    }
}

Entitlement Checking

Use Transaction.currentEntitlements for non-consumables, active or grace period auto-renewable subscriptions, and non-renewing subscriptions. It excludes consumables and consumable delivery history; track consumable fulfillment in your own app or server ledger. It also excludes refunded or revoked transactions. Use Transaction.unfinished for unfinished consumables and recovery sweeps. Always check revocationDate when processing transactions.

In reviews, include this sentence verbatim: "Transaction.currentEntitlements covers non-consumables, active or grace-period auto-renewable subscriptions, and non-renewing subscriptions; it does not include consumable purchase or delivery history." Do not replace this with only a code sample or a revocation check.

@Observable
@MainActor
class StoreManager {
    static let shared = StoreManager()
    var purchasedProductIDs: Set<String> = []
    var isPremium: Bool { purchasedProductIDs.contains(ProductID.premium) }

    func updateEntitlements() async {
        var purchased = Set<String>()
        for await result in Transaction.currentEntitlements {
            if case .verified(let transaction) = result,
               transaction.revocationDate == nil {
                purchased.insert(transaction.productID)
            }
        }
        purchasedProductIDs = purchased
    }
}

SwiftUI .currentEntitlementTask Modifier

struct PremiumGatedView: View {
    @State private var state: EntitlementTaskState<VerificationResult<Transaction>?> = .loading

    var body: some View {
        Group {
            switch state {
            case .loading: ProgressView()
            case .failure: PaywallView()
            case .success(.some(.verified(let transaction))) where transaction.revocationDate == nil:
                PremiumContentView()
            case .success:
                PaywallView()
            }
        }
        .currentEntitlementTask(for: ProductID.premium) { state in
            self.state = state
        }
    }
}

SubscriptionStoreView (iOS 17+)

Built-in SwiftUI view for subscription paywalls. Handles product loading, purchase UI, and restore purchases automatically.

SubscriptionStoreView(groupID: "YOUR_GROUP_ID")
    .subscriptionStoreControlStyle(.prominentPicker)
    .subscriptionStoreButtonLabel(.multiline)
    .storeButton(.visible, for: .restorePurchases)
    .storeButton(.visible, for: .redeemCode)
    .subscriptionStorePolicyDestination(url: termsURL, for: .termsOfService)
    .subscriptionStorePolicyDestination(url: privacyURL, for: .privacyPolicy)
    .onInAppPurchaseCompletion { product, result in
        if case .success(.success(.verified(let transaction))) = result {
            await deliverContent(for: transaction)
            await transaction.finish()
        }
    }

Custom Marketing Content

SubscriptionStoreView(groupID: "YOUR_GROUP_ID") {
    VStack {
        Image(systemName: "crown.fill").font(.system(size: 60)).foregroundStyle(.yellow)
        Text("Unlock Premium").font(.largeTitle.bold())
        Text("Access all features").foregroundStyle(.secondary)
    }
}
.containerBackground(.blue.gradient, for: .subscriptionStore)

Hierarchical Layout

SubscriptionOptionGroup, SubscriptionOptionSection, and SubscriptionPeriodGroupSet are iOS 18+ helper views for organizing options inside SubscriptionStoreView.

SubscriptionStoreView(groupID: "YOUR_GROUP_ID") {
    SubscriptionPeriodGroupSet()
}
.subscriptionStoreControlStyle(.picker)

StoreView (iOS 17+)

Merchandises multiple products with localized names, prices, and purchase buttons.

StoreView(ids: [ProductID.gems100, ProductID.premium], prefersPromotionalIcon: true)
    .productViewStyle(.large)
    .storeButton(.visible, for: .restorePurchases)
    .onInAppPurchaseCompletion { product, result in
        if case .success(.success(.verified(let transaction))) = result {
            await deliverContent(for: transaction)
            await transaction.finish()
        }
    }

ProductView for Individual Products

ProductView(id: ProductID.premium) { iconPhase in
    switch iconPhase {
    case .success(let image): image.resizable().scaledToFit()
    case .loading: ProgressView()
    default: Image(systemName: "star.fill")
    }
}
.productViewStyle(.large)

Subscription Status Checking

func checkSubscriptionActive(groupID: String) async throws -> Bool {
    let statuses = try await Product.SubscriptionInfo.status(for: groupID)
    for status in statuses {
        guard case .verified = status.renewalInfo,
              case .verified = status.transaction else { continue }
        if status.state == .subscribed || status.state == .inGracePeriod {
            return true
        }
    }
    return false
}

Renewal States

Restore Purchases

StoreKit 2 handles restoration via Transaction.currentEntitlements. Add a restore button or call AppStore.sync() explicitly.

func restorePurchases() async throws {
    try await AppStore.sync()
    await StoreManager.shared.updateEntitlements()
}

On store views: .storeButton(.visible, for: .restorePurchases)

App Transaction (App Purchase Verification)

Verify the legitimacy of the app installation. Use for business model changes or detecting tampered installations (iOS 16+).

func verifyAppPurchase() async {
    do {
        let result = try await AppTransaction.shared
        switch result {
        case .verified(let appTransaction):
            let originalVersion = appTransaction.originalAppVersion
            let purchaseDate = appTransaction.originalPurchaseDate
            // Migration logic for users who paid before subscription model
        case .unverified:
            // Potentially tampered -- restrict features as appropriate
            break
        }
    } catch { /* Could not retrieve app transaction */ }
}

Purchase Options

// App account token for server-side reconciliation
try await product.purchase(options: [.appAccountToken(UUID())])

// Consumable quantity
try await product.purchase(options: [.quantity(5)])

// Simulate Ask to Buy in sandbox
try await product.purchase(options: [.simulatesAskToBuyInSandbox(true)])

SwiftUI Purchase Callbacks

.onInAppPurchaseStart { product in
    await analytics.trackPurchaseStarted(product.id)
}
.onInAppPurchaseCompletion { product, result in
    if case .success(.success(.verified(let transaction))) = result {
        await deliverContent(for: transaction)
        await transaction.finish()
    }
}
.inAppPurchaseOptions { product in
    [.appAccountToken(userAccountToken)]
}

Common Mistakes

1. Not starting Transaction.updates at app launch

// WRONG: No listener -- misses renewals, refunds, Ask to Buy approvals
@main struct MyApp: App {
    var body: some Scene { WindowGroup { ContentView() } }
}
// CORRECT: Start listener in App init (see Transaction.updates section above)

2. Forgetting transaction.finish()

// WRONG: Never finished -- reappears in unfinished queue forever
let transaction = try checkVerified(verification)
unlockFeature(transaction.productID)

// CORRECT: Deliver durably, then finish. If delivery fails, do not finish yet.
let transaction = try checkVerified(verification)
try await recordDelivery(transaction)
await transaction.finish()

3. Ignoring verification result

// WRONG: Using unverified transaction -- security risk
let transaction = verification.unsafePayloadValue

// CORRECT: Verify before using
let transaction = try checkVerified(verification)

4. Using original In-App Purchase APIs in new StoreKit 2 code

// AVOID: Original In-App Purchase APIs
let request = SKProductsRequest(productIdentifiers: ["com.app.premium"])
SKPaymentQueue.default().add(payment)

// PREFERRED: StoreKit 2
let products = try await Product.products(for: ["com.app.premium"])
let result = try await product.purchase()

5. Not checking revocationDate

// WRONG: Grants access to refunded purchases
if case .verified(let transaction) = result {
    purchased.insert(transaction.productID)
}

// CORRECT: Skip revoked transactions
if case .verified(let transaction) = result, transaction.revocationDate == nil {
    purchased.insert(transaction.productID)
}

6. Hardcoding prices

// WRONG: Wrong for other currencies and regions
Text("Buy Premium for $4.99")

// CORRECT: Localized price from Product
Text("Buy \(product.displayName) for \(product.displayPrice)")

7. Not handling .pending purchase result

// WRONG: Silently drops pending Ask to Buy
default: break

// CORRECT: Explain approval is pending; unlock only after Transaction.updates
case .pending:
    showPendingApprovalMessage()

8. Checking entitlements only once at launch

// WRONG: Check once, never update
func appDidFinish() { Task { await updateEntitlements() } }

// CORRECT: Re-check on Transaction.updates AND on foreground return
// Transaction.updates listener handles mid-session changes.
// Also use .task { await storeManager.updateEntitlements() } on content views.

9. Missing restore purchases button

// WRONG: No restore option -- App Store rejection risk
SubscriptionStoreView(groupID: "group_id")

// CORRECT
SubscriptionStoreView(groupID: "group_id")
    .storeButton(.visible, for: .restorePurchases)

10. Subscription views without policy links

// WRONG: No terms or privacy policy
SubscriptionStoreView(groupID: "group_id")

// CORRECT
SubscriptionStoreView(groupID: "group_id")
    .subscriptionStorePolicyDestination(url: termsURL, for: .termsOfService)
    .subscriptionStorePolicyDestination(url: privacyURL, for: .privacyPolicy)

Review Checklist

• [ ] Transaction.updates listener starts at app launch in App init
• [ ] All transactions verified before granting access
• [ ] transaction.finish() called only after durable content delivery
• [ ] Revoked/refunded transactions excluded and entitlement state updated
• [ ] .pending result shows Ask to Buy/deferred-approval feedback
• [ ] Restore purchases button visible on paywall and store views
• [ ] Terms of Service and Privacy Policy links on subscription views
• [ ] Prices shown using product.displayPrice, never hardcoded
• [ ] Subscription terms (price, duration, renewal) clearly displayed
• [ ] Free trial states post-trial pricing clearly
• [ ] No original In-App Purchase APIs (SKProduct, SKPaymentQueue) unless legacy OS support requires them
• [ ] Product IDs defined as constants, not scattered strings
• [ ] StoreKit tests cover promotional offers, win-back, offer codes, Ask to Buy, renewals, refunds, and revocations
• [ ] Entitlements re-checked on Transaction.updates and app foreground
• [ ] Server-side validation uses jwsRepresentation if applicable
• [ ] Consumables delivered and finished promptly
• [ ] Transaction observer types and product model types are Sendable when shared across concurrency boundaries

References

• See references/app-review-guidelines.md for IAP rules (Guideline 3.1.1), subscription display requirements, and rejection prevention.
• See references/storekit-advanced.md for subscription control styles, offer management, testing patterns, and advanced subscription handling.
• For submission, privacy, metadata, screenshots, and rejection-risk audits use app-store-review.
• For keyword, screenshot-caption, ranking, and conversion strategy use app-store-optimization.
• Official Apple docs: Choosing a StoreKit API, Transaction.updates, Transaction.currentEntitlements,

SubscriptionStoreView, and PurchaseAction.

App Review Guidelines -- In-App Purchases and Subscriptions

Use this as a StoreKit implementation guardrail for App Review payment issues. For full submission, privacy, metadata, entitlement, or rejection-risk audits, use the sibling app-store-review skill and re-check Apple's current App Review Guidelines.

Contents

• Guideline 3.1.1 Baseline
• What Generally Requires IAP
• What Generally Does Not Require IAP
• External Purchase Links and Reader Apps
• Subscription Display Requirements
• StoreKit Implementation Checklist
• Common IAP Rejection Risks
• Pre-Submission Payments Checklist
• References

Guideline 3.1.1 Baseline

Digital content, app features, subscriptions, virtual goods, and services unlocked in the app generally must use Apple's In-App Purchase system unless a specific App Review guideline exception, storefront-specific rule, or approved entitlement applies.

Do not present this as a universal ban on every external purchase link. The rules differ by storefront, entitlement, and app type, and they change over time. For a release audit, quote the current guidelines directly.

What Generally Requires IAP

• Premium features or content unlocks
• Subscriptions to app functionality
• Virtual currency, coins, gems, or other digital goods
• Ad removal
• Digital tips or donations
• Digital gift cards, certificates, vouchers, or coupons for digital goods

What Generally Does Not Require IAP

• Physical products and e-commerce
• Ride-sharing, food delivery, and real-world services
• One-to-one services such as tutoring or consulting booked through the app
• Enterprise or B2B apps distributed through Apple Business Manager

External Purchase Links and Reader Apps

• Remove external purchase links, buttons, calls to action, and purchase paths

for digital goods unless the current storefront rules or an approved entitlement explicitly allow them.

• Reader apps may access content purchased elsewhere. Account-management or

sign-up links depend on current reader-app rules, storefront, and entitlement status.

• U.S. storefront behavior and some regional external-purchase entitlements are

different from the old blanket prohibition. Do not hardcode old guidance into product or review advice.

Subscription Display Requirements

• Clearly display price, duration, billing frequency, renewal behavior, and

cancellation terms before purchase.

• Free trials must clearly state trial duration, post-trial price, billing

frequency, auto-renewal, and cancellation terms.

• Subscriptions should provide ongoing value and be available across a user's

devices where the app supports them.

StoreKit Implementation Checklist

• Categorize consumables, non-consumables, non-renewing subscriptions, and

auto-renewable subscriptions correctly in App Store Connect.

• Provide working restore purchases for restorable products. StoreKit views can

expose this with .storeButton(.visible, for: .restorePurchases).

• Verify transactions with StoreKit 2 VerificationResult, current

entitlements, and server-side JWS validation when the business model requires server authority.

• Handle interrupted purchases, .pending Ask to Buy approvals, refunds,

revocations, Family Sharing changes, grace period, and billing retry.

Common IAP Rejection Risks

1. Unauthorized external purchase path. The app links or directs users to buy digital goods outside IAP without a current rule or entitlement allowing that path. 2. Missing restore path. Restorable products cannot be restored from the paywall or store surface. 3. Unclear subscription terms. Price, duration, renewal behavior, trial conversion price, and cancellation terms are missing or hidden before purchase. 4. Incorrect product categorization. Consumables, non-consumables, and auto-renewable subscriptions do not match the App Store Connect product setup or the app's entitlement logic.

Pre-Submission Payments Checklist

• [ ] Digital goods and app-unlocked features use IAP unless a current exception or approved entitlement applies
• [ ] Subscription terms are visible before purchase
• [ ] Free trial copy states post-trial price and billing frequency
• [ ] External purchase links and CTAs are either removed or justified by a current storefront rule or approved entitlement
• [ ] Restore purchases path is visible and functional for restorable products
• [ ] Product types match App Store Connect configuration
• [ ] Transaction verification uses StoreKit 2 APIs and server validation where needed
• [ ] Ask to Buy, deferred approvals, refunds, and revocations are handled

References

• App Store Review Guidelines -- use the original Apple URL because this guidelines page is not reliably available through Sosumi.
• StoreKit External Purchase Link Entitlement
• StoreKit External Purchase

StoreKit 2 Advanced Reference

Covers subscription control styles, offer management, testing, server-side validation, and advanced subscription handling patterns for StoreKit 2. Use this after the core purchase, transaction listener, and entitlement patterns from the top-level StoreKit skill are in place.

Contents

• SubscriptionStoreView Control Styles
• Subscription Group Management
• Introductory Offers
• Promotional Offers
• Win-Back Offers
• Offer Codes
• Server-Side Validation
• StoreKit Testing in Xcode
• Subscription Renewal States
• Grace Period and Billing Retry
• Refund Handling
• Family Sharing
• Ask to Buy Handling
• .currentEntitlementTask SwiftUI Modifier
• Subscription Status Listener
• Product Promotion Management
• Price Increase Handling
• Unfinished Transactions
• Common Advanced Mistakes

SubscriptionStoreView Control Styles

Apply control styles to change how subscription options render in SubscriptionStoreView.

// Individual buttons for each subscription option
.subscriptionStoreControlStyle(.buttons)

// Inline picker for compact selection
.subscriptionStoreControlStyle(.picker)

// Picker with the selected option visually emphasized
.subscriptionStoreControlStyle(.prominentPicker)

// Full-page swipeable picker (one option per page)
.subscriptionStoreControlStyle(.pagedPicker)

// Paged picker with prominent selected option
.subscriptionStoreControlStyle(.pagedProminentPicker)

// Minimal inline picker for tight layouts
.subscriptionStoreControlStyle(.compactPicker)

// System decides based on context
.subscriptionStoreControlStyle(.automatic)

Control Placement

Specify where controls appear within the view. Not every placement is supported by every control style, so let unsupported combinations fall back to the system default instead of assuming exact placement on every platform.

.subscriptionStoreControlStyle(.picker, placement: .bottom)
// Placement options: .bottom, .leading, .trailing, .scrollView,
// .bottomBar, .buttonsInBottomBar

Button Labels

Control what information subscription buttons display:

.subscriptionStoreButtonLabel(.multiline)   // Full details (name, price, period)
.subscriptionStoreButtonLabel(.price)       // Price only
.subscriptionStoreButtonLabel(.displayName) // Product name only
.subscriptionStoreButtonLabel(.action)      // Action text ("Subscribe")
.subscriptionStoreButtonLabel(.singleLine)  // Condensed single line
.subscriptionStoreButtonLabel(.automatic)   // System default

Container Backgrounds

.containerBackground(.blue.gradient, for: .subscriptionStore)

.containerBackground(for: .subscriptionStoreHeader) {
    Image("premium-header").resizable().scaledToFill()
}

.containerBackground(for: .subscriptionStoreFullHeight) {
    LinearGradient(colors: [.blue, .purple], startPoint: .top, endPoint: .bottom)
}

Subscription Store Buttons

.storeButton(.visible, for: .restorePurchases)
.storeButton(.visible, for: .redeemCode)
.storeButton(.visible, for: .cancellation)
.storeButton(.visible, for: .policies)
.storeButton(.hidden, for: .signIn)

Policy Destinations

// URL-based
.subscriptionStorePolicyDestination(url: termsURL, for: .termsOfService)
.subscriptionStorePolicyDestination(url: privacyURL, for: .privacyPolicy)

// Custom view
.subscriptionStorePolicyDestination(for: .termsOfService) {
    TermsOfServiceView()
}

// Style policy link text
.subscriptionStorePolicyForegroundStyle(.white)

Decorative Icons per Option

.subscriptionStoreControlIcon { product, subscriptionInfo in
    if subscriptionInfo.subscriptionPeriod.unit == .year {
        Image(systemName: "star.fill")
    } else {
        Image(systemName: "star")
    }
}

Sign-In Action

.storeButton(.visible, for: .signIn)
.subscriptionStoreSignInAction {
    showSignInSheet = true
}

Subscription Group Management

The option hierarchy helper views in this section are iOS 18+ APIs for organizing subscription choices inside SubscriptionStoreView.

Hierarchical Layouts with SubscriptionOptionGroup

SubscriptionStoreView(groupID: "premium_group") {
    SubscriptionOptionGroup("Monthly Plans") { product in
        product.subscription?.subscriptionPeriod.unit == .month
    }
    SubscriptionOptionGroup("Annual Plans") { product in
        product.subscription?.subscriptionPeriod.unit == .year
    }
}

Automatic Period Grouping

SubscriptionStoreView(groupID: "premium_group") {
    SubscriptionPeriodGroupSet()
}

Sections with Headers

SubscriptionStoreView(groupID: "premium_group") {
    SubscriptionOptionSection("Standard", isIncluded: { product in
        product.subscription?.groupLevel == 1
    }) {
        Text("Basic features included")
    }
    SubscriptionOptionSection("Pro", isIncluded: { product in
        product.subscription?.groupLevel == 2
    }) {
        Text("All features included")
    }
}

Visible Relationships

Filter which subscription levels are shown relative to the current subscription:

// Show all options
SubscriptionStoreView(groupID: "group_id", visibleRelationships: .all)

// Show only upgrades from current subscription
SubscriptionStoreView(groupID: "group_id", visibleRelationships: .upgrade)

Custom Subscription Store Controls

SubscriptionStoreButton, SubscriptionStorePicker, SubscriptionOptionGroup, and related option controls are supported inside a custom SubscriptionStoreControlStyle.makeBody(configuration:). Do not place them as arbitrary standalone content outside a custom control style.

Introductory Offers

Checking Eligibility

// Per-product eligibility
let isEligible = product.subscription?.isEligibleForIntroOffer ?? false

// Per-group eligibility
let groupEligible = await Product.SubscriptionInfo.isEligibleForIntroOffer(
    for: groupID
)

Accessing Offer Details

if let introOffer = product.subscription?.introductoryOffer {
    let price = introOffer.displayPrice       // Localized price
    let period = introOffer.period            // SubscriptionPeriod
    let count = introOffer.periodCount        // Number of periods
    let mode = introOffer.paymentMode         // .freeTrial, .payAsYouGo, .payUpFront

    switch introOffer.paymentMode {
    case .freeTrial:
        Text("Free for \(count) \(period.unit)")
    case .payAsYouGo:
        Text("\(price)/\(period.unit) for \(count) periods")
    case .payUpFront:
        Text("\(price) for \(count) \(period.unit)")
    default:
        EmptyView()
    }
}

Introductory offers apply automatically when eligible. No special purchase options needed.

Promotional Offers

Promotional offers require server-side signature generation.

Accessing Promotional Offers

let promoOffers = product.subscription?.promotionalOffers ?? []
for offer in promoOffers {
    print("Offer: \(offer.id ?? "nil"), price: \(offer.displayPrice)")
}

Purchasing with a Promotional Offer

// 1. Get signature from your server
let signature = Product.SubscriptionOffer.Signature(
    keyID: serverKeyID,
    nonce: serverNonce,
    timestamp: serverTimestamp,
    signature: serverSignatureData
)

// 2. Purchase with the offer
guard let offerID = offer.id else { throw StoreError.invalidOffer }
let result = try await product.purchase(options: [
    .promotionalOffer(offerID: offerID, signature: signature)
])

SwiftUI Automatic Promotional Offer

For StoreKit SwiftUI views on iOS 26+, provide the offer and the compact JWS signature asynchronously:

.subscriptionPromotionalOffer { product, subscription in
    subscription.promotionalOffers.first
} compactJWS: { product, subscription, offer in
    guard let offerID = offer.id else { throw StoreError.invalidOffer }
    return try await offerSigner.compactJWS(
        productID: product.id,
        offerID: offerID
    )
}

Preferred Offer Selection

Let the system choose the best offer for each user:

.preferredSubscriptionOffer { product, subscription, eligibleOffers in
    // Return the best offer, or nil for no offer
    return eligibleOffers.first
}

Win-Back Offers

Target former subscribers who cancelled. Available since iOS 18.

Accessing Win-Back Offers

let winBackOffers = product.subscription?.winBackOffers ?? []

winBackOffers is the raw offer list for the product. Filter it through renewalInfo.eligibleWinBackOfferIDs before showing or applying offers.

Checking Eligibility via Renewal Info

let statuses = try await Product.SubscriptionInfo.status(for: groupID)
let eligibleOfferIDs = statuses.flatMap { status -> [String] in
    guard case .verified(let renewalInfo) = status.renewalInfo else { return [] }
    return renewalInfo.eligibleWinBackOfferIDs
}

let offersByID = Dictionary(uniqueKeysWithValues: winBackOffers.compactMap { offer in
    offer.id.map { ($0, offer) }
})

let eligibleWinBackOffers = eligibleOfferIDs.compactMap { offersByID[$0] }
for offer in eligibleWinBackOffers {
    // Display or apply only eligible offers.
}

Purchasing with a Win-Back Offer

let result = try await product.purchase(options: [
    .winBackOffer(winBackOffer)
])

Offer Codes

Redemption Sheet

@State private var showRedeemSheet = false

var body: some View {
    Button("Redeem Code") { showRedeemSheet = true }
        .offerCodeRedemption(isPresented: $showRedeemSheet) { result in
            switch result {
            case .success:
                await storeManager.updateEntitlements()
            case .failure(let error):
                print("Redemption failed: \(error)")
            }
        }
}

Show Redeem Button on Subscription Store

.storeButton(.visible, for: .redeemCode)

Testing Offer Codes

Test offer-code redemption in StoreKit configuration files and sandbox. In StoreKit testing, use the configured offer-code reference name:

try await product.purchase(options: [.codeOffer(referenceName: "SUMMER2024")])

Also test the user-facing redemption path with .storeButton(.visible, for: .redeemCode) or .offerCodeRedemption(isPresented:), then verify the resulting transaction uses transaction.offer?.type == .code and the expected transaction.offer?.id.

Verifying Applied Offers in Transactions

if let offer = transaction.offer {
    switch offer.type {
    case .introductory: break  // Introductory offer applied
    case .promotional: break   // Promotional offer applied
    case .code: break          // Offer code redeemed
    case .winBack: break       // Win-back offer applied
    default: break
    }

    let offerID = offer.id
}

Server-Side Validation

Sending JWS to Server

StoreKit 2 transactions are JWS (JSON Web Signature) tokens. Send the raw JWS string to your server for validation.

case .success(let verification):
    let transaction = try checkVerified(verification)

    // Send to server for validation
    let jwsString = verification.jwsRepresentation
    try await sendToServer(jws: jwsString, productID: transaction.productID)

    await transaction.finish()

Server-Side Verification

On your server, use Apple's App Store Server Library:

• verifyAndDecodeTransaction(signedTransaction:) to validate and decode
• verifyAndDecodeRenewalInfo(signedRenewalInfo:) for subscription renewal info
• The JWS format matches JWSTransaction from the App Store Server API and

App Store Server Notifications V2

Device Verification

Bind transactions to specific devices to prevent replay attacks:

let deviceVerification = transaction.deviceVerification
let nonce = transaction.deviceVerificationNonce
// Send both to server for additional validation

StoreKit Testing in Xcode

StoreKit Configuration Files

1. Create a StoreKit Configuration file in Xcode: File > New > File > StoreKit Configuration File 2. Add products matching your App Store Connect configuration 3. Set the configuration in the scheme: Edit Scheme > Run > Options > StoreKit Configuration

Configuration File Contents

Define products with:

• Product ID, reference name, product type
• Price and locale
• Subscription group and level (for subscriptions)
• Introductory and promotional offers
• Family Sharing settings

Testing Features

// Simulate Ask to Buy
try await product.purchase(options: [.simulatesAskToBuyInSandbox(true)])

// Test-only: set purchase date and renewal behavior
try await product.purchase(options: [
    .purchaseDate(Date(), renewalBehavior: .default)
])

// Test-only: apply offer code by reference name
try await product.purchase(options: [.codeOffer(referenceName: "SUMMER2024")])

StoreKit Testing Capabilities

• Simulate failed transactions, interrupted purchases, refunds
• Test Ask to Buy pending approvals for promotional, win-back, and offer-code purchases
• Speed up subscription renewals (renewals happen in minutes, not months)
• Test grace period and billing retry states
• Clear purchase history between test runs
• Test offer redemption flows
• Simulate subscription expiration and cancellation

Transaction Manager in Xcode

Use Debug > StoreKit > Manage Transactions to:

• View all test transactions
• Delete transactions to reset state
• Request refunds
• Expire subscriptions
• Approve or decline Ask to Buy requests

Subscription Renewal States

Active States (grant access)

switch status.state {
case .subscribed:
    // Active, auto-renewing subscription
    grantAccess()

case .inGracePeriod:
    // Payment failed but grace period active -- still grant access
    // Show a gentle prompt to update payment method
    grantAccess()
    showPaymentUpdatePrompt()

Degraded States (consider limited or no access)

case .inBillingRetryPeriod:
    // Payment failed, Apple is retrying -- access decision is yours
    // Apple recommends granting limited access to encourage payment update
    grantLimitedAccess()
    showPaymentFailedBanner()

case .expired:
    // Subscription ended -- check expirationReason
    revokeAccess()
    if let reason = renewalInfo.expirationReason {
        switch reason {
        case .autoRenewDisabled: showResubscribeOffer()
        case .billingError: showUpdatePaymentMethod()
        case .didNotConsentToPriceIncrease: showPriceInfo()
        case .productUnavailable: break
        default: break
        }
    }

case .revoked:
    // Apple refunded -- must revoke access
    revokeAccess()

Expiration Reasons

Grace Period and Billing Retry

Grace Period

When enabled in App Store Connect, subscribers retain access for a short period after a billing failure. Check status.state == .inGracePeriod and the gracePeriodExpirationDate on renewal info.

if status.state == .inGracePeriod,
   case .verified(let renewalInfo) = status.renewalInfo {
    let expirationDate = renewalInfo.gracePeriodExpirationDate
    // Grant access but prompt to update payment method
}

Billing Retry

Apple automatically retries failed payments. During billing retry, the subscription state is .inBillingRetryPeriod. Check renewalInfo.isInBillingRetry.

Refund Handling

Initiating Refund Requests

// From a transaction instance
let refundStatus = try await transaction.beginRefundRequest(in: windowScene)

// From a transaction ID
let refundStatus = try await Transaction.beginRefundRequest(
    for: transactionID, in: windowScene
)

SwiftUI Refund Sheet

@State private var showRefund = false

Button("Request Refund") { showRefund = true }
    .refundRequestSheet(for: transactionID, isPresented: $showRefund) { result in
        // Handle refund request dismissal
    }

Detecting Refunds

Refunds appear via Transaction.updates with a non-nil revocationDate. Always check revocationDate when evaluating entitlements.

if let revocationDate = transaction.revocationDate {
    revokeAccess(for: transaction.productID)
    // revocationPercentage indicates partial vs full refund
    let percentage = transaction.revocationPercentage
}

Family Sharing

Checking Ownership Type

switch transaction.ownershipType {
case .purchased:
    // User purchased directly
    break
case .familyShared:
    // Shared via Family Sharing -- may be revoked if sharer leaves
    break
default:
    break
}

Family Shareable Products

Check product.isFamilyShareable to determine if a product supports Family Sharing. Enable Family Sharing in App Store Connect per product.

Family Sharing changes arrive via Transaction.updates. When a family member stops sharing, the transaction is revoked.

Ask to Buy Handling

Ask to Buy applies to child accounts in Family Sharing. The purchase returns .pending; show a waiting-for-approval state, keep content locked, and unlock only after the approved transaction arrives from Transaction.updates.

case .pending:
    // Show UI indicating purchase needs parental approval
    showPendingApprovalState()
    // When approved, the transaction arrives via Transaction.updates

Testing Ask to Buy

try await product.purchase(options: [.simulatesAskToBuyInSandbox(true)])

Then approve or decline in Xcode's Transaction Manager. Include this path when testing promotional offers, win-back offers, offer codes, and renewal states so deferred approval does not bypass verification or entitlement updates.

.currentEntitlementTask SwiftUI Modifier

Basic Usage

.currentEntitlementTask(for: "com.app.premium") { state in
    self.entitlementState = state
}

EntitlementTaskState Pattern

enum EntitlementTaskState<Value> {
    case loading
    case success(Value)    // Value is VerificationResult<Transaction>?
    case failure(any Error)
}

Pattern-match the verified optional transaction before granting access:

.currentEntitlementTask(for: ProductID.premium) { state in
    if case .success(.some(.verified(let transaction))) = state,
       transaction.revocationDate == nil {
        self.isPremium = true
    } else {
        self.isPremium = false
    }
}

Related Task Modifiers

// Load a single product
.storeProductTask(for: "com.app.premium") { taskState in
    // taskState: Product.TaskState (.loading, .success(Product), .unavailable, .failure)
}

// Load multiple products
.storeProductsTask(for: ["id1", "id2"]) { taskState in
    // taskState: Product.CollectionTaskState (.loading, .success([Product], unavailable:), .failure)
}

// Monitor subscription status
.subscriptionStatusTask(for: "group_id") { taskState in
    // Receive subscription status updates
}

Subscription Status Listener

Listen for real-time subscription status changes:

func listenForStatusChanges() -> Task<Void, Never> {
    Task {
        for await (groupID, statuses) in Product.SubscriptionInfo.Status.all {
            for status in statuses {
                guard case .verified(let renewalInfo) = status.renewalInfo else { continue }
                await handleStatusChange(state: status.state, renewalInfo: renewalInfo)
            }
        }
    }
}

Product Promotion Management

Control the order and visibility of promoted in-app purchases on the App Store product page:

// Product.PromotionInfo provides device-level promotion customization
// Configure in App Store Connect and override per-device as needed

Price Increase Handling

if case .verified(let renewalInfo) = status.renewalInfo {
    switch renewalInfo.priceIncreaseStatus {
    case .noIncreasePending: break
    case .pending:
        // User has not yet consented -- show price increase info
        showPriceIncreaseConsent(newPrice: renewalInfo.renewalPrice,
                                 currency: renewalInfo.currency)
    case .agreed:
        // User accepted the price increase
        break
    }
}

Unfinished Transactions

Transaction.updates emits unfinished transactions once immediately after app launch. Use Transaction.unfinished when you need an explicit recovery sweep, such as after a delivery-server outage or a late listener startup:

func processUnfinishedTransactions() async {
    for await result in Transaction.unfinished {
        guard case .verified(let transaction) = result else { continue }
        await deliverContent(for: transaction)
        await transaction.finish()
    }
}

Keep the Transaction.updates listener as the primary always-on path, and use the sweep as a recovery tool rather than a replacement for the listener.

Common Advanced Mistakes

Missing a recovery path for unfinished transactions

// WRONG: No launch listener and no recovery sweep
init() { }

// CORRECT: Start updates at launch; sweep unfinished transactions when needed
init() {
    transactionListener = listenForTransactions()
    Task { await processUnfinishedTransactions() }
}

Treating billing retry as expired

// WRONG: Revoking access during billing retry
case .inBillingRetryPeriod: revokeAccess()

// CORRECT: Grant limited access and prompt payment update
case .inBillingRetryPeriod:
    grantLimitedAccess()
    showUpdatePaymentPrompt()

Not handling Family Sharing revocation

// WRONG: Assuming family-shared access is permanent
if transaction.ownershipType == .familyShared {
    grantPermanentAccess()
}

// CORRECT: Check revocation status and listen for changes
if transaction.ownershipType == .familyShared,
   transaction.revocationDate == nil {
    grantAccess()  // May be revoked later via Transaction.updates
}