Subscription Integration Guide

Requisitos previos

Antes de comenzar, necesitas:

Una cuenta de comerciante de Dodo Payments
Una API key de Developer → API Keys en el dashboard, almacenada en DODO_PAYMENTS_API_KEY
Un webhook secret de Developer → Webhooks, almacenado en DODO_PAYMENTS_WEBHOOK_KEY
Al menos un producto de suscripción creado en Products

Para obtener más información, consulta Requisitos previos de la guía de integración.

Integración de API

Sesiones de checkout

Crea una suscripción mediante una sesión de checkout con tu producto de suscripción. El cliente autoriza un método de pago y la suscripción se activa cuando completa el checkout.

Puedes combinar un producto de suscripción con productos de un solo uso en la misma sesión de checkout. Esto permite aplicar tarifas de configuración, combinar hardware con SaaS y abordar casos de uso similares. Consulta Checkout Sessions para ver ejemplos.También puedes vender dos o más productos de suscripción en un solo checkout. El cliente paga una vez y obtiene una suscripción independiente por producto, cada una con su propio ciclo de facturación. Este tipo de carrito no puede contener productos de un solo uso. Consulta Multi-Subscription Cart.

Node.js SDK
Python SDK
REST API

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

async function main() {
  const session = await client.checkoutSessions.create({
    product_cart: [
      { product_id: 'pdt_subscription_monthly', quantity: 1 }
    ],
    // Optional: configure trials for subscription products
    subscription_data: { trial_period_days: 14 },
    customer: {
      email: 'subscriber@example.com',
      name: 'Jane Doe',
    },
    return_url: 'https://example.com/success',
  });

  console.log(session.checkout_url);
}

main();

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",  # defaults to "live_mode"
)

session = client.checkout_sessions.create(
    product_cart=[
        {"product_id": "pdt_subscription_monthly", "quantity": 1}
    ],
    subscription_data={"trial_period_days": 14},  # optional
    customer={
        "email": "subscriber@example.com",
        "name": "Jane Doe",
    },
    return_url="https://example.com/success",
)

print(session.checkout_url)

const response = await fetch('https://test.dodopayments.com/checkouts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`
  },
  body: JSON.stringify({
    product_cart: [
      { product_id: 'pdt_subscription_monthly', quantity: 1 }
    ],
    subscription_data: { trial_period_days: 14 }, // optional
    customer: {
      email: 'subscriber@example.com',
      name: 'Jane Doe'
    },
    return_url: 'https://example.com/success'
  })
});

if (!response.ok) {
  throw new Error(`HTTP error! status: ${response.status}`);
}

const session = await response.json();
console.log(session.checkout_url);

Respuesta de la API

La respuesta incluye un checkout_url:

{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}

Redirige al cliente a esta URL. El cliente autoriza el método de pago y la suscripción se activa.

Webhooks

Los webhooks notifican a tu servidor cuando ocurren eventos de suscripción. Configura tu endpoint en Developer → Webhooks en el dashboard. Para configurar tu endpoint de webhook, consulta Webhooks.

Tipos de eventos de suscripción

Supervisa estos eventos para gestionar el ciclo de vida de la suscripción:

subscription.active — La suscripción se activa
subscription.updated — Un campo de la suscripción cambió
subscription.on_hold — Un cargo de renovación o cambio de plan falló
subscription.failed — La creación de la suscripción falló (terminal; el cliente debe volver a suscribirse)
subscription.renewed — Un cargo recurrente se realizó correctamente
subscription.past_due — Una renovación falló y comenzó el período de gracia; el cliente conserva el acceso hasta past_due_ends_at
subscription.plan_changed — El plan se actualizó, se degradó o cambió
subscription.cancelled — La suscripción se canceló
subscription.expired — La suscripción llegó al final de su período

Estos son los eventos principales. Para consultar la lista completa, incluidos paused, unpaused y update_payment_method, consulta Subscription Webhooks.

Usa subscription.updated para recibir notificaciones en tiempo real sobre cualquier cambio en la suscripción y mantener sincronizado el estado de tu aplicación sin consultar la API periódicamente.

Escenarios de pago

Flujo de pago exitoso La secuencia de webhooks depende de si la suscripción tiene un período de prueba. Facturación inmediata (0 días de prueba):

subscription.active: el mandato se autoriza y la suscripción se activa.
payment.succeeded: confirma el primer cargo. Espera recibirlo en un plazo de 2–10 minutos después del checkout.

Con un período de prueba:

Al comenzar la prueba (checkout): subscription.active se activa una vez autorizado el método de pago. Todavía no se realiza ningún cargo recurrente. El primer cargo real se pospone hasta que finalice la prueba.
Al finalizar la prueba: se cobra el importe recurrente y recibes payment.succeeded junto con subscription.renewed.

Cada renovación posterior:

subscription.renewed: se activa en cada ciclo de facturación cuando se deduce el pago de renovación, siempre junto con payment.succeeded. También incluye el next_billing_date actualizado.

Siempre que se deduzca dinero por un producto de suscripción, recibirás subscription.renewed y payment.succeeded. Usa subscription.renewed (en lugar de usar únicamente payment.succeeded) como señal para ampliar el acceso durante el siguiente ciclo.

Escenarios de pago fallido

Fallo de la suscripción

subscription.failed - La creación de la suscripción falló porque no se pudo crear un mandato.
payment.failed - Indica un pago fallido.

Suscripción en espera

subscription.on_hold - La suscripción se pone en espera debido a un pago de renovación fallido o a un cargo fallido por cambio de plan. Si tu empresa tiene un período de gracia, una renovación fallida mueve primero la suscripción a past_due (subscription.past_due), y la mueve a on_hold (o cancelled, según la configuración del período de gracia) únicamente cuando este finaliza. Consulta Subscription States.
Cuando una suscripción pasa a estar en espera, no se renueva automáticamente hasta que se actualiza el método de pago.

Práctica recomendada: Para simplificar la implementación, recomendamos realizar principalmente el seguimiento de los eventos de suscripción para gestionar el ciclo de vida de la suscripción.

Para consultar una guía completa sobre cómo leer error_code/error_message, decidir cuándo reintentar y mostrar los fallos a los clientes, consulta Handle Payment Failures.

`subscription.failed` frente a `subscription.on_hold`

Es fácil confundir estos dos eventos, pero requieren un tratamiento muy diferente:

Evento	Cuándo se activa	Estado	¿Se puede recuperar?	Qué hacer
`subscription.failed`	No se pudo crear el mandato inicial durante la creación de la suscripción	`failed`	No (terminal)	No concedas acceso. Pide al cliente que inicie una nueva suscripción con otro método de pago.
`subscription.on_hold`	Falló un pago de renovación (o un cargo por cambio de plan) en una suscripción ya activa	`on_hold`	Sí	Recupera la suscripción actualizando el método de pago; consulta Handling Subscription On Hold a continuación.

subscription.failed es terminal. La suscripción no se puede reactivar. El cliente debe crear una nueva suscripción. Nunca concedas permisos cuando se active este evento.

Gestionar una suscripción en espera

Cuando una suscripción entra en el estado on_hold, debes actualizar el método de pago para reactivarla. En esta sección se explica cuándo las suscripciones pasan a estar en espera y cómo gestionarlas.

Cuándo pasan las suscripciones a estar en espera

Una suscripción pasa a estar en espera cuando:

Falla el pago de renovación: el cargo de renovación automática falla por fondos insuficientes, una tarjeta vencida o el rechazo del banco
Falla el cargo por cambio de plan: falla un cargo inmediato durante la actualización o degradación del plan
Falla la autorización del método de pago: el método de pago no se puede autorizar para cargos recurrentes

Las suscripciones en el estado on_hold no se renovarán automáticamente. Debes actualizar el método de pago para reactivar la suscripción.

Reactivar suscripciones en espera

Para reactivar una suscripción desde el estado on_hold, usa la API Update Payment Method. Esto automáticamente:

Crea un cargo por los importes pendientes
Genera una factura para el cargo
Procesa el pago con el nuevo método de pago
Reactiva la suscripción al estado active tras realizarse correctamente el pago

Handle subscription.on_hold webhook

Cuando recibas un webhook subscription.on_hold, actualiza el estado de tu aplicación y notifica al cliente:

// Webhook handler
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'subscription.on_hold') {
    const subscription = event.data;
    
    // Update subscription status in your database
    await updateSubscriptionStatus(subscription.subscription_id, 'on_hold');
    
    // Notify customer to update payment method
    await sendEmailToCustomer(subscription.customer_id, {
      subject: 'Payment Required - Subscription On Hold',
      message: 'Your subscription is on hold. Please update your payment method to continue service.'
    });
  }
  
  res.json({ received: true });
});

Update payment method

Cuando el cliente esté listo para actualizar su método de pago, llama a la API Update Payment Method:

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
  payment_method: { 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 for remaining dues:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
}

# Update with new payment method
response = client.subscriptions.update_payment_method(
    subscription_id=subscription_id,
    payment_method={"type": "new", "return_url": "https://example.com/return"},
)

# For on_hold subscriptions, a charge is automatically created
if response.payment_id:
    print("Charge created for remaining dues:", response.payment_id)
    # Redirect customer to response.payment_link to complete payment

También puedes usar un ID de método de pago existente si el cliente tiene métodos de pago guardados:

await client.subscriptions.updatePaymentMethod(subscriptionId, {
  payment_method: { type: 'existing', payment_method_id: 'pm_abc123' }
});

Monitor webhook events

Después de actualizar el método de pago, supervisa estos eventos de webhook:

payment.succeeded - El cargo por los importes pendientes se realizó correctamente
subscription.active - La suscripción se reactivó

if (event.type === 'payment.succeeded') {
  const payment = event.data;
  
  // Check if this payment is for an on_hold subscription
  if (payment.subscription_id) {
    // Wait for subscription.active webhook to confirm reactivation
  }
}

if (event.type === 'subscription.active') {
  const subscription = event.data;
  
  // Update subscription status in your database
  await updateSubscriptionStatus(subscription.subscription_id, 'active');
  
  // Restore customer access
  await restoreCustomerAccess(subscription.customer_id);
  
  // Notify customer of successful reactivation
  await sendEmailToCustomer(subscription.customer_id, {
    subject: 'Subscription Reactivated',
    message: 'Your subscription has been reactivated successfully.'
  });
}

Ejemplo de payload de evento de suscripción

Propiedad	Tipo	Obligatorio	Descripción
`business_id`	string	Sí	El identificador único de la empresa
`timestamp`	string	Sí	La marca de tiempo en que ocurrió el evento (no necesariamente coincide con el momento en que se entregó)
`type`	string	Sí	El tipo de evento. Consulta Subscription Event Types
`data`	object	Sí	El payload de datos principal. Consulta Subscription webhook payloads

Cambiar planes de suscripción

Puedes actualizar o degradar un plan de suscripción mediante el endpoint de la API de cambio de plan. Esto te permite modificar el producto, la cantidad y gestionar el prorrateo de la suscripción.

Change Plan API Reference

Para obtener información detallada sobre cómo cambiar planes de suscripción, consulta nuestra documentación de la API Change Plan.

Opciones de prorrateo

Al cambiar de plan de suscripción, tienes cuatro opciones para gestionar el cargo inmediato:

1. `prorated_immediately`

Abona la parte no utilizada del ciclo de facturación actual, prorrateada según el tiempo restante. El crédito cubre el plan base, la cantidad y cualquier complemento
Después cobra un ciclo completo con el nuevo plan, cantidad y complementos. El cargo en sí nunca se prorratea
Cargo inmediato neto = (ciclo nuevo completo) menos (fracción restante x ciclo antiguo completo). Si el crédito es mayor, la diferencia se conserva como crédito asociado a la suscripción para futuras renovaciones
Durante un período de prueba, esto cambia inmediatamente al usuario al nuevo plan y cobra al cliente en ese momento

2. `full_immediately`

Cobra al cliente el importe total de la suscripción del nuevo plan sin crédito por el ciclo anterior
Tanto al actualizar como al degradar el plan, el cliente paga desde cero el precio completo del nuevo plan
Es útil cuando quieres cobrar el importe completo independientemente del tiempo restante del plan anterior

3. `difference_immediately`

El cliente solo paga la diferencia entre el precio del plan anterior y el nuevo
El importe no depende del momento del ciclo en que se realiza el cambio. La misma actualización cuesta lo mismo el día 1 que el día 29
Al actualizar el plan, se cobra inmediatamente al cliente la diferencia. Por ejemplo, $30/mes → $80/mes = $50 cobrados al instante
Al degradar el plan, la diferencia de precio se guarda como crédito asociado a la suscripción y se aplica automáticamente a futuras renovaciones. Por ejemplo, $50/mes → $20/mes = $30 guardados como crédito

4. `do_not_bill`

Aplica el cambio de plan inmediatamente, pero no cobra nada en el momento del cambio. El nuevo plan, la cantidad y los complementos se pueden usar de inmediato
Como no se cobra nada en ese momento, una actualización proporciona al cliente el plan superior de forma gratuita durante el resto del ciclo actual. Una degradación entra en vigor inmediatamente sin crédito por la parte no utilizada del ciclo que el cliente ya pagó
Los complementos concedidos mediante do_not_bill no se acreditan en un cambio de plan posterior porque nunca se facturaron. Un cambio posterior factura íntegramente la nueva cantidad de complementos
El plan actualizado (y la cantidad o los complementos) se factura en la siguiente renovación programada y se conserva la fecha de facturación original

Los tres modos de «cobrar ahora» reinician el ciclo de facturación. prorated_immediately, difference_immediately e full_immediately mueven el next_billing_date de la suscripción a la fecha del cambio. Solo do_not_bill conserva la fecha de renovación original, pero no aplica ningún cargo inmediato.

Comportamiento

Cuando invocas esta API, Dodo Payments inicia inmediatamente un cargo según la opción de prorrateo seleccionada
Con prorated_immediately, se calcula un crédito por la parte no utilizada del ciclo actual en cada cambio, tanto al actualizar como al degradar el plan. Si ese crédito supera el cargo del nuevo ciclo, el resto se añade al saldo de crédito de la suscripción. Estos créditos son específicos de esa suscripción y solo se utilizarán para compensar futuros pagos recurrentes de la misma suscripción
Con difference_immediately, el importe neto siempre es exactamente la diferencia de precio. En las degradaciones, el excedente se guarda como crédito asociado a la suscripción, igual que con prorated_immediately
La opción full_immediately omite los cálculos de crédito y cobra el importe completo del nuevo plan
La opción do_not_bill aplica el cambio inmediatamente, pero pospone la facturación hasta la siguiente fecha de renovación, que se conserva

Cómo elegir un modo de prorrateo:

difference_immediately — el cliente paga la diferencia de precio. Es la opción más predecible; el cargo es el mismo independientemente del momento del ciclo en que se realice el cambio.
prorated_immediately — el cliente recibe crédito únicamente por el tiempo no utilizado del ciclo actual. El cargo varía según el momento del ciclo en que se realice el cambio.
full_immediately — el cliente paga el importe completo del nuevo plan. No se concede crédito por el ciclo anterior.
do_not_bill — no hay ningún cargo ahora. El nuevo plan se factura en la siguiente renovación. Es el único modo que conserva la fecha de facturación original.

Procesamiento del cargo

El procesamiento del cargo inmediato iniciado al cambiar de plan suele completarse en menos de 2 minutos
Si este cargo inmediato falla por cualquier motivo, la suscripción pasa automáticamente a estar en espera hasta que se resuelva el problema

Suscripciones bajo demanda

Las suscripciones bajo demanda te permiten cobrar a los clientes de forma flexible, no solo según un calendario fijo. Esta función está disponible para todas las cuentas.

Para crear una suscripción bajo demanda: Para crear una suscripción bajo demanda, usa el endpoint de la API POST /checkouts e incluye el campo subscription_data.on_demand en el cuerpo de la solicitud. Esto te permite autorizar un método de pago sin realizar un cargo inmediato o establecer un precio inicial personalizado.

POST /subscriptions está obsoleto. Sigue funcionando para integraciones existentes, pero las nuevas integraciones deben crear suscripciones bajo demanda mediante una Checkout Session (POST /checkouts) con subscription_data.on_demand. Consulta la On-Demand Subscriptions Guide para conocer el flujo actual.

Para cobrar una suscripción bajo demanda: Para los cargos posteriores, usa el endpoint POST /subscriptions//charge y especifica el importe que se cobrará al cliente por esa transacción.

Para consultar una guía completa paso a paso (incluidos ejemplos de solicitudes y respuestas, políticas de reintento seguro y gestión de webhooks), consulta la On-Demand Subscriptions Guide.

Aspectos clave de la facturación de suscripciones

Establece un período de suscripción más largo que la frecuencia de pago. Si el período de suscripción es igual a la frecuencia de pago (por ejemplo, período = 1 mes, frecuencia = 1 mes), la suscripción es válida durante un solo ciclo y luego pasa a expired en lugar de renovarse. Para un plan mensual continuo, establece un período de suscripción largo (por ejemplo, 20 años) con una frecuencia de pago mensual.

La moneda se bloquea con el primer cargo exitoso. Pasa siempre billing_currency e billing_address.country explícitamente al crear el checkout. Si se omiten, se detectan a partir de la IP del cliente (Adaptive Currency), y una vez que la suscripción realiza su primer cargo, la moneda queda fijada durante toda su vigencia. Un cliente que viaje posteriormente no podrá cambiarla.

Las pruebas realizan una autorización de $0, no un cargo. Cuando una suscripción tiene un período de prueba, el inicio de la prueba crea una autorización de mandato de $0 para guardar la tarjeta; el primer cargo real se realiza cuando termina la prueba. En la lista de pagos, una suscripción en prueba gratuita muestra exactamente un pago con total_amount de 0. Una prueba de pago cobra por adelantado su trial_amount.

Ciclo de vida de la suscripción: past_due = una renovación falló y el período de gracia está activo (el cliente conserva el acceso). on_hold = una renovación falló (recuperable: solicita al cliente que actualice su método de pago; se aplican reintentos de dunning). expired = el período terminó sin renovación y no se puede reactivar. El cliente debe volver a suscribirse. cancelled = finalizada por el cliente o el merchant. La mayoría de los fallos de renovación son rechazos del emisor (fondos insuficientes, tarjeta rechazada), no un error de Dodo.

Las tarjetas indias funcionan con un mandato electrónico del RBI. Los cargos off-session (renovaciones y cargos por cambio de plan) pueden tardar hasta ~48 horas en liquidarse, y los débitos automáticos recurrentes superiores a ₹15,000 requieren una nueva autenticación del cliente (por lo que una actualización que supere ese límite no puede utilizar el mandato existente). Mientras un cargo siga en processing, un segundo cargo en la misma suscripción falla con “Cannot create new charge as previous payment is not successful yet.” Las tarjetas no indias se confirman casi al instante.

Las suscripciones tienen un mínimo de $1.00 en USD. Checkout rechaza un total inferior con TOTAL_PAYMENT_AMOUNT_BELOW_MINIMUM_AMOUNT. Las monedas distintas de USD, EUR y GBP también deben tener un valor mínimo de $1.00; consulta Minimum Amounts. Se rechaza un cargo bajo demanda product_price inferior a 100 en la unidad monetaria más pequeña con product_price: value out of range. Se permite un producto de suscripción con un precio exacto de $0; consulta Card-Optional at Zero Price. Para autorizar una tarjeta sin realizar un cargo, usa una configuración mandate_only bajo demanda.

Referencia de API relacionada

Create Subscription (Deprecated)

API heredada para crear una suscripción directamente. Usa Checkout Sessions para las nuevas integraciones

Change Subscription Plan

Referencia de API para actualizar, degradar o cambiar planes de suscripción con opciones de prorrateo

Update Payment Method

Referencia de API para actualizar métodos de pago y reactivar suscripciones en espera

Patch Subscription

Referencia de API para actualizar los detalles y la configuración de la suscripción

Integration Guides

Billing Deconstructions

Cookbooks

Requisitos previos

Integración de API

Sesiones de checkout

Respuesta de la API

Webhooks

Tipos de eventos de suscripción

Escenarios de pago

`subscription.failed` frente a `subscription.on_hold`

Gestionar una suscripción en espera

Cuándo pasan las suscripciones a estar en espera

Reactivar suscripciones en espera

Ejemplo de payload de evento de suscripción

Cambiar planes de suscripción

Change Plan API Reference

Opciones de prorrateo

1. `prorated_immediately`

2. `full_immediately`

3. `difference_immediately`

4. `do_not_bill`

Comportamiento

Procesamiento del cargo

Suscripciones bajo demanda

Aspectos clave de la facturación de suscripciones

Referencia de API relacionada

Create Subscription (Deprecated)

Change Subscription Plan

Update Payment Method

Patch Subscription

​Requisitos previos

​Integración de API

​Sesiones de checkout

​Respuesta de la API

​Webhooks

​Tipos de eventos de suscripción

​Escenarios de pago

​subscription.failed frente a subscription.on_hold

​Gestionar una suscripción en espera

​Cuándo pasan las suscripciones a estar en espera

​Reactivar suscripciones en espera

​Ejemplo de payload de evento de suscripción

​Cambiar planes de suscripción

Change Plan API Reference

​Opciones de prorrateo

​1. prorated_immediately

​2. full_immediately

​3. difference_immediately

​4. do_not_bill

​Comportamiento

​Procesamiento del cargo

​Suscripciones bajo demanda

​Aspectos clave de la facturación de suscripciones

​Referencia de API relacionada

Create Subscription (Deprecated)

Change Subscription Plan

Update Payment Method

Patch Subscription

Requisitos previos

Integración de API

Sesiones de checkout

Respuesta de la API

Webhooks

Tipos de eventos de suscripción

Escenarios de pago

`subscription.failed` frente a `subscription.on_hold`

Gestionar una suscripción en espera

Cuándo pasan las suscripciones a estar en espera

Reactivar suscripciones en espera

Ejemplo de payload de evento de suscripción

Cambiar planes de suscripción

Opciones de prorrateo

1. `prorated_immediately`

2. `full_immediately`

3. `difference_immediately`

4. `do_not_bill`

Comportamiento

Procesamiento del cargo

Suscripciones bajo demanda

Aspectos clave de la facturación de suscripciones

Referencia de API relacionada