Crear grupo de suscripciones de iOS

Los grupos de suscripción son esenciales para organizar y gestionar múltiples niveles de suscripción en tu app de iOS. Entender cómo funcionan es clave para implementar funciones de upgrade, downgrade y crossgrade.

¿Qué es un grupo de suscripciones?

Un grupo de suscripción es un conjunto de suscripciones relacionadas entre las que los usuarios pueden elegir. Los usuarios solo pueden tener una suscripción activa por grupo a la vez. Al cambiar de suscripción, Apple gestiona la transición automáticamente.

Por qué importan los grupos de suscripciones

Los grupos de suscripción permiten:

• Precios por niveles: Ofrecer planes básicos, premium y ultimate
• Diferentes duraciones: Opciones mensuales, anuales y de por vida
• Lógica de upgrade/downgrade: Gestión automática de cambios en la suscripción
• Gestión simplificada: Agrupa suscripciones relacionadas

Niveles de suscripción

Dentro de un grupo, cada suscripción debe ordenarse de mayor valor (nivel 1) a menor valor. Este orden determina cómo se clasifican los cambios de suscripción:

Ejemplos de niveles

Nivel 1 (Mayor valor)

• Premium Anual ($99.99/año)
• Ultimate mensual ($19.99/mes)

Nivel 2 (Valor medio)

• Standard anual ($49.99/año)
• Premium mensual ($9.99/mes)

Nivel 3 (Valor más bajo)

• Basic anual ($29.99/año)
• Standard mensual ($4.99/mes)

Tipos de cambio de suscripción

Apple gestiona automáticamente tres tipos de cambios de suscripción según el ranking de niveles:

1. Actualizar

Cambiar a una de nivel superior suscripción (p. ej., nivel 2 → nivel 1).

Comportamiento:

• Se aplica inmediatamente
• El usuario recibe un reembolso prorrateado por el tiempo restante
• La nueva suscripción empieza de inmediato

Ejemplo:

// 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

Cambiar a una de nivel inferior suscripción (ej., nivel 1 → nivel 2).

Comportamiento:

• Entra en vigor en la próxima fecha de renovación
• El usuario mantiene la suscripción actual hasta que termine el periodo
• La nueva suscripción comienza automáticamente tras la expiración

Ejemplo:

// 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

Cambio a otra suscripción en el mismo nivel de tier.

El comportamiento depende de la duración:

Diferente duración → Funciona como un downgrade

• Se aplica en la próxima fecha de renovación
• Ejemplo: Premium Mensual (Nivel 1) → Premium Anual (Nivel 1)

Misma duración → Funciona como upgrade

• Se aplica de inmediato
• Ejemplo: Premium Mensual (Nivel 1) → Ultimate Mensual (Nivel 1)

Crear un grupo de suscripción

1. Ve a Subscriptions

   En App Store Connect, selecciona tu app y ve a Monetización > Suscripciones.

2. Crear grupo

   Haz clic + junto a “Subscription Groups” para crear un nuevo grupo.

3. Nombre del grupo

   Elige un nombre descriptivo que refleje las suscripciones que contiene:

   • “Acceso Premium”
   • “Planes de Cloud Storage”
   • “Funciones Pro”

4. Añadir suscripciones

   Tras crear el grupo, añade las suscripciones individuales. Cada suscripción tendrá un nivel de ranking.

5. Configurar niveles de ranking

   Ordena las suscripciones del mayor valor (1) al menor. Ten en cuenta:

   • Los planes anuales suelen tener mayor prioridad que los mensuales
   • Los niveles de mayor precio van por encima de los de menor precio
   • Ultimate/premium tiers rank highest

Uso en tu app

El plugin native-purchases gestiona automáticamente la lógica de los grupos de suscripción:

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);
});

Gestionar cambios de suscripción

Detectar el tipo de cambio

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();
  }
});

Comunicación con el usuario

Comunica siempre el comportamiento del cambio con claridad:

Para Upgrades:

“Tendrás acceso inmediato a las funciones Premium. Prorratearemos tu suscripción actual.”

Para Downgrades:

“Mantendrás el acceso Premium hasta el [renewal date] y luego cambiarás a Standard.”

Para Crossgrades:

“Tu plan cambiará a facturación anual en la próxima renovación el [date].”

Monitoreo del servidor

Usa las App Store Server Notifications v2 de Apple o tu propio backend de validación de recibos para reflejar los cambios de StoreKit en tu base de datos. Combina las notificaciones del servidor con el transactionUpdated listener so both client and backend stay in sync.

Buenas prácticas

Organización de grupos

• Mantén suscripciones relacionadas en el mismo grupo
• No mezcles funciones distintas (ej. almacenamiento y eliminación de anuncios)
• Crea grupos separados para diferentes conjuntos de funciones

Estrategia de ranking de niveles

• Planes anuales → Nivel superior al mensual (mismo tier)
• Tiers de mayor precio → Nivel superior
• Considera el valor, no solo el precio

Experiencia de usuario

• Mostrar la suscripción actual con claridad
• Mostrar todas las opciones disponibles del grupo
• Indicar qué cambios son inmediatos vs. al renovar
• Permitir cambiar de plan fácilmente

Pruebas

• Probar todos los escenarios de upgrade
• Probar todos los escenarios de downgrade
• Verificar el comportamiento de crossgrade
• Comprobar el disparo de webhooks

Escenarios comunes

Escenario 1: Planes mensuales de tres niveles

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

• Basic → Premium: Upgrade (inmediato)
• Premium → Ultimate: Upgrade (inmediato)
• Ultimate → Premium: Downgrade (al renovar)
• Basic → Ultimate: Upgrade (inmediato)

Escenario 2: Planes de duración mixta

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

• Mensual → Anual: Crossgrade (al renovar)
• Anual → Mensual: Downgrade (al renovar)

Escenario 3: varios niveles y varias duraciones

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)

Esta configuración ofrece máxima flexibilidad con una lógica clara de upgrade/downgrade.

Solución de problemas

La suscripción no aparece en el grupo:

• Verifica que esté asignada al grupo correcto
• Comprueba que tenga al menos el estado “Ready to Submit”
• Asegúrate de que el product ID sea correcto

Comportamiento de upgrade/downgrade incorrecto:

• Revisa el ranking de niveles (1 = más alto)
• Verifica que los niveles de suscripción tengan sentido
• Check that levels are set correctly

Productos de diferentes grupos:

• Los usuarios pueden suscribirse a varios grupos a la vez
• Esto es intencional: mantén productos relacionados en el mismo grupo

getActiveProducts muestra múltiples suscripciones:

• Comprueba si las suscripciones están en grupos distintos
• Verifica que el usuario no use Family Sharing
• Revisa el estado de la suscripción en App Store Connect

Recursos adicionales

Para más detalles, consulta la documentación oficial de Apple sobre grupos de suscripción.

Continúa desde Create iOS Subscription Group

Si estás usando Crear grupo de suscripciones de iOS para planificar la aprobación y distribución en la tienda, conéctalo con Uso de @capgo/native-purchases para la capacidad nativa al usar @capgo/native-purchases, @capgo/capacitor-in-app-review para el detalle de implementación en @capgo/capacitor-in-app-review, Usando @capgo/capacitor-in-app-review para la capacidad nativa en «Usando @capgo/capacitor-in-app-review», @capgo/capacitor-native-market para el detalle de implementación en @capgo/capacitor-native-market, y Usando @capgo/capacitor-native-market para la capacidad nativa en «Usando @capgo/capacitor-native-market.»