Upgrades and Downgrades

Nami makes it easy for you to provide upgrade, downgrade, and crossgrade options to your customers.

In this guide, we'll cover how to properly configure your app for upgrades and downgrades, how they work, and how to test them.

Note each payment platform works a little differently for changing Product SKUs, so we will cover each platform separately below.

App Store

In order for Apple to properly execute an upgrade or downgrade on a new purchase, all the Product SKUs must belong to the same Subscription Group.

Subscription Groups are configured in App Store Connect.

🚧

Products in App Store Connect are assigned to a Subscription Group at the time they are created and cannot be changed later.

If you need to change your products into a different subscription group to enable upgrades and downgrades, you'll need to create brand new products.

To see the Products SKUs in your Subscription Group, select your App, then under Features click on Subscription Groups. Then select the group you'd like to look at from the list.

After clicking on a Subscription Group, you'll be able to see the order of the Products SKUs. Products SKUs are ordered in the group where 1 is the highest tier. A product SKU assigned to a higher number will indicate a downgrade from your highest tier. Two Product SKUs at the same number will be a crossgrade.

A new purchase that triggers an upgrade, downgrade, or crossgrade will be executed at different times.

• Upgrade Upgrades happen immediately and the customer will be billed right away. They will be refunded the pro-rated amount of the original subscription.
• Downgrade A downgrade is deferred until the start of the next billing cycle. The customer's bill term and price will change at the end of their current billing cycle.
• Crossgrade For crossgrades, if the bill term is the same length, the purchase will be made immediately. If the bill terms are different, the purchase will happen at the end of the current bill term.

🚧

Free Trials Have Different Rules

Upgrading, downgrading, or crossgrading during a Free Trial period will always result in a deferral of the new purchase until the end of the current bill term.

📘

Granting Immediate Access to a Deferred Product Change

On Apple platforms, Nami enables you to immediately provide access to the new Product SKU, even though the change will not go into effect until the current bill terms ends.

This can be particularly important to unlock additional functionality in your app if the user upgrades during a free trial.

We provide the pending_sku_ref_id in the active entitlement data returned by the activeEntitlements call, which you can check to see if the customer has a pending Product SKU change.

We also produce a user.subscription.pending_sku_change event that can be consumed by your server through our webhooks.

For more on Subscription Group setup, see Apple's documentation.

Google Play Store

For Android Apps on the Google Play store, there is no setup required in the Play Console using the current Nami SDK which utilizes Google Play Billing library version 4.0.

However, some care needs to be given to the Product SKU and Entitlement relationship in the Nami Control Center.

In order for upgrade, downgrade, or cross-grade to work correctly for Google Play, the Product SKUs that you wish to allow SKU Changes for must all share at least one entitlement.

Each Product SKU may grant more than one entitlement as long as each SKU grants at least one shared entitlement.

📘

Apps with Multiple Tiers

If your app offers multiple tiers of service, your Product SKUs should be associated with two entitlements: one for the appropriate tier (e.g. the "bronze" entitlement) and one for all Product SKUs that are allow to upgrade, downgrade, or cross grade between each other (e.g. the "upgrade" entitlement).

In this way, the upgrade entitlement acts similarly to Apple's subscription group concept.

Importantly, if two Product SKUs do not share the overlapping upgrade entitlement, the newly purchased Product SKU will be treated as an entirely new purchase.

For Google Play Apps the rules about Upgrades and Downgrades are nearly identical to Apple, except for upgrades that happen during a free trial.

Here's how we define upgrades and downgrades on Google Play. First, there must be an already active subscription purchase. If a 2nd purchase is then initiated, we check to see if the entitlements granted by the purchase match exactly. If they do, then:

• Upgrade The price of the new Product SKU is higher than the current active purchase
• Downgrade The price of the new Product SKU is less than or equal to the current active purchase

Timing of when an upgrade or downgrade is initiated:

• Upgrade - Immediately upgraded and charged a pro-rated price for the newly purchased SKU for the remainder of the current billing term.
• Downgrade - Deferred to the next billing term.
• Upgraded During Free Trial - Immediately upgraded and no pro-rated price charged for the newly purchased SKU. First billing will be at the next bill term when the user exits the free trial.
• Downgrade During Free Trial - Deferred to the next billing term.

🚧

A Note about the Mechanics of Deferred Purchases

On Google Play, deferred purchases are not issued a purchase token, order ID, etc. until the purchase becomes active, at the beginning of the next bill term.

If a user tries to upgrade or downgrade when there is a current deferred purchase, Google Play's payment sheet will surface an error message to the end user.

In a further SDK update, Nami will provide a mechanism so you can check if there are any known deferred purchases, so you can message the user appropriately.

Android App Testing

When testing on Android devices, look for specific screens in Google's purchase process to indicate that Google has properly initiated the upgrade or downgrade and not an entirely new purchase.

Upgrade example screen: Look for the prorated price that will be billed today and then the new price at the next billing term in the Upcoming charges section of the payment sheet.

For a downgrade, check the time of the first billing event. It should be in the future at the time of your next renewal and not immediately. If the time shows that it will happen immediately, then the app will not execute a downgrade.

After doing an upgrade or downgrade, it is a good idea to check the Google Play app. Then click your account icon, and select Payments and Subscriptions and ensure there is only 1 subscription under Active.

🚧

Do not rely on RTDN events to understand upgrades and downgrades

Google's real-time developer notifications do not have a 1:1 relationship with a Product SKU change for upgrades and downgrades. There is information from the purchase token response on the overall entitlement state that must be taken into account.

See our next section on events for how our User Entitlement Engine logs these changes.

Events

To help you track upgrades and downgrades, the Nami Platform produces Product SKU change events. These can be used with our integrations such as Webhooks to inform your systems about upgrades, downgrades, and in some cases about pending changes as well.

Product SKU Change events

• user.subscription.sku_change - this event tells you there's been an upgrade or downgrade. This will occur at the start of a new billing cycle and will be accompanied by a user.subscription.renewed event.
• user.subscription.pending_sku_change - this event is produced on platforms where the upgrade or downgrade is deferred until the next billing cycle and Nami is able to identify that there is a pending change

📘

Pending SKU Changes are only supported on Apple