What’s new in Apphud: SplitMetrics Acquire Integration, Experiments Improvements, SDK UpdatesLet’s see
Why Apphud?PricingContact
November 14, 2019
12 min read

A Simple Guide to iOS Subscription Levels

In this article, we’ll go over subscription levels and their configuration.

A Simple Guide to iOS Subscription Levels

You’ll learn what subscription levels are, how to configure them, and in which cases users get a refund after changing their subscription. But first, it is important to understand what a subscription group is.

To put it simply, it is a combination of products inside your app that grant access to a bunch of the app’s features. While creating a subscription group, a product must be added to it. This means it is necessary for you to have a minimum of one subscription group. For the majority of apps, one group is enough.  It also has to be said that a person using an app may only have one subscription per group. The introductory offer can also be used just once within a group.

What are subscription levels?

Now that you know what AppIe subscription groups are, it will be easier for you to digest what subscription levels are. They are part of a ranking system, where the highest subscription level offers the most features and content. Subscriptions can be ranked at the same or different levels. In reality, very few apps offer more than one subscription level. In most cases, apps with multiple subscription levels are content-based apps, like the NY Times newspaper app — it offers basic and premium subscriptions with different levels that belong to the same subscription group.

Two subscriptions of different levels in "The New York Times" appTwo subscriptions of different levels in "The New York Times" app

Let's dissect how other famous apps use subscription levels. YouTube and its YouTube Premium subscription allow you to watch content without ads.  Duolingo Plus lets you use its app without any limits. And then, of course, there are Netflix’s basic, standard, and premium subscription plans, which give users an opportunity to download content onto their devices and choose the streaming quality.

It’s up to you to configure the logic of providing access for users on your app. The App Store’s provided subscription service level helps distinguish which level of premium access a customer will get for each product. Without knowing the subscription service level for each product, the App Store will not be able to process what to do with a subscriber when they switch between products.

How to set up subscription levels?

To set up a subscription level, go to your app in App Store Connect and then open your subscription group. There, you will be able to rearrange subscriptions by dragging them up or down.

Changing subscription levelsChanging subscription levels

The topmost subscription should offer the best service. The subscription duration doesn’t depend on the level. For example, you could have only a yearly subscription for the top level and only a monthly subscription for the lower level.

Subscription Level Changes

After purchasing a subscription, a user can manage it in App Store settings. Users can upgrade, downgrade, or cross-grade their subscriptions. Let’s take a closer look.

1. Subscription Upgrade

What we mean by subscription upgrade are the cases in which a customer decides to change their current subscription to one that provides higher quality services, more content, etc. Switching from Premium Apple Music to Family Premium may serve as a good example. If the current subscription is active, the user will be immediately switched to the new subscription and receive a refund of the prorated amount of their previous subscription. After upgrading their subscription, the customer will be charged the new price for their monthly subscription. The upgrade will be applied immediately.  Later on in this article, we’ll show you how to determine a subscription upgrade and calculate the prorated amount.

Subscription upgradeSubscription upgrade

2. Subscription downgrade

When a user chooses subscription with lower level, the new subscription starts from the next renewal date with the new price and duration.

As for a subscription downgrade, it is the direct opposite of a subscription upgrade. It happens when a customer decides to subscribe to a lower service instead of a higher one.  When a user chooses a subscription with a lower level, the new subscription starts from the next renewal date with the new price and duration. 

The new price for a lower-level subscription should obviously be lower. It is one of the main reasons why people downgrade their subscriptions. Maybe they just can’t afford it anymore but still want to continue using your app. So, this is why having a lower-level subscription is good. It will help you keep such users, and it will help them save their money.

3. Subscription cross-grade

We call it a cross-grade when a user transfers from one in-app subscription to another one of the same service level. This is the most common situation. There are two cases: the user either switches to a subscription with the same or different duration.

When switching a subscription to a different duration, the process will be the same as downgrading. The new subscription will be applied at the next renewal date.

However, when a user changes to a subscription with the same duration, the process will be the same as upgrading. The new subscription will start immediately, and the user will receive a refund of the prorated amount of their previous subscription.

How to determine a subscription change in your server?

First of all, due to Apple’s in-app purchase pricing tiers, Apple has been providing users from all around the globe with consistent payment experiences. To determine whether a subscription was changed, you should validate the user’s App Store receipt or set up Apple server-to-server notifications.

You can check the auto_renew_product_id field in pending_renewal_info to know which subscription will be renewed at the next renewal date. Another way is to check the product_id in each transaction from the latest_receipt_info array. If you have server-to-server notifications enabled, you should listen for a DID_CHANGE_RENEWAL_PREF notification. It will contain the new product_id in request parameters.

How to Calculate the Refund Amount?

To know whether a subscription was upgraded, you should check for the is_upgraded field in the transaction’s JSON. If it’s true, then the subscription was upgraded, and the next transaction belongs to the new subscription.

The field is_upgraded will be true also when cross-grading a subscription of the same duration. In other words, is_upgraded = true is not actually an upgrade, but it’s changing the subscription with a refund.

Besides the is_upgraded field, there will also appear the cancellation_date, which is the time the user made an upgrade. It equals or almost equals the purchase date of the new transaction.

So, the cancellation_date field appears not only upon a subscription refund, but upon an upgrade as well. Another thing is that cancellation_date doesn’t appear in Sandbox. While testing in Sandbox, you should check the purchase_date of the new transaction instead of cancellation_date. More information is available here.

To calculate prorated amount of the refund, you should divide unused portion of subscription duration by the full duration:

# upgrade_date is `cancellation_date` in production or purchase_date of new transaction in sandbox

# to_f converts date to float timestamp value

prorate_amount = price * (upgrade_date.to_f - cancellation_date.to_f) / (expires_date.to_f - purchase_date.to_f)

How it works in Apphud?

Apphud automatically tracks all subscription changes, and calculates prorated amount of the refund if applicable.

Example of subscription upgrade with partial refundExample of subscription upgrade with partial refund


As it turns out, just updating the value of product_id is not enough. In the case of a subscription upgrade and cross-grade with the same duration, you should calculate the prorated amount of the refund.

Working with subscriptions is hard. There are lots of situations you should take into consideration. You can start using Apphud – a tool for developers that makes working with subscriptions easy. You can start using it today for free.

Co-founder at Apphud
Ex iOS app and game developer. 11 years in the industry since iOS 3. More than 50 apps are in the background with 4 exits. Entrepreneur and traveler.