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.

Control Center Setup

In order for an upgrade, downgrade, or cross-grade to occur correctly, the Product SKUs that you wish to allow SKU Changes for must all grant the same set of entitlements.

The Product SKUs may grant more than one entitlement as long as each SKU grants the exact same group of multiple entitlements.

📘

Nami currently does not support upgrades or downgrades where the current active Product SKU and the newly purchased Product SKU have overlapping, but not exactly the same entitlements.

In this case, the newly purchased Product SKU will be treated as an entirely new purchase, and new entitlements will be granted to the customer.

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.

You can configure Subscription Groups 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.

Play Store

For Android Apps on the Google Play store, there is no setup required in the Play Console. Simply ensure you have created your Product SKUs and Entitlements with the correct relationships as described in the section above.

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.

🚧

Upgrades and Downgrades May Not Happen in the same Session

Please note this important limitation on upgrades and downgrades with our Google Play SDK.

The app must go to the background between each purchase.

If an app user tries to do an upgrade or downgrade in the same session, the 2nd purchase will be treated as a new purchase and not an upgrade or downgrade.

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