Diseño de sistema de créditos por referidos para SaaS: rastrea referidos, previene abusos y aplica créditos a suscripciones con reglas claras y un libro mayor auditable.
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.
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:
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.
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.
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.
Una configuración simple y depurable se ve así:
id, referrer_user_id, referred_user_id, created_at, source (invite link, coupon, manual), status, status_updated_atreferral_id, invite_code_id o campaign_id, first_seen_ip_hash, first_seen_user_agent_hashworkspace_id, owner_user_id, created_atworkspace_id, user_id, role, joined_atManté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).
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:
referred_user_id)credited por cuenta referidareferral_id elegidoSi 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.
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.
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.
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.
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.
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.
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:
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).
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.
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:
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.
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.
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”.
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.
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:
invite_id, conversion_id) para prevenir duplicados.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.
Antes de lanzar, ejecuta unas comprobaciones que atrapan la mayoría de problemas de facturación y soporte temprano.
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:
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.
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.
Los créditos por referidos reducen lo que debes en facturas futuras (o extienden el tiempo de tu suscripción).
Son no dinero transferido a una cuenta bancaria, no tarjetas regalo y no una promesa de pago posterior. Piénsalos como crédito de tienda que aparece en la facturación.
Un valor habitual por defecto es: la referencia se califica después de que el usuario referido completa una primera factura pagada con éxito (a menudo tras la verificación del correo electrónico y, a veces, después de un breve período de gracia).
Evita calificar solo por “invitación enviada” o por “registro”, porque son fáciles de manipular y difíciles de defender en disputas.
Usa una fuente principal de verdad, típicamente un token de enlace de referidos o un código corto.
La práctica recomendada es:
Usa estados explícitos y mutuamente excluyentes para que soporte pueda responder rápido:
pending: el registro existe, aún no es elegiblequalified: cumplió las reglas (p. ej., primera factura pagada)Un solo campo de “saldo” se sobrescribe, se reintenta o se actualiza doble y termina siendo imposible de auditar.
Un libro mayor es una lista de entradas que siempre puedes sumar:
Eso hace la facturación explicable y fácil de depurar.
Haz la acción de “otorgar crédito” idempotente usando una clave única por evento origen (por ejemplo, el ID de la primera factura pagada).
Si el mismo webhook o job se ejecuta dos veces, la segunda ejecución no debe hacer nada en lugar de emitir créditos duplicados.
Comienza con bloqueos simples y justificables:
Luego añade controles ligeros sin castigar a usuarios legítimos:
Define una política de reversión ligada a eventos de facturación:
Para reembolsos parciales, elige una regla y apégate a ella:
Un orden predecible por defecto es:
Reglas que reducen confusión:
Un MVP mínimo pero que no genere caos en soporte:
Después añade UI y herramientas de admin antes de introducir niveles de recompensa complejos.
creditedrejected: fallaron las comprobaciones o es inelegiblereversed: crédito revertido tras reembolso/chargebackGuarda un sello de tiempo para el último cambio de estado.