iOS Submission Guide

If you've ever validated App Store receipts, you probably have code calling Apple's verifyReceipt endpoint. That endpoint is going away. Here's what's happening and exactly how to fix it before your IAP breaks.

Why Apple Made This Change

Let me explain what happened, because the announcement was buried in WWDC sessions and technical notes that most developers missed.

For years, the "correct" way to validate receipts was:

1. App receives receipt from StoreKit
2. App sends receipt to your server
3. Your server sends receipt to Apple's verifyReceipt endpoint
4. Apple returns validation result

This worked, but it had problems. The endpoint was slow (sometimes taking seconds to respond), it was a single point of failure, and it created unnecessary server-to-server traffic for what should be a simple cryptographic verification.

Apple's new approach is more elegant: receipts are signed using Apple's certificate chain. You can validate them locally by checking the signature, without calling any Apple servers. For subscription status and purchase history, there's a separate App Store Server API.

What Breaks If You Don't Migrate

Here's the timeline:

If your app relies on verifyReceipt after January 24, 2025:

• New purchases won't validate correctly
• Subscription renewals might not be recognized
• Users who bought premium features see them locked
• Support tickets will flood in

The Migration Path

Your migration depends on your current setup. Let me break this down by scenario.

Scenario 1: Using StoreKit 2 (iOS 15+)

Good news - you're mostly set. StoreKit 2 uses JWS (JSON Web Signature) transactions that are automatically validated. The receipt file at Bundle.main.appStoreReceiptURL is deprecated in StoreKit 2.

What you should be doing:

// StoreKit 2 - transactions are self-validating
for await result in Transaction.currentEntitlements {
    switch result {
    case .verified(let transaction):
        // Transaction is already verified by StoreKit 2
        // Grant access based on transaction.productID
        await updateEntitlements(for: transaction)
    case .unverified(let transaction, let error):
        // Handle verification failure
        Logger.iap.error("Unverified transaction: \(error)")
    }
}

For server-side validation with StoreKit 2, send the originalTransactionId and signedTransactionInfo to your server, then use the App Store Server API to get full purchase history.

Scenario 2: Still on StoreKit 1 (Original API)

This is where most developers need to make changes. You have two options:

Option A: Migrate to StoreKit 2

This is the recommended long-term solution. StoreKit 2 has better APIs and automatic validation. The catch is it requires iOS 15+, so you might need to drop support for older devices.

Option B: Local Receipt Validation

If you need to support iOS 14 and earlier, implement local receipt validation. This involves:

1. Read the receipt from disk
2. Parse the PKCS#7 container
3. Verify the signature against Apple's root certificate
4. Extract and validate the receipt fields

Here's a simplified overview (the full implementation requires OpenSSL or similar):

import Foundation
import CryptoKit

class LocalReceiptValidator {

    // Apple's root certificate (bundled in your app)
    private let appleRootCertificate: SecCertificate

    func validateReceipt() throws -> Receipt {
        // 1. Get receipt data
        guard let receiptURL = Bundle.main.appStoreReceiptURL,
              let receiptData = try? Data(contentsOf: receiptURL) else {
            throw ReceiptError.notFound
        }

        // 2. Verify PKCS#7 signature
        // This requires OpenSSL or a similar crypto library
        let isSignatureValid = try verifyPKCS7Signature(
            data: receiptData,
            rootCertificate: appleRootCertificate
        )

        guard isSignatureValid else {
            throw ReceiptError.invalidSignature
        }

        // 3. Extract and parse receipt payload
        let receipt = try parseReceiptPayload(receiptData)

        // 4. Verify bundle ID matches your app
        guard receipt.bundleId == Bundle.main.bundleIdentifier else {
            throw ReceiptError.bundleMismatch
        }

        // 5. Verify receipt hash (SHA-256)
        try verifyReceiptHash(receipt: receipt)

        return receipt
    }

    private func verifyReceiptHash(receipt: Receipt) throws {
        // Get device identifier
        let deviceId = getDeviceIdentifier()

        // Compute expected hash
        var dataToHash = Data()
        dataToHash.append(deviceId)
        dataToHash.append(receipt.opaqueValue)
        dataToHash.append(receipt.bundleIdData)

        let computedHash = SHA256.hash(data: dataToHash)

        guard computedHash == receipt.sha256Hash else {
            throw ReceiptError.hashMismatch
        }
    }
}

Scenario 3: Server-Side Subscription Management

For subscriptions, you should use the App Store Server API instead of verifyReceipt:

// Node.js example using App Store Server API
import { AppStoreServerAPIClient, Environment } from '@apple/app-store-server-library';

const client = new AppStoreServerAPIClient(
    signingKey,          // Your private key (.p8 file)
    keyId,               // Key ID from App Store Connect
    issuerId,            // Issuer ID from App Store Connect
    bundleId,
    Environment.PRODUCTION
);

async function getSubscriptionStatus(originalTransactionId: string) {
    try {
        const response = await client.getAllSubscriptionStatuses(originalTransactionId);

        for (const subscription of response.data) {
            const status = subscription.lastTransactions[0]?.status;
            // 1 = Active, 2 = Expired, 3 = Billing Retry, 4 = Grace Period, 5 = Revoked
            console.log(`Subscription status: ${status}`);
        }

        return response;
    } catch (error) {
        console.error('Failed to get subscription status:', error);
        throw error;
    }
}

Step-by-Step Migration Checklist

Libraries That Help

You don't have to implement receipt validation from scratch. Here are battle-tested options:

Common Mistakes to Avoid

Testing Your Migration

Before submitting, verify these scenarios work:

• New purchase: User buys a product for the first time
• Restore purchases: User reinstalls app and restores
• Subscription renewal: Sandbox subscriptions renew every few minutes
• Subscription expiration: Let a sandbox subscription lapse
• Upgrade/downgrade: User changes subscription tier
• Refund: Simulate via App Store Connect sandbox
• Family sharing: If enabled for your products

FAQ