michangarrito/docs/01-epicas/MCH-018-planes-suscripciones.md

MCH-018: Planes y Suscripciones

Metadata

• Codigo: MCH-018
• Fase: 5 - Monetizacion
• Prioridad: P0
• Estado: Completado
• Fecha inicio: 2026-01-06
• Fecha fin: 2026-01-07

Descripcion

Sistema de planes de suscripcion para monetizar MiChangarrito: dos planes principales (Changarrito y Tiendita), facturacion mensual, y gestion de ciclos de pago.

Objetivos

1. Definir planes disponibles
2. Proceso de suscripcion
3. Facturacion recurrente
4. Gestion de ciclo de vida
5. Upgrade/downgrade de plan

Alcance

Incluido

• Plan Changarrito ($99/mes)
• Plan Tiendita ($199/mes)
• Trial de 14 dias
• Facturacion via Stripe
• Cancelacion y pausas
• Historial de facturacion

Excluido

• Planes anuales (fase posterior)
• Planes enterprise personalizados
• Facturacion fiscal mexicana (MCH-027)

Planes

Plan Changarrito - $99/mes

✓ App movil completa
✓ Punto de venta basico
✓ Hasta 500 productos
✓ 1 usuario
✓ 500 tokens IA/mes
✓ Soporte por WhatsApp
✗ WhatsApp Business propio
✗ Predicciones de inventario

Plan Tiendita - $199/mes

✓ Todo de Changarrito
✓ Productos ilimitados
✓ Hasta 5 usuarios
✓ 2,000 tokens IA/mes
✓ WhatsApp Business propio
✓ Predicciones de inventario
✓ Reportes avanzados
✓ Entregas a domicilio
✓ Soporte prioritario

Modelo de Datos

Tablas (schema: subscriptions)

plans

• id, name, code, price
• currency, interval (month/year)
• features (JSONB), token_quota
• max_products, max_users
• stripe_price_id, status

subscriptions

• id, tenant_id, plan_id
• status (trialing/active/past_due/cancelled)
• stripe_subscription_id
• current_period_start, current_period_end
• trial_end, cancelled_at

invoices

• id, subscription_id, amount
• status, stripe_invoice_id
• paid_at, pdf_url

Endpoints API

Metodo	Endpoint	Descripcion
GET	/subscriptions/plans	Listar planes
GET	/subscriptions/current	Suscripcion actual
POST	/subscriptions/subscribe	Suscribirse
POST	/subscriptions/cancel	Cancelar
POST	/subscriptions/resume	Reanudar
PUT	/subscriptions/change-plan	Cambiar plan
GET	/subscriptions/invoices	Historial facturas
POST	/subscriptions/webhook	Webhook Stripe

Flujos

Nueva Suscripcion

1. Usuario selecciona plan
2. Ingresa metodo de pago (Stripe)
3. Se crea suscripcion con trial
4. Usuario tiene acceso inmediato
5. Al terminar trial, se cobra automaticamente

Cancelacion

1. Usuario solicita cancelar
2. Confirmacion requerida
3. Suscripcion marcada para cancelar
4. Acceso hasta fin del periodo
5. Datos preservados 30 dias

Upgrade

1. Usuario en Changarrito
2. Solicita upgrade a Tiendita
3. Se calcula prorateo
4. Pago de diferencia
5. Features activadas inmediatamente

Estados de Suscripcion

trialing ──► active ──► past_due ──► cancelled
                │           │
                └───────────┴──► paused

Estado	Descripcion	Acceso
trialing	En periodo de prueba	Completo
active	Pagando normalmente	Completo
past_due	Pago fallido (grace period)	Limitado
cancelled	Cancelada	Sin acceso
paused	Pausada temporalmente	Sin acceso

Integracion Stripe

Subscription Billing

const subscription = await stripe.subscriptions.create({
  customer: customer.stripe_id,
  items: [{ price: plan.stripe_price_id }],
  trial_period_days: 14,
  payment_behavior: 'default_incomplete',
  expand: ['latest_invoice.payment_intent']
});

Webhooks Manejados

• customer.subscription.created
• customer.subscription.updated
• customer.subscription.deleted
• invoice.payment_succeeded
• invoice.payment_failed

Entregables

Entregable	Estado	Archivo
DDL subscriptions	Completado	10-subscriptions.sql
subscriptions.module	Completado	modules/subscriptions/
Stripe integration	Completado	providers/stripe.provider.ts
Plans UI	Pendiente	pages/Plans.tsx
Billing UI	Pendiente	pages/Billing.tsx

Dependencias

Depende de

• MCH-005 (Stripe integration base)
• MCH-002 (Auth)

Bloquea a

• MCH-019 (Tokens)
• MCH-020 (Pagos online)

Criterios de Aceptacion

• Planes se muestran correctamente
• Suscripcion se crea en Stripe
• Trial de 14 dias funciona
• Cobro recurrente funciona
• Cancelacion funciona
• Upgrade/downgrade funciona

Configuracion

// plans seed
[
  {
    name: 'Changarrito',
    code: 'changarrito',
    price: 99,
    currency: 'MXN',
    token_quota: 500,
    max_products: 500,
    max_users: 1,
    stripe_price_id: 'price_xxx'
  },
  {
    name: 'Tiendita',
    code: 'tiendita',
    price: 199,
    currency: 'MXN',
    token_quota: 2000,
    max_products: null, // unlimited
    max_users: 5,
    stripe_price_id: 'price_yyy'
  }
]

---

Ultima actualizacion: 2026-01-07