iOS subscription groups explained
Subscription groups are the structural layer that decides how a customer moves between subscription products on iOS. Before you finalize in-app purchase products, you need to know which products can coexist, how service levels rank them, and what happens when a user switches. This guide walks through the group model, the three switch types, and the practical limits on testing and eligibility.
What a subscription group actually controls
A subscription group is a set of subscription products that share rules. Four properties matter most for planning:
- Mutual exclusivity: no two products in the same group can be active at once.
- Introductory offer limits: a free trial or introductory price can be used only once per group.
- Service levels: each product is assigned a level, and that ranking drives upgrade, downgrade, and crossgrade behavior.
- Localized description: the group carries localized text that shapes how the app appears in the App Store subscription management screen.
The group model solved two earlier user-experience problems. Customers can now change plans without canceling, waiting for expiry, and repurchasing. They also can no longer accidentally hold two simultaneous subscriptions.
Two paths for changing an active subscription
A customer can change a subscription in two places:
- The subscription management page in the Settings app.
- Inside your app, by purchasing a product that belongs to the same group as the active subscription.
The first path happens while your app is not running. You will not see a new SKPaymentTransaction arrive on the StoreKit payment queue. You have three handling options:
- Poll lastest_receipt_info for the user's past receipts at a high enough frequency.
- Connect Apple's Status Update Notifications.
- Use a subscription management service.
If your app has no cross-platform features, you can rely on receiving the transaction at the next launch and refresh receipt data then. That fallback fails if the subscription unlocks content outside the app.
Switching from inside the app
An in-app change starts like any standard in-app purchase. When the group already has an active subscription, StoreKit presents a modified purchase flow that treats the purchase as a plan change rather than a new subscription. Offering upgrade and downgrade UI inside the app is a technique many apps skip, even though it is available to any app that sells short- and long-term plans.
Upgrade, downgrade, and crossgrade behavior
The timing of a change depends on the direction of the move and, for crossgrades, on product duration. Use this decision table when planning your product catalog:
A worked example: suppose a group holds two service levels, each with two products of different durations. A customer on the lower level buys a product in the higher level. The current plan stops at once and the unused portion is refunded, while the new plan begins. Reverse the direction and the current plan runs to its original end date before the new one takes over. Move between two products at the same level with equal durations and the result matches an upgrade; move between different durations and it matches a downgrade.
Choosing one service level or several
Most subscription apps can put every product in one group under a single service level. A typical setup is a Pro tier with monthly, six-month, and annual products. In that arrangement, switching between durations follows the crossgrade-with-different-duration behavior: the current plan runs to expiry, then the new one begins.
Multiple service levels make sense when your tiers differ in substance, not just billing period. If Pro and Pro+ unlock different features or content, placing Pro+ at a higher level lets a customer move from Pro to Pro+ instantly instead of waiting for the current period to end. Each tier can still carry one product per duration.
Decision checklist:
- Do your tiers differ only by billing period? Use one service level.
- Do higher tiers unlock additional features or content? Use separate service levels.
- Do you want instant movement to a higher tier? Rank it above the current tier.
- Do you want a lower tier to begin only after the current period? Rank it below.
Why the one-year mark matters
The commercial reason to care about continuous subscription time is Apple's revenue share. Once a subscriber passes one year of continuous service, Apple reduces its cut from 30% to 15%. Apple also introduced a 60-day grace period after cancellation: if the customer resubscribes within that window, previously accumulated days are retained. Days spent unsubscribed during the grace period do not count toward the total.
Limitations to plan around
Two constraints affect testing and eligibility.
Price testing: every product in a group is visible to the user through subscription settings. You cannot add a one-off product at a different price and limit who sees it. Comparing two prices for the same product requires two fully parallel subscription groups, and maintaining several parallel groups becomes difficult as the number of tests grows.
Eligibility calculation: because introductory offers are limited to one use per group, you need to know which group a product belongs to in order to determine eligibility. Apple does not expose that information in SKProduct. Developers must carry both the product identifier and the subscription group to compute introductory price eligibility correctly.
Pre-launch checklist
Before shipping a subscription product, confirm the following:
- Every product is assigned to the intended group.
- Service levels reflect real differences in features or content, not just price.
- You know which switches take effect immediately and which wait for expiry.
- Your app handles changes made in Settings, including when it is not running.
- You can compute introductory offer eligibility using both product identifier and group.
- Your price-testing plan accounts for the parallel-group requirement.
- Localized group descriptions are written for the App Store management screen.
| Move | Condition | Effect on current subscription | When new product starts |
|---|---|---|---|
| Upgrade | Lower service level to higher | Ends immediately; remainder refunded | Immediately |
| Downgrade | Higher service level to lower | Continues to original expiration date | After current period ends |
| Crossgrade | Same service level, same duration | Ends immediately; remainder refunded | Immediately |
| Crossgrade | Same service level, different duration | Continues to original expiration date | After current period ends |
Frequently asked questions
Does an upgrade take effect immediately?
Yes. Moving from a lower service level to a higher one ends the current subscription at once, refunds the unused portion, and starts the new product.
When does a downgrade begin?
A downgrade keeps the current subscription running until its original expiration date. The new product's period starts after that.
Why does a crossgrade behave differently depending on duration?
Within one service level, equal durations trigger immediate replacement with a refund of the remainder. Different durations defer the change until the current period ends.
Can a customer get a second free trial by switching products?
No. A free trial or introductory price is limited to one use per subscription group, so switching to another product in the same group does not reset eligibility.
How does my app learn about a change made in Settings?
The app is not running at that moment, so no new SKPaymentTransaction appears on the queue. You can poll lastest_receipt_info frequently, connect Apple's Status Update Notifications, or use a subscription management service. Apps without cross-platform features can refresh receipts at next launch, but that fails when the subscription unlocks content outside the app.
Can I A/B test two prices inside one subscription group?
No. All products in a group are visible in subscription settings, so a separate price cannot be hidden from some users. Testing two prices requires two parallel subscription groups.