Saltar al contenido principal
Las suscripciones te permiten vender acceso continuo con renovaciones automáticas. Utiliza ciclos de facturación flexibles, pruebas gratuitas, cambios de plan y complementos para personalizar los precios para cada cliente.

Actualizar y Degradar

Controla los cambios de plan con prorrateo y actualizaciones de cantidad.

Suscripciones Bajo Demanda

Autoriza un mandato ahora y cobra más tarde con montos personalizados.

Portal del Cliente

Permite a los clientes gestionar planes, facturación y cancelaciones.

Webhooks de Suscripción

Reacciona a eventos del ciclo de vida como creado, renovado y cancelado.

​
¿Qué Son las Suscripciones?

Las suscripciones son productos recurrentes que los clientes compran en un horario. Son ideales para:
  • Licencias de SaaS: Aplicaciones, APIs o acceso a plataformas
  • Membresías: Comunidades, programas o clubes
  • Contenido digital: Cursos, medios o contenido premium
  • Planes de soporte: SLA, paquetes de éxito o mantenimiento

​
Beneficios Clave

  • Ingresos predecibles: Facturación recurrente con renovaciones automáticas
  • Ciclos flexibles: Mensuales, anuales, intervalos personalizados y pruebas
  • Agilidad del plan: Prorrateo para actualizaciones y degradaciones
  • Complementos y asientos: Adjunta mejoras opcionales y cuantificables
  • Checkout sin problemas: Checkout alojado y portal del cliente
  • Desarrollador primero: APIs claras para creación, cambios y seguimiento de uso

​
Creando Suscripciones

Crea productos de suscripción en tu panel de Dodo Payments, luego véndelos a través de checkout o tu API. Separar productos de suscripciones activas te permite versionar precios, adjuntar complementos y rastrear el rendimiento de manera independiente.

​
Creación de productos de suscripción

Configura los campos en el panel para definir cómo se vende, renueva y factura tu suscripción. Las secciones a continuación se corresponden directamente con lo que ves en el formulario de creación.

​
Detalles del producto

  • Nombre del Producto (requerido): El nombre que se muestra en el checkout, portal del cliente y facturas.
  • Descripción del Producto (requerido): Una declaración de valor clara que aparece en el checkout y las facturas.
  • Imagen del Producto (requerido): PNG/JPG/WebP de hasta 3 MB. Usada en el checkout y las facturas.
  • Marca: Asocia el producto con una marca específica para temas y correos electrónicos.
  • Categoría Fiscal (requerido): Elige la categoría (por ejemplo, SaaS) para determinar las reglas fiscales.
Elige la categoría fiscal más precisa para asegurar la correcta recaudación de impuestos por región.

​
Precios

  • Tipo de Precio: Elige Suscripción (esta guía). Las alternativas son Pago Único y Facturación Basada en Uso.
  • Precio (requerido): Precio recurrente base con moneda.
  • Descuento Aplicable (%): Descuento porcentual opcional aplicado al precio base; reflejado en el checkout y las facturas.
  • Repetir pago cada (requerido): Intervalo para renovaciones, por ejemplo, cada 1 Mes. Selecciona la cadencia (meses o años) y la cantidad.
  • Período de Suscripción (requerido): Término total por el cual la suscripción permanece activa (por ejemplo, 10 Años). Después de que este período termine, las renovaciones se detienen a menos que se extiendan.
  • Días de Período de Prueba (requerido): Establece la duración de la prueba en días. Usa 0 para deshabilitar pruebas. El primer cargo ocurre automáticamente cuando termina la prueba.
  • Seleccionar complemento: Adjunta hasta 3 complementos que los clientes pueden comprar junto con el plan base.
Cambiar el precio de un producto activo afecta las nuevas compras. Las suscripciones existentes siguen tus configuraciones de cambio de plan y prorrateo.
Los complementos son ideales para extras cuantificables como asientos o almacenamiento. Puedes controlar las cantidades permitidas y el comportamiento de prorrateo cuando los clientes los cambian.

​
Configuraciones avanzadas

  • Precios Incluidos Impuestos: Muestra precios incluidos impuestos aplicables. El cálculo final de impuestos aún varía según la ubicación del cliente.
  • Generar claves de licencia: Emite una clave única a cada cliente después de la compra. Consulta la guía de Claves de Licencia.
  • Entrega de Producto Digital: Entrega archivos o contenido automáticamente después de la compra. Aprende más en Entrega de Producto Digital.
  • Metadatos: Adjunta pares clave-valor personalizados para etiquetado interno o integraciones de clientes. Consulta Metadatos.
Usa metadatos para almacenar identificadores de tu sistema (por ejemplo, accountId) para que puedas reconciliar eventos y facturas más tarde.

​
Pruebas de Suscripción

Las pruebas permiten a los clientes acceder a suscripciones sin pago inmediato. El primer cargo ocurre automáticamente cuando termina la prueba.

​
Configurando Pruebas

Establece Días de Período de Prueba en la sección de precios del producto (usa 0 para deshabilitar). Puedes anular esto al crear suscripciones: 
// Via subscription creation
const subscription = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_monthly',
  trial_period_days: 14  // Overrides product's trial period
});

// Via checkout session
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_monthly', quantity: 1 }],
  subscription_data: { trial_period_days: 14 }
});
El valor trial_period_days debe estar entre 0 y 10,000 días.

​
Detectando el Estado de Prueba

Actualmente, no hay un campo directo para detectar el estado de prueba. Lo siguiente es una solución alternativa que requiere consultar pagos, lo cual es ineficiente. Estamos trabajando en una solución más eficiente.
Para determinar si una suscripción está en prueba, recupera la lista de pagos para la suscripción. Si hay exactamente un pago con monto 0, la suscripción está en período de prueba: 
const subscription = await client.subscriptions.retrieve('sub_123');
const payments = await client.payments.list({
  subscription_id: subscription.subscription_id
});

// Check if subscription is in trial
const isInTrial = payments.items.length === 1 && 
                  payments.items[0].total_amount === 0;

​
Actualizando el Período de Prueba

Extiende la prueba actualizando next_billing_date: 
await client.subscriptions.update('sub_123', {
  next_billing_date: '2025-02-15T00:00:00Z'  // New trial end date
});
No puedes establecer next_billing_date a un tiempo pasado. La fecha debe estar en el futuro.

​
Cambios en el Plan de Suscripción

Los cambios de plan te permiten actualizar o degradar suscripciones, ajustar cantidades o migrar a diferentes productos. Cada cambio desencadena un cargo inmediato basado en el modo de prorrateo que selecciones.

​
Modos de Prorrateo

Elige cómo se facturan los clientes al cambiar de planes:

​
prorated_immediately

Cobra un monto prorrateado basado en el tiempo restante en el ciclo de facturación actual. Mejor para una facturación justa que tenga en cuenta el tiempo no utilizado. 
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

​
difference_immediately

Cobra la diferencia de precio inmediatamente (actualización) o añade crédito para futuras renovaciones (degradación). Mejor para escenarios simples de actualización/degradación. 
// Upgrade: charges $50 (difference between $30 and $80)
// Downgrade: credits remaining value, auto-applied to renewals
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});
Los créditos de las degradaciones usando difference_immediately son de ámbito de suscripción y se aplican automáticamente a futuras renovaciones. Son distintos de Créditos de Clientes.

​
full_immediately

Cobra el monto completo del nuevo plan inmediatamente, ignorando el tiempo restante. Mejor para restablecer ciclos de facturación. 
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_monthly',
  quantity: 1,
  proration_billing_mode: 'full_immediately'
});

​
Cambiando Planes con Complementos

Modifica los complementos al cambiar de planes. Los complementos se incluyen en los cálculos de prorrateo: 
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [{ addon_id: 'addon_extra_seats', quantity: 2 }]  // Add add-ons
  // addons: []  // Empty array removes all existing add-ons
});
Los cambios de plan desencadenan cargos inmediatos. Los cargos fallidos pueden mover la suscripción a on_hold estado. Rastrear cambios a través de eventos de webhook subscription.plan_changed.

​
Previsualizando Cambios de Plan

Antes de comprometerte a un cambio de plan, previsualiza el cargo exacto y la suscripción resultante: 
const preview = await client.subscriptions.previewChangePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

// Show customer the charge before confirming
console.log('You will be charged:', preview.immediate_charge.summary);

API de Previsualización de Cambio de Plan

Previsualiza los cambios de plan antes de comprometerte a ellos.

​
Estados de Suscripción

Las suscripciones pueden estar en diferentes estados a lo largo de su ciclo de vida:
  • active: La suscripción está activa y se renovará automáticamente
  • on_hold: La suscripción está en pausa debido a un pago fallido. Se requiere actualización del método de pago para reactivar
  • cancelled: La suscripción está cancelada y no se renovará
  • expired: La suscripción ha alcanzado su fecha de finalización
  • pending: La suscripción está siendo creada o procesada

​
Estado en Espera

Una suscripción entra en estado on_hold cuando:
  • Un pago de renovación falla (fondos insuficientes, tarjeta expirada, etc.)
  • Un cargo por cambio de plan falla
  • La autorización del método de pago falla
Cuando una suscripción está en estado on_hold, no se renovará automáticamente. Debes actualizar el método de pago para reactivar la suscripción.

​
Reactivando desde Espera

Para reactivar una suscripción desde el estado on_hold, actualiza el método de pago. Esto automáticamente:
  1. Crea un cargo por las deudas restantes
  2. Genera una factura
  3. Procesa el pago utilizando el nuevo método de pago
  4. Reactiva la suscripción al estado active tras el pago exitoso
// Reactivate subscription from on_hold
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'new',
  return_url: 'https://example.com/return'
});

// For on_hold subscriptions, a charge is automatically created
if (response.payment_id) {
  console.log('Charge created:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
  // Monitor webhooks for payment.succeeded and subscription.active
}
Después de actualizar exitosamente el método de pago para una suscripción en on_hold, recibirás eventos de webhook payment.succeeded seguidos de subscription.active.

​
Gestión de API

Usa POST /subscriptions para crear suscripciones programáticamente a partir de productos, con pruebas y complementos opcionales.

Referencia de API

Consulta la API para crear suscripciones.
Usa PATCH /subscriptions/{id} para actualizar cantidades, cancelar al final del período o modificar metadatos.

Referencia de API

Aprende cómo actualizar los detalles de la suscripción.
Cambia el producto activo y las cantidades con controles de prorrateo.

Referencia de API

Revisa las opciones de cambio de plan.
Para suscripciones bajo demanda, cobra montos específicos bajo demanda.

Referencia de API

Cobra una suscripción bajo demanda.
Usa GET /subscriptions para listar todas las suscripciones y GET /subscriptions/{id} para recuperar una.

Referencia de API

Explora las APIs de listado y recuperación.
Obtén el uso registrado para modelos de precios medidos o híbridos.

Referencia de API

Consulta la API de historial de uso.
Actualiza el método de pago para una suscripción. Para suscripciones activas, esto actualiza el método de pago para futuras renovaciones. Para suscripciones en estado on_hold, esto reactiva la suscripción creando un cargo por las deudas restantes.

Referencia de API

Aprende cómo actualizar métodos de pago y reactivar suscripciones.

​
Casos de Uso Comunes

  • SaaS y APIs: Acceso por niveles con complementos para asientos o uso
  • Contenido y medios: Acceso mensual con pruebas introductorias
  • Planes de soporte B2B: Contratos anuales con complementos de soporte premium
  • Herramientas y complementos: Claves de licencia y lanzamientos versionados

​
Ejemplos de Integración

​
Sesiones de Checkout (suscripciones)

Al crear sesiones de checkout, incluye tu producto de suscripción y complementos opcionales: 
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_subscription',
      quantity: 1
    }
  ]
});

​
Cambios de plan con prorrateo

Actualiza o degrada una suscripción y controla el comportamiento de prorrateo: 
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

​
Cancelar al final del período

Programa una cancelación sin terminación inmediata del acceso: 
await client.subscriptions.update('sub_123', {
  cancel_at_period_end: true
});

​
Suscripciones bajo demanda

Crea una suscripción bajo demanda y cobra más tarde según sea necesario: 
const onDemand = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_on_demand',
  on_demand: true
});

await client.subscriptions.createCharge(onDemand.id, {
  amount: 4900,
  currency: 'USD',
  description: 'Extra usage for September'
});

​
Actualizar método de pago para suscripción activa

Actualiza el método de pago para una suscripción activa: 
// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'new',
  return_url: 'https://example.com/return'
});

// Or use existing payment method
await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'existing',
  payment_method_id: 'pm_abc123'
});

​
Reactivar suscripción desde en espera

Reactivar una suscripción que se puso en espera debido a un pago fallido: 
// Update payment method - automatically creates charge for remaining dues
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'new',
  return_url: 'https://example.com/return'
});

if (response.payment_id) {
  // Charge created for remaining dues
  // Redirect customer to response.payment_link
  // Monitor webhooks: payment.succeeded → subscription.active
}

​
Suscripciones con Mandatos Cumplidores de RBI

Las suscripciones UPI y de tarjetas indias operan bajo regulaciones del RBI (Banco de Reserva de India) con requisitos específicos de mandato:

​
Límites de Mandato

El tipo y monto del mandato dependen del cargo recurrente de tu suscripción:
  • Cargos inferiores a ₹15,000: Creamos un mandato bajo demanda por ₹15,000 INR. El monto de la suscripción se cobra periódicamente de acuerdo con la frecuencia de tu suscripción, hasta el límite del mandato.
  • Cargos de ₹15,000 o más: Creamos un mandato de suscripción (o mandato bajo demanda) por el monto exacto de la suscripción.

​
Consideraciones para Actualizar y Degradar

Importante: Al actualizar o degradar suscripciones, considera cuidadosamente los límites del mandato:
  • Si una actualización/degradación resulta en un monto de cargo que excede ₹15,000 y va más allá del límite de pago bajo demanda existente, el cargo de la transacción puede fallar.
  • En tales casos, el cliente puede necesitar actualizar su método de pago o cambiar la suscripción nuevamente para establecer un nuevo mandato con el límite correcto.

​
Autorización para Cargos de Alto Valor

Para cargos de suscripción de ₹15,000 o más:
  • El cliente será solicitado por su banco para autorizar la transacción.
  • Si el cliente no autoriza la transacción, esta fallará y la suscripción se pondrá en espera.

​
Retraso de Procesamiento de 48 Horas

Cronograma de Procesamiento: Los cargos recurrentes en tarjetas indias y suscripciones UPI siguen un patrón de procesamiento único:
  • Los cargos son iniciados en la fecha programada de acuerdo con la frecuencia de tu suscripción.
  • La deducción real de la cuenta del cliente ocurre solo después de 48 horas desde la iniciación del pago.
  • Esta ventana de 48 horas puede extenderse hasta 2-3 horas adicionales dependiendo de las respuestas de la API del banco.

​
Ventana de Cancelación de Mandato

Durante la ventana de procesamiento de 48 horas:
  • Los clientes pueden cancelar el mandato a través de sus aplicaciones bancarias.
  • Si un cliente cancela el mandato durante este período, la suscripción permanecerá activa (este es un caso límite específico para suscripciones de tarjetas indias y UPI AutoPay).
  • Sin embargo, la deducción real puede fallar, y en ese caso, pondremos la suscripción en espera.
Manejo de Casos Límite: Si proporcionas beneficios, créditos o uso de suscripción a los clientes inmediatamente después de la iniciación del cargo, necesitas manejar esta ventana de 48 horas apropiadamente en tu aplicación. Considera:
  • Retrasar la activación de beneficios hasta la confirmación del pago
  • Implementar períodos de gracia o acceso temporal
  • Monitorear el estado de la suscripción para cancelaciones de mandato
  • Manejar estados de espera de suscripción en la lógica de tu aplicación
Monitorea los webhooks de suscripción para rastrear cambios en el estado de pago y manejar casos límite donde los mandatos son cancelados durante la ventana de 48 horas.

​
Mejores Prácticas

  • Comienza con niveles claros: 2–3 planes con diferencias obvias
  • Comunica precios: Muestra totales, prorrateo y próxima renovación
  • Usa pruebas de manera reflexiva: Convierte con incorporación, no solo con tiempo
  • Aprovecha los complementos: Mantén los planes base simples y vende extras
  • Prueba cambios: Valida cambios de plan y prorrateo en modo de prueba
Las suscripciones son una base flexible para ingresos recurrentes. Comienza simple, prueba a fondo e itera según la adopción, la pérdida y las métricas de expansión.