Créer iOS Subscription Group

Subscription groups are essential for organizing and managing multiple subscription levels in your iOS Application. Understanding how they work is crucial for implementing Mise à niveau, downgrade, and crossgrade functionality.

What is a Subscription Group?

A subscription group is a collection of related subscriptions that Utilisateurs can choose between. Utilisateurs can only subscribe to one subscription within a group at a time. When they switch subscriptions, Apple handles the transition automatically.

Why Subscription Groups Matter

Subscription groups Activer:

• Tiered pricing: Offer basic, premium, and ultimate plans
• Different durations: Monthly, yearly, and lifetime Options
• Mise à niveau/downgrade logic: Automatic handling of subscription changes
• Simplified management: Group related subscriptions together

Subscription Levels

Within a group, each subscription should be ranked from highest value (level 1) to lowest value. This ranking determines how subscription changes are classified:

Level Exemples

Level 1 (Highest Value)

• Premium Annual ($99.99/year)
• Ultimate Monthly ($19.99/month)

Level 2 (Medium Value)

• Standard Annual ($49.99/year)
• Premium Monthly ($9.99/month)

Level 3 (Lowest Value)

• Basic Annual ($29.99/year)
• Standard Monthly ($4.99/month)

Subscription Change Types

Apple automatically handles three types of subscription changes based on the level ranking:

1. Mise à niveau

Moving to a higher-tier subscription (e.g., level 2 → level 1).

Behavior:

• Takes effect immediately
• Utilisateur receives prorated refund for remaining time
• Nouveau subscription starts right away

Example:

// User currently has: Standard Monthly (Level 2)
// User upgrades to: Premium Annual (Level 1)
// Result: Immediate access to Premium, refund for unused Standard time

2. Downgrade

Moving to a lower-tier subscription (e.g., level 1 → level 2).

Behavior:

• Takes effect at Suivant renewal date
• Utilisateur keeps current subscription until period ends
• Nouveau subscription starts automatically after expiration

Example:

// User currently has: Premium Annual (Level 1)
// User downgrades to: Standard Monthly (Level 2)
// Result: Premium access continues until annual renewal date, then switches

3. Crossgrade

Switching to another subscription at the same tier level.

Behavior depends on duration:

Different Duration → Behaves like downgrade

• Takes effect at Suivant renewal date
• Exemple: Monthly Premium (Level 1) → Annual Premium (Level 1)

Same Duration → Behaves like upgrade

• Takes effect immediately
• Exemple: Premium Monthly (Level 1) → Ultimate Monthly (Level 1)

Creating a Subscription Group

1. Navigate to Subscriptions

   In Application Store Connect, select your Application and go to Monetize > Subscriptions.

2. Créer Group

   Click + Suivant to “Subscription Groups” to Créer a Nouveau group.

3. Name the Group

   Choose a descriptive name that reflects the subscriptions it contains:

   • “Premium Access”
   • “Cloud Storage Plans”
   • “Pro Fonctionnalités”

4. Ajouter Subscriptions

   After creating the group, Ajouter individual subscriptions to it. Each subscription will have a level ranking.

5. Set Level Rankings

   Arrange subscriptions from highest value (1) to lowest value. Consider:

   • Annual plans typically rank higher than monthly
   • Higher-priced tiers rank above lower-priced ones
   • Ultimate/premium tiers rank highest

Using in Your Application

The Natif-purchases plugin automatically handles subscription group logic:

import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';

// Fetch all subscriptions in a group
const { products } = await NativePurchases.getProducts({
  productIdentifiers: ['premium_monthly', 'premium_annual', 'ultimate_monthly'],
  productType: PURCHASE_TYPE.SUBS,
});

// Display current subscription using StoreKit transactions
const { purchases } = await NativePurchases.getPurchases({
  productType: PURCHASE_TYPE.SUBS,
});

const activeSubs = purchases.filter((purchase) => purchase.isActive);

// Detect pending downgrade/cancellation (StoreKit sets willCancel === true)
const pendingChange = purchases.find((purchase) => purchase.willCancel === true);
if (pendingChange) {
  console.log('Subscription will stop auto-renewing on', pendingChange.expirationDate);
}

// Purchase (StoreKit handles upgrades/downgrades automatically)
await NativePurchases.purchaseProduct({
  productIdentifier: 'premium_annual',
  productType: PURCHASE_TYPE.SUBS,
});

// Listen for StoreKit updates (fires on upgrades/downgrades/refunds)
NativePurchases.addListener('transactionUpdated', (transaction) => {
  console.log('Subscription updated:', transaction);
});

Handling Subscription Changes

Detecting Change Type

import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';

// Get current subscription info
const { purchases } = await NativePurchases.getPurchases({
  productType: PURCHASE_TYPE.SUBS,
});

const currentSubscription = purchases.find(
  (purchase) => purchase.subscriptionState === 'subscribed',
);

if (currentSubscription) {
  // StoreKit reports if user cancelled auto-renew
  if (currentSubscription.willCancel) {
    console.log(
      `User cancelled. Access remains until ${currentSubscription.expirationDate}`,
    );
  }

  if (currentSubscription.isUpgraded) {
    console.log('User recently upgraded to this plan.');
  }
}

// Listen for automatic upgrades/downgrades
NativePurchases.addListener('transactionUpdated', (transaction) => {
  console.log('Subscription changed!', transaction);
  if (transaction.subscriptionState === 'revoked') {
    revokeAccess();
  } else if (transaction.isActive) {
    unlockPremiumFeatures();
  }
});

Utilisateur Communication

Always communicate the change behavior clearly:

For Upgrades:

“You’ll get immediate access to Premium Fonctionnalités. We’ll prorate your current subscription.”

For Downgrades:

“You’ll keep Premium access until [renewal date], then switch to Standard.”

For Crossgrades:

“Your plan will change to Annual billing at the Suivant renewal on [date].”

Server monitoring

Use Apple’s App Store Server Notifications v2 or your own receipt-validation backend to mirror StoreKit changes in your database. Pair server notifications with the transactionUpdated listener so both client and backend stay in sync.

Best Practices

Group Organisation

• Keep related subscriptions in the same group
• Don’t mix unrelated Fonctionnalités (e.g., storage and ad removal)
• Créer separate groups for different Fonctionnalité sets

Level Ranking Strategy

• Annual plans → Higher level than monthly (for same tier)
• Higher-priced tiers → Higher level
• Consider value, not just price

Utilisateur Experience

• Show current subscription clearly
• Display all Disponible Options in the group
• Indicate which changes are immediate vs. at renewal
• Allow easy switching between plans

Test

• Test all Mise à niveau scenarios
• Test all downgrade scenarios
• Verify crossgrade behavior
• Vérifier webhook firing

Common Scenarios

Scenario 1: Three-Tier Monthly Plans

Level 1: Ultimate Monthly ($19.99)
Level 2: Premium Monthly ($9.99)
Level 3: Basic Monthly ($4.99)

• Basic → Premium: Mise à niveau (immediate)
• Premium → Ultimate: Mise à niveau (immediate)
• Ultimate → Premium: Downgrade (at renewal)
• Basic → Ultimate: Mise à niveau (immediate)

Scenario 2: Mixed Duration Plans

Level 1: Premium Annual ($99.99/year)
Level 2: Premium Monthly ($9.99/month)

• Monthly → Annual: Crossgrade (at renewal)
• Annual → Monthly: Downgrade (at renewal)

Scenario 3: Multi-Tier Multi-Duration

Level 1: Ultimate Annual ($199/year)
Level 2: Ultimate Monthly ($19.99/month)
Level 3: Premium Annual ($99/year)
Level 4: Premium Monthly ($9.99/month)
Level 5: Basic Annual ($49/year)
Level 6: Basic Monthly ($4.99/month)

This Configuration provides maximum flexibility while maintaining clear Mise à niveau/downgrade logic.

Dépannage

Subscription not appearing in group:

• Verify it’s assigned to the correct group
• Vérifier that it’s in at least “Ready to Soumettre” status
• Ensure product ID is correct

Wrong upgrade/downgrade behavior:

• Review level rankings (1 = highest)
• Verify subscription tiers make sense
• Vérifier that levels are set correctly

Products from different groups:

• Utilisateurs can subscribe to multiple groups simultaneously
• This is intentional - keep related products in same group

getActiveProducts showing multiple subscriptions:

• Vérifier if subscriptions are in different groups
• Verify Utilisateur isn’t subscribed via Family Sharing
• Review subscription status in Application Store Connect

Additional Resources

For more details, refer to the official Apple Documentation on subscription groups.