Migrar sistemas de facturación se sitúa en el cruce entre lo crítico y lo arriesgado. Los errores pueden derivar en cargos duplicados, pérdida de registros de suscripciones o informes de ingresos rotos: preocupaciones que mantienen tensos a los equipos de finanzas y a los ingenieros revisando hojas de cálculo a horas raras.
El Migration Toolkit de Stripe Billing ofrece una solución no-code desde el dashboard. En lugar de scripts a medida o herramientas vía API, los equipos suben un CSV con sus suscripciones existentes y se crean en Stripe replicando la configuración actual.
Sin embargo, hay algunos detalles de implementación que requieren atención cuidadosa para evitar dobles facturaciones accidentales.
Requisitos previos: clientes y precios deben existir ya
Antes de migrar suscripciones, los clientes deben existir en Stripe con métodos de pago válidos asociados. El Migration Toolkit crea suscripciones, no registros de cliente.
Esto suele ocurrir por dos vías:
- Clientes ya en Stripe: los equipos que ya usan Stripe para pagos pero no para suscripciones probablemente tengan a los clientes presentes.
- Importación de datos PAN: Stripe puede importar tokens de métodos de pago desde procesadores anteriores mediante un proceso aparte que se inicia con antelación.
Cada fila del CSV referencia un customer ID que debe existir; los IDs ausentes provocan errores de validación. Del mismo modo, productos y precios deben estar definidos previamente.
Para empezar: vaya a Subscriptions, seleccione la pestaña Migrations y pulse "+ Start new migration".
El formato del CSV
Tras iniciar una nueva migración, un asistente solicita los detalles del tipo de migración. Stripe ofrece plantillas CSV para los escenarios habituales:
- Basic: suscripciones estándar con cantidad, impuestos, descuentos y trials.
- Multi-price items: suscripciones con varios productos.
- Ad-hoc pricing: precios a medida aplicados a productos existentes.
Los campos más críticos son:
| Campo | Obligatorio | Descripción |
|---|---|---|
customer | Sí | El customer ID de Stripe (debe existir ya) |
price o items.0.price | Sí | El price ID de Stripe para la suscripción |
start_date | Sí | Cuándo se activa la suscripción en Stripe |
backdate_start_date | No | Para reflejar el histórico de la suscripción |
proration_behavior | No | Controla si se generan cargos prorrateados |
billing_cycle_anchor | No | Determina la siguiente fecha de facturación |
La mayoría de las complicaciones en una migración vienen de cómo interactúan estos campos, en particular las fechas y las opciones de prorrateo.
El requisito clave de tiempos
El campo start_date determina cuándo se activan las suscripciones en Stripe. Stripe impone un tiempo mínimo entre la subida y la activación:
- Live mode: aproximadamente 24 horas.
- Test mode: normalmente más corto, alrededor de una hora.
Esa ventana aporta seguridad. Entre la subida y la activación, revise las suscripciones importadas en el dashboard. Verifique que precios, cantidades y asignaciones de cliente son correctos. Si aparecen problemas, cancele la migración entera antes de que se procesen cargos.
Fijar start_date bastante en el futuro da más tiempo de revisión. Configurarlo para acelerar la activación deja muy poco margen de reacción si surgen problemas. Rara vez tiene sentido acelerar este proceso, así que conceda periodos de revisión holgados.
Validación primero, revisión después
Al subir el CSV, Stripe valida el archivo entero antes de crear ninguna suscripción. Este proceso detecta campos ausentes o mal formados, customer IDs o price IDs no válidos, fechas de inicio demasiado próximas y combinaciones de campos no válidas.
Stripe muestra todos los errores de validación a la vez en lugar de fallar fila a fila, lo que permite corregirlos en una única pasada. Cuando hay errores, Stripe ofrece un CSV descargable que explica los fallos línea por línea para cada entrada.
Tras corregir los errores, suba el CSV actualizado a la misma migración. Una sutileza de la UI: pulsar "Start again" sube el CSV al intento actual, mientras que "Fix errors" sugiere crear una migración nueva. En general, usar "Start again" mantiene el histórico de la migración más limpio dentro de un mismo intento.
Cuando la validación tiene éxito, las suscripciones se crean en estado scheduled: existen en Stripe pero aún no están activas. El tiempo de validación depende del número de registros; las migraciones de prueba con menos de 100 suscripciones suelen validarse al instante.
Tras una validación correcta aparece un botón "View subscription schedules" que enlaza con la lista de suscripciones programadas. Antes de que se activen, revise las suscripciones en el dashboard. Cancele las que no se vean correctas, ya sea individualmente o por lotes si la fecha de inicio está lejos.
Backdating: la fuente de confusión más habitual
Si un cliente se suscribió originalmente en enero de 2023 y la migración ocurre en 2026, lo deseable es reflejar ese histórico en Stripe. Aquí entra backdate_start_date, y es el campo que más confusión genera, especialmente al ponerse en relación con start_date.
La distinción clave:
start_date- cuándo pasa la suscripción a estar activa en Stripe y comienza la facturación. Debe estar en el futuro.backdate_start_date- la fecha histórica registrada como inicio original de la suscripción. Puede estar en el pasado.
customer,items.0.price,start_date,backdate_start_date
cus_ABC123,price_XYZ789,1705753518,1658179441La suscripción se activa el 15 de febrero de 2026, pero Stripe registra al cliente como suscrito desde enero de 2023. Esto afecta a informes, analítica y a la visibilidad en el dashboard del cliente.
No fije start_date a una fecha pasada: Stripe lo rechazará en la validación.
Prorrateo: la zona de peligro
Aquí es donde más fallan las migraciones, lo que se traduce en cargos inesperados al cliente.
Por defecto, proration_behavior en Stripe está en create_prorations. Si Stripe detecta un desajuste entre el billing cycle anchor y la fecha de inicio, genera facturas prorrateadas. Durante una migración, eso suele significar facturar al cliente otra vez por periodos que ya pagó en otro sitio.
En casi todos los escenarios de migración hay que desactivarlo de forma explícita:
customer,items.0.price,start_date,backdate_start_date,proration_behavior
cus_ABC123,price_XYZ789,1705753518,1658179441,nonePoner proration_behavior en none equivale a decir: "este cliente está pagado hasta su próxima fecha de facturación; arranca con la facturación normal a partir de ahí". Si solo recordamos un punto de este artículo, que sea este.
Billing cycle anchors: por qué importan
El billing_cycle_anchor determina cuándo se generan las facturas futuras. Si no encaja con las fechas actuales de facturación, Stripe puede "corregir" el ciclo, disparando prorrateos o facturas iniciales confusas.
Durante una migración, el objetivo suele ser replicar la cadencia de facturación existente con precisión, asegurando que el cliente no perciba cambios en el comportamiento de facturación tras la migración.
Por ejemplo, con una suscripción en la que el cliente se dio de alta el 1 de enero de 2026 y debe facturarse el día 1 de cada mes, pero la migración ocurre el 10 de febrero:
| Campo | Detalle |
|---|---|
start_date | Timestamp del 10 de febrero |
backdate_start_date | Timestamp del 1 de enero de 2026 |
billing_cycle_anchor | Timestamp del 1 de marzo de 2026 |
proration_behavior | none |
Al inspeccionar este schedule en el dashboard, la primera fase comienza el 10 de febrero y el siguiente evento de facturación es el 1 de marzo, evitando la doble facturación.
Un flujo de migración típico
- Exportar del sistema actual: referencias de cliente, fechas originales de inicio, planes, cantidades.
- Asegurar la presencia de los clientes en Stripe: ya existentes o vía importación PAN.
- Mapear los datos con cuidado: casar clientes con sus IDs en Stripe y planes con price IDs.
- Fijar fechas con criterio:
start_datecon margen,backdate_start_datereflejando el inicio original ybilling_cycle_anchoralineado con la facturación existente. - Desactivar el prorrateo: ponga
proration_behaviorennonesalvo que quiera explícitamente generar cargos. - Subir y validar: resuelva todos los errores antes de continuar.
- Revisar en el dashboard: haga una revisión por muestreo de las suscripciones mientras siguen programadas.
- Vigilar la activación: observe el primer ciclo de facturación buscando fallos o facturas inesperadas.
Errores habituales que evitar
- Fijar
start_datedemasiado pronto: dese aire. No hay ventaja en acelerar este proceso. - Olvidar desactivar el prorrateo: este descuido por sí solo provoca la mayoría de los cargos accidentales.
- Confundir
start_dateybackdate_start_date: uno marca el momento de la facturación, el otro el histórico. - Métodos de pago ausentes: las suscripciones pueden existir sin ellos, pero el cobro de las facturas fallará.
- Erratas en los price IDs: incluso un solo carácter equivocado provoca el fallo de la fila.
¿Merece la pena usar el Migration Toolkit?
Para volúmenes mínimos de suscripciones - unas pocas docenas a lo sumo - la creación manual o las llamadas a la API pueden ser igual de eficientes.
Para volúmenes mayores, el Migration Toolkit ahorra mucho tiempo. Fender, por ejemplo, "migró 70 000 suscriptores en pocas horas" usando esta solución. La sola fase de validación previa, que identifica todos los problemas en lugar de descubrirlos llamada a llamada por API, justifica la curva de aprendizaje.
El éxito depende de entender los campos críticos - start_date, backdate_start_date, billing_cycle_anchor y proration_behavior - y de aprovechar bien la ventana de revisión. Bien ejecutado, las suscripciones se migran con confianza y sin sorpresas para clientes ni para finanzas.
