Events for Upgrades, Downgrades, and Crossgrades

Subscriptions that support upgrades, downgrades, and cross-grades can be tricky to understand. Different purchase platforms handle these events in different ways, creating more potential for confusion.

Adding yet another layer of complexity is that apps themselves may wish to handle these events differently than the default behaviors implemented by the purchase platform.

For example, an app that offers a monthly and yearly subscription for the same features works differently than an app selling different quantities of items with their subscription products.

Let's start by looking at some information about how specific purchase platforms handle this and then we'll jump into the events Nami produces and how to use them.

Purchase Platforms

Apple

Apple determines whether a change in the purchased product SKU is an upgrade, downgrade, or cross-grade based on the Subscription Group.

SKUs that should be able to be switched between must be in the same Subscription Group, otherwise, Apple will consider it to be a purchase of a new product.

SKU Change Type	Definition	When does it take effect?
Upgrade	The subscription product is at a higher level (lower number) in the subscription group	Immediately
Downgrade	The subscription product is at a lower level (higher number) in the subscription group	At the start of the next bill term
Crossgrade	The subscription product is at the same level and number in the subscription group	Immediately if bill terms are the same. If they are different, at the next bill term.

Free Trials

Apple always completes the free trial of any purchased product SKU in a subscription group before executing an upgrade, downgrade, or crossgrade.

For some apps, this can result in unexpected behavior if you want to affect a SKU change immediately.

Apple's official documentation: https://developer.apple.com/app-store/subscriptions/

Events

It is not always possible to determine if an upgrade, downgrade, or crossgrade occurred. The rules are not consistent cross-platform, and the purchase platforms do not always provide enough context around what occurred to enable Nami to apply these labels directly.

The Nami platform handles reporting reliably on these changes by providing 2 events:

Event Name	Description
user.subscription.sku_change	The active purchased SKU for a subscription has changed.
user.subscription.pending_sku_change	The active purchase SKU will change at the start of the next bill term. This event is produced at the time when the customer requests the SKU change.

Additionally, every Nami event produced that contains a list of the current Active Entitlements, will include a field pending_sku_ref_id. This field contains the SKU reference ID (set in the Nami Control Center) for the SKU that will be active after the next renewal occurs.

The list of Active Entitlements is provided in every user.subscription.* event. Below is an example payload.

{
  ...
  "active_entitlements": [
    {
      "name": "Tiered Access",
      "expiration": "2021-08-30T22:58:34+00:00",
      "sku_ref_id": "tier_gold",
      "description": null,
      "last_verified": "2021-08-30T22:55:34.464481+00:00",
      "purchase_platform": "apple",
      "entitlement_ref_id": "tiered_access",
      "pending_sku_ref_id": "tier_bronze"
    }
  ]
  ...
}

Common Scenarios

Pending Downgrade

In this example payload, you can see that the current active SKU is tier_gold but at the start of the next bill term, the customer will be downgraded to tier_bronze.

{
  ...
  "active_entitlements": [
    {
      "name": "Tiered Access",
      "expiration": "2021-08-30T22:58:34+00:00",
      "sku_ref_id": "tier_gold",
      "description": null,
      "last_verified": "2021-08-30T22:55:34.464481+00:00",
      "purchase_platform": "apple",
      "entitlement_ref_id": "tiered_access",
      "pending_sku_ref_id": "tier_bronze"
    }
  ]
  ...
}

Renewal for the same Product SKU

{
  ...
  "active_entitlements": [
    {
      "name": "Tiered Access",
      "expiration": "2021-08-30T22:58:34+00:00",
      "sku_ref_id": "tier_gold",
      "description": null,
      "last_verified": "2021-08-30T22:55:34.464481+00:00",
      "purchase_platform": "apple",
      "entitlement_ref_id": "tiered_access",
      "pending_sku_ref_id": "tier_gold"
    }
  ]
  ...
}

Enabling access to a Pending SKU Change

Apps that sell access to a quantity of items each month may want to grant access to that new quantity immediately on the SKU change, even if the purchase platform has not charged the user and made the change.

When you see the new SKU in the pending_sku_ref_id field, you may optionally use this to change the access tier in your app, even if the purchase platform has not made the change yet.