Implementing iOS Subscriptions: StoreKit 2, Grace Period, and Promotional Offers

Auto-renewable subscriptions are the most complex type of in-app purchase. Not because StoreKit is inherently complicated, but because of the entire ecosystem that surrounds it: grace periods, billing retry, downgrade/upgrade between tiers, promo offers, introductory pricing, and finally — handling churn through expirationIntent. An error at any stage leads to revenue loss. We implement subscriptions turnkey in 3–5 days, ensuring correct logic at every stage of the lifecycle.

The Subscription Lifecycle and Where It Breaks

An iOS subscription isn't just active or not. Apple automatically renews it 24 hours before expiration. If payment fails, a billing retry period begins (up to 60 days). During this time, the subscription status is expired, but Apple continues retrying. Most apps block access right after expirationDate — that's wrong.

The correct logic: check renewalInfo.isInBillingRetryPeriod. If true, grant a grace period (configured in App Store Connect, typically 6 days for annual, 3 days for monthly). A user with a card issue should not lose access immediately.

StoreKit 2 handles grace period transparently, reducing churn by 20–30% compared to manual implementation with StoreKit 1. Here's an example of correct validation:

for await result in Transaction.currentEntitlements { guard case .verified(let transaction) = result else { continue } if transaction.productType == .autoRenewable { let renewalInfo = try? await transaction.subscriptionStatus.first?.renewalInfo let isInGracePeriod = renewalInfo?.gracePeriodExpirationDate != nil let isRetrying = renewalInfo?.isInBillingRetryPeriod == true if transaction.revocationDate == nil && (transaction.expirationDate ?? .distantPast > .now || isInGracePeriod || isRetrying) { unlockPremium() } } } 

Why Grace Period Matters

Without a grace period, users with payment issues lose access instantly. Apple allows up to 16 days of grace — enough time for the customer to update their card and for you to retain them. Our experience shows that 70% of users return to payment within the grace period. If you block access immediately, they leave permanently.

Tiers and Transitions Between Them

If your app has multiple tiers (Basic, Pro, Enterprise), you need a subscription group in App Store Connect. All tiers belong to one group; a user can have only one active subscription in a group at a time.

Upgrade (to a higher tier) takes effect immediately; Apple recalculates the remaining balance. Downgrade (to a lower tier) takes effect at the next billing period. Crossgrade (same price, different tier) depends on configuration: immediate or deferred.

Track transitions on the client via originalTransactionID and subscriptionGroupID. On the server, store full transaction history and handle Apple Server Notifications v2 (App Store Server Notifications). Critical event types: DID_RENEW, DID_FAIL_TO_RENEW, EXPIRED, GRACE_PERIOD_EXPIRED, REFUND.

How to Handle Tier Transitions?

Upgrades activate immediately — Apple prorates the cost. Downgrades are deferred until the next cycle. Crossgrades can be immediate or deferred as set in App Store Connect. Update the UI accordingly, showing the effective date of the change. Use renewalInfo.renewalDate and offerType.

Introductory and Promotional Offers

Introductory pricing (first N periods at a reduced price) is configured in App Store Connect and automatically applied to new subscribers. Problem: a user who cancelled and wants to return does not get the intro price again. For that, promotional offers exist — you can grant them based on your logic (win-back campaigns).

The signature for a promotional offer is generated on the server with the private key from App Store Connect:

// On the client, create paymentDiscount let discount = SKPaymentDiscount( identifier: "winback_3months", keyIdentifier: keyID, nonce: nonce, // UUID from server signature: signature, // signature from server timestamp: timestamp ) payment.paymentDiscount = discount 

Without a server-generated signature, the promotional offer is invalid — Apple validates the signature server-side.

What's Included in the Work

• Audit of current IAP implementation and subscription groups
• Design of tier and group schemas (subscription groups) aligned with business logic
• Integration of StoreKit 2 with support for grace period, billing retry, and error handling
• Configuration of App Store Server Notifications (v2) on the backend with critical event processing
• Implementation of win-back logic using promotional offers
• Code documentation and churn analytics integration
• Team training on Sandbox and subscription testing
• Post-launch support (1 month free)

Our Work Process

Current implementation audit → design subscription group and tier structure → integrate StoreKit 2 with grace period and billing retry → configure App Store Server Notifications on the backend → implement win-back and promo offer logic → test in Sandbox with simulated expiration (Sandbox compresses time: 1 month = 5 minutes).

Timeline: 3–5 days depending on number of tiers, backend presence, and churn analytics requirements. Cost is determined individually after analyzing your project. Contact us for a consultation — we'll assess scope and propose the best solution. Get advice from a certified iOS developer with 5+ years of subscription implementation experience.

We guarantee: correct handling of billing retry, grace period, and all transition types, compliance with App Store Review Guidelines (Sections 4.2 and 5.1), and full support during testing and release.