Hi, this is Renat from Apphud . In this article we will tell you what the levels of auto-renewable subscriptions are, how to configure them correctly and in what cases the user is refunded for an unused paid period.
What is the subscription level?
This is the designation of the subscription class, depending on the level of service it offers. Subscription of the first class means the highest level of service, the second class - lower, and so on. In fact, rarely in which application can you find two levels of subscriptions, not to mention three or more.
Two subscription levels in The New York Times app.
How to set up subscription levels?
To configure your subscription levels, go to the App Store Connect , select your application and go to the Features tab. In the in-app purchases section, move your subscription one level up or down. To do this, select the desired subscription by pressing and holding the drag icon and move the subscription to the desired level.
Drag and drop a subscription to a higher level.
Subscription number 1 should offer the highest level of service, for example, subscription to all categories of magazines. There is no dependence between the duration of the subscription and its level. So, the highest subscription can be annual, and a subscription at a level lower than monthly.
Change subscription
The user can change the subscription in the App Store application after its registration. It can increase (upgrade), lower (downgrade) the level or change the subscription within the same level (cross-grade).
Subscription level upgrade (upgrade)
If the user's current subscription is active, then he will immediately switch to a new tariff, and the unused portion of the paid period will be returned to the card.
Notification that part of the funds will be refunded upon upgrade of the subscription.
At the end of the article, we will look at how to catch the increase in the subscription level and calculate the amount of return.
Subscription downgrade (downgrade)
By lowering the level, the user switches to a new one at the end of the current paid period. Funds are not refunded, and the cost of a new subscription is debited when it is activated.
Change of subscription at the same level (cross-grade)
This is a common situation, it is divided into two types: change of subscription of the same duration and different. When changing a subscription with a different duration, the same thing will happen as with a downgrade: the subscription will be applied at the end of the current paid period.
If the durations match, the current subscription will be canceled and a new one will start immediately. The money will be debited for the new subscription, and the unused part of the old subscription will be returned to the user.
How to find out about changing the subscription on the server?
You can validate the App Store check or listen to Apple server notifications .
While checking each new transaction, you need to look to see if product_id has changed. Changing product_id means that the user has changed their subscription in the App Store settings.
In addition, you can look at the value of auto_renew_product_id
in pending_renewal_info
. It will help you learn about a change to product_id before a new subscription takes effect.
If you have server notifications configured, listen to the DID_CHANGE_RENEWAL_PREF notification that is called when a product is changed . You can limit yourself to this notification and get the new product_id from the request parameters, or you can re-check the App Store check. In the latter case, Apple server notifications will only serve as a trigger for an unscheduled check.
How to calculate the amount of return for upgrades?
To understand whether there was an upgrade, you need to check the value of the is_upgraded
field. A value of true
indicates that the next transaction is already in the new subscription.
Note that is_upgraded
will be true
even when changing a subscription with the same duration within the same level. That is, is_upgraded = true
does not mean an increase in the level, but the fact that the subscription was changed with a refund.
In addition to the is_upgraded
field, the cancellation_date
field will appear in this transaction, which indicates the time of cancellation. It equals or almost coincides with the start date of the next transaction.
It turns out that the cancellation_date
field appears not only when the subscription is returned , but also when upgrading.
Note that when upgrading Sandbox subscriptions, the cancellation_date
field is missing . Therefore, when testing in Sandbox, you need to use the purchase_date
next transaction instead of cancellation_date
. Read more about cancellation date in the Apple documentation .
To calculate the amount that should be returned to the user, you need to divide the unused period by the full period of the previous subscription and multiply by its cost:
# upgrade_date is `cancellation_date` in prodiction 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 is this implemented in Apphud?
Apphud automatically tracks changes in subscriptions and calculates the return of unused parts.
An example of a subscription change at the same level with a refund of part of the funds in Apphud.
An iOS developer is not required to handle these situations himself. You just need to integrate the SDK, the rest will be done by Apphud.
Conclusion
It turns out that just updating the value of product_id
not enough: you also need to consider the refund for upgrades. Working with subscriptions requires handling many borderline situations. We make Apphud - a service that greatly simplifies the work with subscriptions. You can start using it for free. Registration - at this link .