iOS Subscription Groups Explained

It is essential to understand subscription groups before planning your in-app purchases.

iOS Subscription Groups Explained
Jacob Eiting

Jacob Eiting

PublishedLast updated

In 2016 Apple announced new incentives for developers to maintain their customers on a continuous subscription for more than a year. Apple simultaneously introduced subscription groups: a way of grouping subscription products that makes managing active subscriptions easier.

It is essential to understand subscription groups before planning your in-app purchases.

Subscription groups

A subscription group is a collection of subscription products that has some specific properties.

  • No two products in a subscription group can be active at the same time.
  • A free trial or introductory price can only be used once per group.
  • A subscription group also determines the service level of each product, determining the upgrade/downgrade/crossgrade behavior.
  • Subscription groups have localized description data that determine how your app appears in the management menu in the App Store settings.
ios subscription groups explained
How a subscription group affects what your customer sees while managing subscriptions.

Subscription groups solved two major user experience issues:

  • Users could now upgrade or downgrade their subscriptions without having to cancel first, wait for the expiration, and re-purchase.
  • Users could no longer accidentally end up with simultaneous subscriptions.

Moving within a subscription group

There are two ways for a user to change an active subscription:

  • The subscription management page in Settings app.
  • In your app by initiating an in-app purchase of a product in the same group as another active subscription product.

These options give the user a vastly simplified experience; however, for the developer, there are some considerations.

Via the Settings app

When a user changes subscriptions via the settings app, your application will not be running, and you cannot observe the appearance of new SKPaymentTransaction on the StoreKit payment queue. You have three options to handle this correctly:

  1. Poll the lastest_receipt_info for your user’s past receipts with a sufficiently high frequency
  2. Have Apple’s Status Update Notifications hooked up.
  3. Use RevenueCat (my personal favorite)

If your app doesn’t have any cross-platform features, you could rely on hopefully receiving the SKPaymentTransaction on the next app launch, and refresh your receipt data then. This option doesn’t work if your subscription provides any content outside of the app.

As an in-app purchase

Alternatively, you can change a subscription from within your app, the same way you initiate a standard in-app purchase. When initiating an upgrade or downgrade purchase, StoreKit presents a modified version of the purchase flow:

If a group already has a subscription, a purchase for a product in the group will initiate a change.

Offering upgraded subscriptions from within the app is a technique that you don’t often see implemented. Every app that offers short and long-term subscriptions can be providing UI for users to upgrade and downgrade their subscriptions. Side-note: I hope that Apple extends this to allow for canceling in iOS 12

After a user has initiated an upgrade, downgrade, or crossgrade, the way that this executes is a little complicated.

Upgrading, Downgrading, and Crossgrading! Oh My!

To better illustrate these somewhat complicated behaviors, let’s consider a scenario. Below are several examples based on a subscription group that contains two service levels, each which contain two products of varying durations.

Upgrading Service Levels

Upgrading from a lower to higher service level stops the current subscription immediately and refunds the remainder of the period, simultaneously initiating a subscription for the new product.

Upgrading service levels occurs immediately.

Downgrading Service Levels

Downgrading behaves differently. When a user downgrades service levels, the subscription they currently have always continues until the original expiration date. After that, the new product begins its period.

Downgrading doesn’t occur until the end of the current subscription period.

Crossgrades Within a Service Level

Things start to get more complicated when a user moves within the same service level, a.k.a. a crossgrade. How a crossgrade executes depends on the duration of the products involved.

If both products have the same duration, it behaves like a service upgrade, immediately ending and refunding the remainder of the current subscription and initiating the new product’s subscription.

Crossgrading to a product with the same duration behaves like upgrading a service level.

When crossgrading between two products in the same service level with different durations, it behaves like service level downgrading.

Crossgrading between different duration products behaves like downgrading.

For all the complexity, a proper subscription group and service level configuration can create a very smooth experience for the user if executed correctly.

How to use service levels

For most subscription apps, you can get away with all products in the same group and one service level. This setup would be something like a “Pro” plan, and within that, you had “Pro (1 Month)”, “Pro (6 Month)”, and “Pro (1 Year)”. In this case, subscription change behavior will behave as in the “Crossgrading, Different Duration” diagram.

A user upgrading and downgrading within one service level.

The correct instance to use multiple service levels is when you have differentiated offerings. For example, you may offer a Pro plan and Pro+ plan, where Pro+ provides access to additional features or content. Each plan will have three products, one for each duration. By putting the Pro+ products in the higher service level, users are allowed to instantly upgrade from Pro to Pro+ without having to wait until the end of the current subscription period.

Unsubscribed days during the grace period do not count, however, if the user resubscribes before the end of the grace period, the days accumulated before the cancellation are retained.

Apple’s share of the pie

It’s easy to lose sight of why this is important: to get users through to one year of continuous subscription. After this point, Apple reduces the cut of revenue from 30% to 15%. To aid in this, Apple also introduced a 60-day “grace period” following a user canceling a subscription, where, if they resubscribe, they keep their accumulated days.


Subscription groups make testing prices more difficult. Because all products in a subscription group are visible to the user via the subscription settings, you can’t add a one-off product to a subscription group at a different price and control who sees it. If you want to A/B test two prices for a product you will need to create two entirely parallel subscription groups. Deploying and maintaining entire parallel subscription groups can be challenging to manage, especially if you are doing multiple price tests (which you should be.)

Because free trials and introductory prices are limited to one usage per group, the group that a product belongs to is required to compute product eligibility. Apple doesn’t provide this information in SKProduct , so developers need to carry around the product identifier and the subscription group if they want to be able to compute introductory price eligibility correctly. (Introductory price eligibility is now available with RevenueCat)

Use subscription groups and use them well

Subscription groups on balance were a great addition to the iOS subscription eco-system. They protect the user, sensible defaults, and even some opportunities for the developer. Before you launch your subscription in-app purchase product, make sure you take into consideration the specific behaviors of groups and service levels, so that you understand the experience you will be delivering.

In-App Subscriptions Made Easy

See why thousands of the world's tops apps use RevenueCat to power in-app purchases, analyze subscription data, and grow revenue on iOS, Android, and the web.

Related posts

Cache at RevenueCat

Scaling smoothly: RevenueCat’s data-caching techniques for 1.2 billion daily API requests

A deep-dive into the techniques that fuel our efficient cache management.

Guillermo Pérez

Guillermo Pérez

October 31, 2023


How to use offering metadata to A/B test your paywall with Experiments

Even if you’re using a custom paywall, you can run experiments with RevenueCat

Charlie Chapman

Charlie Chapman

August 31, 2023


How to use StoreKit views to build a subscription app paywall with SwiftUI

A guide on Apple’s new StoreView, ProductView, and SubscriptionStoreView APIs for building native paywalls for your subscription app.

Charlie Chapman

Charlie Chapman

August 25, 2023

Want to see how RevenueCat can help?

RevenueCat enables us to have one single source of truth for subscriptions and revenue data.

Olivier Lemarie, PhotoRoomOlivier Lemarie, PhotoRoom
Read case study