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: Elija Suscripción (esta guía). Las alternativas son Pago Único y Facturación Basada en Uso.
  • Precio (requerido): Precio base recurrente con moneda.
  • Descuento Aplicable (%): Porcentaje de descuento opcional aplicado al precio base; reflejado en el pago y en las facturas.
  • Repetir pago cada (requerido): Intervalo para renovaciones, por ejemplo, cada 1 Mes. Seleccione la cadencia (meses o años) y la cantidad.
  • Período de Suscripción (requerido): Término total durante el cual la suscripción permanece activa (por ejemplo, 10 Años). Después de que finalice este período, las renovaciones se detienen a menos que se extiendan.
  • Días del Período de Prueba (requerido): Establezca la duración de la prueba en días. Use 0 para deshabilitar pruebas. El primer cargo ocurre automáticamente cuando finaliza la prueba.
  • Seleccionar complemento: Adjunte hasta 10 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

Establezca Días del Período de Prueba en la sección de precios del producto (use 0 para deshabilitar). Puede 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 de 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

Extienda 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 puede 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.
Puedes cambiar los planes de suscripción y actualizar la próxima fecha de facturación directamente desde el panel de Dodo Payments. Esto proporciona una forma rápida de ajustar las suscripciones para solicitudes de soporte al cliente, mejoras promocionales o migraciones de planes sin realizar llamadas a la API.

Colecciones de Productos

Agrupa productos relacionados en colecciones para permitir rutas de actualización/descenso sin interrupciones en el Portal del Cliente.

​
Modos de Prorrateo

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

​
prorated_immediately

Cobra una cantidad prorrateada basada en el tiempo restante en el ciclo de facturación actual. Mejor para una facturación justa que considera 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 de inmediato (actualización) o agrega crédito para renovaciones futuras (descenso). Mejor para escenarios simples de actualización/descenso. 
// 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 los descensos utilizando 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 la totalidad del nuevo plan de inmediato, 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 Add-ons

Modifica los add-ons al cambiar de planes. Los add-ons están incluidos 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 al estado on_hold. Realiza un seguimiento de los cambios a través de eventos de webhook subscription.plan_changed.

​
Vista Previa de Cambios de Plan

Antes de comprometerte a un cambio de plan, prevé 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);

Vista Previa del API para Cambiar Plan

Vista previa de 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 reactivarse
  • cancelled: La suscripción está cancelada y no se renovará
  • expired: La suscripción ha llegado a su fecha de finalización
  • pending: La suscripción está siendo creada o procesada

​
Estado en Espera

Una suscripción entra en el 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 el estado on_hold, no se renovará automáticamente. Debes actualizar el método de pago para reactivar la suscripción.

​
Reactivando desde el Estado en 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 los saldos pendientes
  2. Genera una factura
  3. Procesa el pago utilizando el nuevo método de pago
  4. Reactiva la suscripción al estado active al realizar el pago con éxito
// 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 estado on_hold, recibirás payment.succeeded seguido de eventos de webhook subscription.active.

​
Gestión de API

Utiliza POST /subscriptions para crear suscripciones programáticamente a partir de productos, con pruebas opcionales y add-ons.

Referencia de API

Ver la API para crear suscripciones.
Utiliza 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 las suscripciones.
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 según se requiera.

Referencia de API

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

Referencia de API

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

Referencia de API

Ver 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 los saldos pendientes.

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 add-ons para asientos o uso
  • Contenido y medios: Acceso mensual con pruebas introductorias
  • Planes de soporte B2B: Contratos anuales con add-ons de soporte premium
  • Herramientas y complementos: Claves de licencia y versiones liberadas

​
Ejemplos de Integración

​
Sesiones de Pago (suscripciones)

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

​
Cambios de plan con prorrateo

Actualiza o baja 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 periodo

Programa una cancelación sin una 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 el 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 del RBI

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

​
Límites de Mandato

El tipo y monto del mandato dependen del cargo recurrente de tu suscripción:
  • Cargos por debajo de Rs 15,000: Creamos un mandato bajo demanda por Rs 15,000 INR. La cantidad de suscripción se cobra periódicamente según la frecuencia de tu suscripción, hasta el límite del mandato.
  • Cargos Rs 15,000 o más: Creamos un mandato de suscripción (o mandato bajo demanda) por el monto exacto de suscripción.
Para obtener información detallada sobre mandatos cumplidores del RBI para métodos de pago indios, consulta la página de Métodos de Pago en India.

​
Consideraciones para Actualizar y Reducir

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

​
Autorización para Cargos de Alto Valor

Para cargos de suscripción de Rs 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 será puesta en espera.

​
Retraso en el Procesamiento de 48 Horas

Línea de Tiempo de Procesamiento: Los cargos recurrentes en tarjetas indias y suscripciones de UPI siguen un patrón de procesamiento único:
  • Los cargos son iniciados en la fecha programada según 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 extremo específico de suscripciones de Pago Automático de tarjeta india y UPI).
  • Sin embargo, la deducción real puede fallar, y en ese caso, pondremos la suscripción en espera.
Manejo de Casos Extremos: Si proporcionas beneficios, créditos o uso de suscripciones a los clientes inmediatamente después de la iniciación del cargo, debes manejar esta ventana de 48 horas de manera apropiada en tu aplicación. Considera:
  • Retrasar la activación del beneficio 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 suscripción en espera 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 extremos donde se cancelen mandatos 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
  • Utiliza pruebas de manera reflexiva: Convierte con incorporación, no solo con tiempo
  • Aprovecha los add-ons: 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 las métricas de adopción, cancelación y expansión.