El ciclo de vida en eventos
| Momento del ciclo de vida | Evento | Origen | Propiedades |
|---|---|---|---|
| Cuenta creada | sign_up | navegador (híbrido) | method |
| Trial iniciado | start_trial | servidor (webhook de facturación) | plan, trial_days |
| Primera suscripción de pago | subscribe | servidor (webhook de facturación) | plan, interval, value, currency, transaction_id |
| Factura de renovación pagada | purchase con props.renewal: true | servidor | value, currency, transaction_id |
| Upgrade / expansión | purchase con props.expansion: true | servidor | value delta |
| Cancelación o reembolso | refund | servidor | transaction_id original, value negativo |
| Inicio de sesión | login | navegador | — |
El sistema de facturación es la autoridad para todo lo que implica dinero. El navegador puede mostrar una página de «suscripción confirmada», pero el evento que llega a las plataformas publicitarias sale del webhook, con los ID del sistema de facturación.
Por qué las renovaciones no deben ser subscribe
Las plataformas publicitarias optimizan hacia la conversión que les envías. Si cada renovación mensual llega como una suscripción nueva con valor, la plataforma aprende que los clientes existentes convierten bien y puja para volver a alcanzarlos. Mantén el evento de adquisición (subscribe, una vez por cliente) separado de la retención (purchase con el flag de renovación) y asigna solo el evento de adquisición a las acciones de conversión publicitarias. Las renovaciones siguen fluyendo hacia la analítica y hacia tus propios informes.
Valores para las plataformas publicitarias
subscribe: el importe de la primera factura es defendible y sencillo. Enviar una estimación del valor de vida del cliente solo está permitido como constante documentada por plan en el mapeo del destino, visible en el registro de auditoría; nunca como una conjetura por usuario.start_trial: sin valor, o un valor esperado documentado por plan.- Expansión: el delta, no el nuevo total.
refund: valor negativo del importe reembolsado; GA4 procesa los reembolsos por ID de transacción, Google Ads mediante ajustes de conversiones y la mayoría de las demás plataformas lo ignoran: el conector aplica lo que admite cada proveedor.
Identidad entre dispositivos
Un cliente SaaS se registra en el escritorio, paga desde el móvil e inicia sesión en todas partes. Llama a identify con tu ID de usuario y, bajo consentimiento de marketing, con el correo electrónico con hash; los eventos de servidor llevan el mismo ID de usuario y el mismo hash. Eso es lo que permite a las plataformas asociar un subscribe server-side con el clic en el anuncio que ocurrió días antes en otro dispositivo, dentro de sus ventanas.
Trials y consentimiento
El webhook de facturación lleva el estado del consentimiento que tu sistema registró en el alta, junto con el ID de usuario. El router aplica ese estado: un usuario que rechazó el marketing al registrarse solo produce eventos de analítica, y un webhook sin información de consentimiento no llega a ningún destino publicitario. No vuelvas a derivar el consentimiento del hecho de que alguien se haya convertido en cliente; ser cliente no es consentir la medición publicitaria.
Deduplicación frente a los reintentos de facturación
Los sistemas de facturación reintentan los webhooks. Usa el ID de factura o de suscripción como transaction_id; la etapa de ingesta marca un segundo subscribe o purchase con el mismo ID de transacción como conversión duplicada, y las plataformas que deduplican por ID de pedido fusionan lo que haya conseguido pasar.
Informes que se mantienen honestos
- Adquisición: número y valor de
subscribepor campaña, desde las plataformas publicitarias y desde tus propios eventos. - Conversión del trial:
start_trial→subscribepor plan, solo desde tus propios eventos. - Ingresos netos:
purchase(todos los flags) menosrefund, desde facturación, conciliados cada mes con los eventos.
Si alguna vez esas tres cifras discrepan de los informes del propio sistema de facturación, el desglose por origen en la página de eventos muestra qué vía está perdiendo qué.