Diseño de un sistema de créditos por referidos para suscripciones SaaS

Qué es (y qué no es) un sistema de créditos por referidos

Un programa de créditos por referidos es una funcionalidad de facturación, no una función de pagos. La recompensa es crédito en la cuenta que reduce cargos futuros (o extiende tiempo). No es dinero enviado a un banco, no son tarjetas regalo y no es la promesa de que alguien "recibirá pago" más tarde.

Un buen sistema responde a una pregunta cada vez: "¿Por qué bajó la próxima factura de esta cuenta?" Si no puedes explicarlo en una o dos frases, llegarán tickets de soporte y disputas.

Un sistema de créditos por referidos tiene tres partes: alguien invita a un nuevo cliente, reglas claras deciden cuándo esa invitación cuenta (la conversión) y se ganan créditos que se aplican a facturas de suscripción futuras.

Lo que no es: pagos en efectivo, un descuento vago que cambia números sin registro, o un sistema de puntos que nunca se conecta a las facturas.

Varios equipos dependen de estos detalles. Los referenciadores quieren ver qué ganaron y cuándo aplicará. Los referidos quieren saber qué reciben y si afecta su plan. Soporte necesita resolver “mi crédito desapareció” rápido. Finanzas necesita totales que coincidan con las facturas y puedan auditarse.

Ejemplo: Sam refiere a Priya. Priya comienza un plan pago. Sam gana $20 en créditos que reducen la próxima factura de Sam hasta $20. Si la próxima factura de Sam es $12, los $8 restantes quedan como crédito para después, con un registro claro de su origen.

El éxito no es solo “más referidos”. Es facturación predecible y menos disputas. Sabes que funciona cuando los saldos de crédito son fáciles de explicar, las facturas concuerdan con el libro mayor y soporte puede responder sin adivinar o hacer correcciones manuales.

Reglas que hay que decidir antes de construir nada

Un programa de referidos suena simple hasta que llegan los primeros tickets: “¿Por qué no recibí mis créditos?” La mayor parte del trabajo es política, no código.

Empieza por el disparador. “Invitación enviada” es demasiado pronto. “Registro” es fácil de abusar con cuentas desechables. Un punto intermedio común es una “conversión calificada”: email verificado más la primera factura pagada, o el primer pago exitoso tras una prueba. Elige un disparador y mantenlo consistente para que tu libro mayor permanezca limpio.

Luego, fija el valor y los límites. Los créditos deben sentirse reales, pero no convertirse en una máquina de descuentos ilimitados. Decide si das una cantidad fija (por ejemplo, $20 en créditos) o un porcentaje de una factura, y limita de forma que puedas explicarlo en una sola frase.

Las decisiones que previenen la mayoría de confusiones son:

• Qué evento califica (primera factura pagada, primera renovación, etc.)
• Cuánto crédito se otorga (fijo vs porcentaje, y si varía por plan)
• Límites (por referido, por mes y de por vida)
• Qué planes y tipos de oferta cuentan
• Si los créditos expiran

Las reglas de elegibilidad importan más de lo que la gente espera. Si solo cuentan los planes pagos, dilo. Si algunas regiones están excluidas (impuestos, cumplimiento, promos), dilo. Si los planes anuales califican pero los mensuales no, dilo. Para una plataforma como Koder.ai con múltiples niveles, decide desde el inicio si las mejoras de free a pro califican y si los contratos enterprise se manejan manualmente.

Escribe el texto hacia el usuario antes de lanzar. Si no puedes explicar cada regla en dos frases cortas, los usuarios la malinterpretarán. Mantén el tono firme pero calmado: “Podemos retener créditos por actividad sospechosa” es más claro (y menos hostil) que una larga lista de amenazas.

Cómo rastrear referidos desde la invitación hasta la conversión calificada

Elige un identificador principal y trata todo lo demás como evidencia secundaria. Las opciones más limpias son un token de enlace de referidos (fácil de compartir), un código corto (fácil de teclear) y una invitación enviada a un correo específico (mejor para invitaciones directas). Elige uno como fuente de verdad para que la atribución sea predecible.

Captura ese identificador lo antes posible y llévalo durante todo el viaje. Un token de enlace suele capturarse en la landing, guardarse en almacenamiento de primer partido y luego reenviarse al registrarse. Para móvil, pásalo por el flujo de instalación de la app cuando puedas, pero asume que a veces se perderá.

Rastrea un pequeño conjunto de eventos que coincidan con tus reglas de negocio. Si tu objetivo es “¿se convirtió en cliente de pago?” (no solo “¿hicieron clic?”), un conjunto mínimo es suficiente:

• referral_click (token visto)
• account_signup (nuevo usuario creado)
• account_verified (email/teléfono verificado)
• first_paid_invoice (primer pago exitoso)
• qualification_locked (conversión aceptada y ya no cambia)

Los cambios de dispositivo y las cookies bloqueadas son normales. Para manejarlos sin rastreos intrusivos, añade un paso de reclamación durante el registro: si un usuario llega con un token, adjúntalo a la nueva cuenta; si no, permite introducir un código corto una vez durante el onboarding. Si hay ambos, conserva el valor capturado primero como primario y guarda el otro como evidencia secundaria.

Finalmente, mantiene una línea de tiempo simple por referido que soporte pueda leer en un minuto: referenciador, cuenta referida (cuando se conozca), estado actual y el último evento significativo con timestamps. Cuando alguien pregunte “¿por qué no recibí créditos?” puedes responder con hechos como “hubo registro, pero nunca se produjo la primera factura pagada”, en lugar de adivinar.

Modelo de datos que siga legible y fácil de depurar

Los programas de referidos suelen romperse cuando el modelo de datos es vago. Soporte pregunta “¿quién refirió a quién?” Facturación pregunta “¿ya se emitió el crédito?” Si no puedes responder sin escarbar en logs, el modelo necesita ser más estricto.

Guarda la relación de referido como un registro de primera clase, no como una suposición derivada de clicks.

Registros básicos a guardar

Una configuración simple y depurable se ve así:

• referrals: id, referrer_user_id, referred_user_id, created_at, source (invite link, coupon, manual), status, status_updated_at
• referral_attribution (opcional): referral_id, invite_code_id o campaign_id, first_seen_ip_hash, first_seen_user_agent_hash
• workspaces (si tienes equipos): workspace_id, owner_user_id, created_at
• workspace_members: workspace_id, user_id, role, joined_at

Mantén la tabla de referrals pequeña. Evita recopilar datos que puedas lamentar más tarde (IP cruda, user agent completo, nombres); guárdalos solo como hashes de corta vida con una política de retención clara.

Haz los estados explícitos y mutuamente excluyentes: pending (registrado, aún no elegible), qualified (cumplió reglas), credited (crédito emitido), rejected (falló comprobaciones), reversed (crédito recuperado tras reembolso/chargeback).

Reglas que evitan el doble conteo

Decide precedencia una vez y aplícala en la base de datos para que la app no pueda acreditar dos veces por accidente. Como mínimo:

• Solo un referenciador por cuenta referida (único sobre referred_user_id)
• Solo una referencia puede llegar a credited por cuenta referida
• Si ocurren múltiples toques, elige first-touch o last-touch y guarda el referral_id elegido

Si soportas equipos, decide si la referencia se ata al registro personal o a la creación del workspace. No intentes hacer ambas cosas. Un enfoque viable es vincular la referencia a la cuenta de usuario, mientras las comprobaciones de elegibilidad miran si ese usuario (o su workspace) se convirtió en suscriptor de pago.

Fundamentos del libro mayor de créditos: preciso, auditable y explicable

Si quieres menos errores de facturación y menos tickets, usa un libro mayor, no un único campo de “saldo de créditos”. Un número de saldo puede sobrescribirse, redondearse o actualizarse dos veces. Un libro mayor es un historial de entradas que siempre puedes sumar.

Mantén los tipos de entrada limitados y claros: earn (otorgar), spend (aplicar a factura), expire, reversal (clawback) y ajuste manual (con nota y aprobador).

Cada entrada debe ser legible por ingenieros y soporte. Guarda campos consistentes: amount, credit type (no “USD” si los créditos no son efectivo), reason text, source event (como referral_signup_qualified), source IDs (usuario, usuario referido, suscripción o factura), timestamps y created_by (sistema o admin).

La idempotencia importa más de lo que la gente espera. El mismo webhook o job en background puede ejecutarse dos veces. Requiere una clave de idempotencia única por evento origen para poder reintentar sin otorgar créditos duplicados.

Hazlo explicable al usuario. Cuando alguien pregunte “¿por qué recibí 20 créditos?” deberías poder mostrar qué referencia lo desencadenó, cuándo se publicó, si expira y si hubo una reversión posterior. Si un amigo mejora de plan, añades una entrada de earn ligada a ese evento de upgrade. Si el pago se reembolsa, publicas una entrada de reversal ligada al evento de reembolso.

Evitar auto-referencias y abusos comunes sin ser drástico

Asume que la mayoría de la gente es honesta y unos pocos intentarán trucos obvios. El objetivo es detener el abuso fácil, mantener reglas claras y evitar bloquear a clientes reales que comparten Wi‑Fi o una tarjeta familiar.

Bloqueos contra auto-referencias con reglas simples y explicables

Empieza con bloqueos contundentes que puedas justificar. No otorgues créditos cuando el referenciador y la cuenta referida sean claramente la misma persona, como el mismo user ID, el mismo email verificado o la misma huella de método de pago. Las reglas por dominio de email pueden ayudar, pero mantenlas estrechas. Bloquear todo un dominio puede perjudicar a equipos legítimos.

Después añade detección ligera para bucles y registros masivos. No necesitas scoring antifraude perfecto desde el día uno. Unas pocas señales fuertes capturan la mayoría del abuso: muchos registros desde el mismo dispositivo en poco tiempo, uso repetido desde la misma IP en minutos, la misma tarjeta usada en varias cuentas “nuevas”, muchas cuentas que nunca verifican email o patrones rápidos de cancelar y volver a suscribirse tras aplicar créditos.

Requiere una acción calificadora antes de que los créditos sean utilizables (por ejemplo: email verificado más factura pagada, opcionalmente tras un corto período de gracia). Eso detiene bots y el churn de la capa gratuita que generan ruido.

Frenar el abuso sin castigar usuarios normales

Añade límites de velocidad y cooldowns alrededor de enlaces de referidos y redenciones, pero mantenlos ocultos hasta que hagan falta. Si un enlace se usa 20 veces en una hora desde la misma red, pausa recompensas y márcalo.

Cuando intervengas, mantén la experiencia calmada. Marca créditos como pendientes hasta que el pago se confirme, muestra una razón simple cuando las recompensas se retrasen (evita culpar), ofrece una vía clara para contactar soporte y deriva casos límite a revisión manual en lugar de baneo automático.

Ejemplo: un equipo startup comparte la misma IP de oficina. Tres compañeros se registran con la misma referencia el mismo día. Con verificación + pago calificante y un cooldown básico, aún así ganan créditos tras pagarse las facturas, mientras que ráfagas tipo bot se retienen para revisión.

Casos reales complicados: reembolsos, reversiones y cambios de cuenta

Los programas de referidos parecen simples hasta que el dinero se mueve de forma “incorrecta”: un reembolso, un chargeback, una factura que se anula o una cuenta que cambia de propietario. Si diseñas estos casos por adelantado evitas usuarios enfadados y hilos largos en soporte.

Cuándo revertir créditos (y cómo)

Trata los créditos como algo que ganas basado en un resultado pagado, no solo por un registro. Luego define una política de reversión ligada a eventos de facturación.

Un conjunto de reglas que soporte pueda explicar:

• Si la factura pagada original se reembolsa por completo o se hace chargeback, revierte el crédito otorgado por ella.
• Si una factura se cancela antes de capturar el pago, no otorgues el crédito.
• Si los créditos se otorgaron antes (por ejemplo en “factura pagada”), las reversiones deben ser automáticas y dejar rastro claro.

Los reembolsos parciales son donde los equipos se atascan. Elige un enfoque y sé consistente: reversión proporcional (revierte el 30 % del crédito por un reembolso del 30 %) o reversión completa (cualquier reembolso revierte todo el crédito). La proporcional es más justa pero más difícil de explicar y probar. La completa es más simple pero puede parecer dura.

Las transiciones de prueba a pago también deben ser explícitas. Un enfoque común es mantener los créditos pendientes durante la trial y bloquearlos solo tras la primera factura pagada exitosa (y opcionalmente después de un breve período de gracia).

Fusiones de cuentas y cambios de propiedad

La gente cambia de emails, fusiona cuentas o pasa de uso personal a workspace. Decide qué sigue a la persona y qué sigue a la cuenta pagadora. Si un workspace es el suscriptor, los créditos suelen pertenecer a ese workspace, no a un miembro que pueda irse.

Si soportas merges de cuenta o transferencias de propiedad, registra un evento de ajuste en lugar de reescribir la historia. Cada reversión o corrección manual debe incluir una nota amigable para soporte como “Chargeback en factura 10482” o “Transferencia de propietario de workspace aprobada por soporte”. En plataformas como Koder.ai donde los créditos se aplican a suscripciones, esas notas permiten responder “¿por qué cambiaron mis créditos?” con una sola búsqueda.

Aplicar créditos a suscripciones de forma limpia

La parte más difícil no es rastrear referidos. Es hacer que los créditos se comporten igual en renovaciones, upgrades, downgrades y con impuestos.

Primero, decide dónde se pueden usar los créditos. Algunos equipos aplican créditos solo a la siguiente factura nueva. Otros permiten que cubran cualquier factura abierta (no pagada). Elige una regla y muéstrala en la UI para que la gente no se sorprenda.

Luego, fija el orden de operaciones. Un enfoque predecible es: calcular cargos de suscripción (incluida la prorrata), aplicar descuentos, calcular impuestos y luego aplicar créditos al final. Aplicar créditos al final mantiene la lógica de impuestos consistente y evita discusiones sobre si en todas las jurisdicciones los créditos reducen la base imponible. Si tus reglas legales/fiscales requieren otro orden, documéntalo y escribe tests.

La prorrata es donde aparecen los bugs de facturación. Si alguien hace upgrade a mitad del ciclo, crea una línea de prorrata (cargo o crédito) y trátala como cualquier otra línea. Luego aplica los créditos al total de la factura, no a líneas individuales.

Mantén reglas de factura estrictas:

• Los créditos reducen lo que el cliente debe, pero nunca por debajo de $0 a deber.
• El crédito no usado queda disponible para facturas futuras.
• Aplica créditos en un orden fijo (más antiguos primero) para que los resultados sean repetibles.
• Si una factura se anula o reembolsa, revierte solo los créditos que realmente se consumieron en esa factura.

Ejemplo: un usuario hace upgrade a mitad de mes y recibe un cargo de prorrata de $12. Su subtotal de factura queda en $32 después de descuentos e impuestos. Si tiene $50 en créditos por referidos, aplicas $32, dejas la factura en $0 y mantienes $18 para la próxima renovación.

Plan de implementación paso a paso (MVP a v1)

Trata el programa de referidos como una pequeña funcionalidad de facturación, no como un widget de marketing. La meta es consistencia aburrida: cada crédito tiene una razón, una marca de tiempo y un camino claro hacia la siguiente factura.

MVP (enviar en días, no semanas)

Elige un evento de conversión y una regla de crédito. Por ejemplo: una referencia califica solo cuando el usuario invitado se convierte en suscriptor de pago y su primer pago se confirma.

Construye el MVP alrededor de un flujo de extremo a extremo: captura un token o código en el signup, ejecuta la calificación cuando el pago tenga éxito (no cuando el usuario ingresa la tarjeta), escribe una entrada de libro mayor con una clave de idempotencia única y aplica créditos a la siguiente factura en un orden predecible.

Decide la fuente de verdad temprano. O tu proveedor de facturación es la fuente de verdad y tu app la refleja, o tu libro mayor interno es la fuente de verdad y facturación solo recibe “aplicar X créditos en esta factura”. Mezclar ambas suele crear tickets de “mis créditos desaparecieron”.

v1 (hacerlo soportable)

Añade herramientas de administración antes de añadir más reglas de referidos. Soporte necesita buscar por usuario, código de referido y factura, y ver una línea de tiempo de: invitación, registro, calificación, créditos concedidos, créditos gastados y reversiones. Incluye ajustes manuales y siempre exige una nota corta.

Luego añade la UX de usuario: una página de referidos, una línea de estado por invitación (pending, qualified, credited) y un historial de créditos que coincida con las facturas.

Finalmente, añade monitorización: alerta por picos repentinos en referidos, altas tasas de reversión (reembolsos o chargebacks) y patrones inusuales como muchas cuentas compartiendo el mismo dispositivo o método de pago. Eso mantiene los controles de abuso firmes sin castigar a usuarios normales.

Ejemplo: si alguien comparte un referido de Koder.ai con su equipo, debería ver créditos aparecer solo después de la primera suscripción pagada exitosa, y esos créditos deberían reducir la siguiente renovación automáticamente, no como un cupón manual.

Errores comunes que generan bugs de facturación y carga de soporte

La mayoría de los programas de referidos fallan en facturación, no en marketing. La forma más rápida de crear tickets es hacer que los créditos sean impredecibles: los usuarios no pueden saber por qué los recibieron, cuándo aplicarán o por qué una factura luce diferente.

Una trampa común es construir antes de tener las reglas claras. Si “referido calificado” es vago (trial iniciada, primer pago, plan pagado mantenido 30 días), acabarás negociando créditos caso por caso y emitiendo reembolsos para dejar a la gente a gusto.

Otro problema frecuente es usar un único campo mutable de “saldo de créditos”. Parece simple hasta que tienes reintentos, reembolsos, cambios de plan o ajustes manuales. Entonces el número se desvía y no puedes explicar cómo llegó ahí.

La idempotencia también se pasa por alto. Los proveedores de pago reintentan webhooks, los workers reintentan jobs y los usuarios hacen doble clic. Si la acción “otorgar crédito” no es idempotente, crearás créditos duplicados y solo lo notarás cuando los ingresos no cuadren.

La matemática de créditos también puede estar mal aun cuando los totales parezcan correctos. Aplicar créditos antes de impuestos, o ignorar reglas de prorrata, puede producir facturas que no coinciden con lo que espera el sistema de pagos. Eso lleva a recibos desajustados, pagos fallidos y reconciliaciones dolorosas.

Los controles antifraude también pueden ser demasiado estrictos. Bloquear por IP, dispositivo o dominio sin una vía de revisión detiene referidos reales (compañeros de cuarto, colegas, equipos en la misma red) y afecta el crecimiento de forma silenciosa.

Cinco señales de alarma a vigilar:

• Las reglas de calificación existen solo en código y no son visibles en vistas de admin/soporte.
• Los créditos no tienen una clave de evento única (invite_id, conversion_id) para prevenir duplicados.
• El “saldo” se almacena sobrescribiendo un campo en lugar de añadiendo entradas al libro mayor.
• Las facturas aplican créditos en un orden distinto al que espera tu proveedor de facturación (impuestos, prorrata, descuentos).
• La prevención de fraude no tiene camino de apelación ni anulación manual.

Ejemplo: un usuario de Koder.ai en Pro hace upgrade a mitad de mes, gana un crédito por referidos y luego hace downgrade. Si tu sistema usa un campo de saldo único y aplica créditos antes de la prorrata, la próxima factura puede verse mal incluso si el total está cercano. Un libro mayor más un orden fijo de aplicación evita que eso se convierta en un largo hilo de soporte.

Lista rápida, ejemplo simple y siguientes pasos

Antes de lanzar, ejecuta unas comprobaciones que atrapan la mayoría de problemas de facturación y soporte temprano.

• Un referenciador por cuenta: una vez atribuida la cuenta, no la cambies en silencio.
• Calificación clara: define el evento exacto que gana el crédito (por ejemplo: primera factura pagada con éxito y no reembolsada).
• Libro mayor, no “saldo”: almacena cada crédito y débito como entradas.
• Existen reversiones: reembolsos, chargebacks y trials canceladas generan entradas reversoras.
• Ajustes de admin registrados: concesiones y eliminaciones manuales se ven como entradas normales del libro mayor con una razón.

Ejemplo: Maya invita a Noah. Noah se registra desde la invitación de Maya, inicia una trial y luego hace upgrade a Pro y paga $30. Tu sistema marca esa factura como calificada y crea una entrada de crédito para Maya (por ejemplo: $10 de crédito de suscripción).

En la siguiente renovación de Maya, su subtotal de factura es $30. Tu paso de facturación aplica hasta $10 de sus créditos disponibles, así que la factura muestra subtotal $30, -$10 crédito y $20 a pagar. El libro mayor de Maya tiene una entrada por ganar (+$10) y otra por gastar (-$10 aplicado a la factura #1234).

Si Noah luego solicita un reembolso de ese primer pago, el sistema añade una entrada de reversal que elimina el crédito ganado por Maya (o publica un débito coincidente). Si ya se usó algún crédito, la siguiente factura cobra la diferencia en lugar de reescribir la historia.

Dos siguientes pasos que mantienen el impulso sin romper la confianza:

1. Prototipa el flujo completo en un documento de planificación corto: atribución, calificación, entradas de libro mayor, aplicación a facturas y reversiones.

2. Prueba escenarios fijos en un sandbox: trial a pago, reembolso después de usar crédito, upgrade y downgrade a mitad de ciclo y un ajuste manual de admin.

Si quieres moverte rápido sin perder control de la lógica de facturación, Koder.ai incluye Planning Mode más snapshots y rollback, que pueden ayudarte a iterar el flujo de referidos hasta que la matemática de las facturas sea consistente. Puedes hacer todo el proceso dentro de la plataforma en koder.ai y luego exportar el código cuando estés listo.