Subscription Integration Guide

Prerequisites

To integrate the Dodo Payments API, you’ll need:

A Dodo Payments merchant account
API credentials (API key and webhook secret key) from the dashboard

For a more detailed guide on the prerequisites, check this section.

API Integration

Checkout Sessions

Use Checkout Sessions to sell subscription products with a secure, hosted checkout. Pass your subscription product in product_cart and redirect customers to the returned checkout_url.

Mixed Checkout: You can combine subscription products with one-time products in the same checkout session. This enables use cases like setup fees with subscriptions, hardware bundles with SaaS, and more. See the Checkout Sessions guide for examples.

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: 'prod_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": "prod_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: 'prod_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);

API Response

The following is an example of the response:

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

Redirige al cliente a checkout_url.

Webhooks

Al integrar suscripciones, recibirás webhooks para rastrear el ciclo de vida de la suscripción. Estos webhooks te ayudan a gestionar los estados de suscripción y escenarios de pago de manera efectiva. Para configurar tu endpoint de webhook, sigue nuestra Guía de Integración Detallada.

Tipos de Eventos de Suscripción

Los siguientes eventos de webhook rastrean los cambios de estado de la suscripción:

subscription.active - La suscripción se activa con éxito.
subscription.updated - El objeto de la suscripción fue actualizado (se dispara con cualquier cambio de campo).
subscription.on_hold - La suscripción se pone en espera debido a una renovación fallida.
subscription.failed - La creación de la suscripción falló durante la creación del mandato.
subscription.renewed - La suscripción se renueva para el siguiente período de facturación.

Para una gestión confiable del ciclo de vida de la suscripción, recomendamos rastrear estos eventos de suscripción.

Usa subscription.updated para obtener notificaciones en tiempo real sobre cualquier cambio de suscripción, manteniendo el estado de tu aplicación sincronizado sin sondeo de la API.

Escenarios de Pago

Flujo de Pago Exitoso Los webhooks que recibes y el momento en que los recibes dependen de si el producto 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 cobro. Recíbelo normalmente entre 2 y 10 minutos después del checkout.

Con un período de prueba:

Al inicio de la prueba (checkout): subscription.active se activa una vez autorizado el método de pago. Todavía no se realiza ningún cobro recurrente. El primer cobro 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 realmente por un producto de suscripción, recibes subscription.renewed y payment.succeeded. Usa subscription.renewed (en lugar de usar solo payment.succeeded) como señal para ampliar el acceso al siguiente ciclo.

Escenarios de pagos fallidos

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 cobro fallido por cambio de plan.
Cuando una suscripción pasa a estar en espera, no se renovará automáticamente hasta que se actualice 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 Gestionar fallos de pago.

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

Estos dos eventos se confunden fácilmente, pero requieren un tratamiento muy diferente:

Evento	Cuándo se activa	Estado	¿Se puede recuperar?	Qué hacer
`subscription.failed`	El mandato inicial no pudo crearse durante la creación de la suscripción	`failed`	No (terminal)	No concedas acceso. Pide al cliente que inicie una nueva suscripción con un método de pago diferente.
`subscription.on_hold`	Falló un pago de renovación (o un cobro por cambio de plan) en una suscripción ya activa	`on_hold`	Sí	Recupérala actualizando el método de pago; consulta Gestionar una suscripción en espera más abajo.

subscription.failed es terminal. La suscripción no se puede reactivar. El cliente debe crear una nueva suscripción. Nunca concedas derechos 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. Esta sección explica cuándo las suscripciones pasan a estar en espera y cómo gestionarlas.

Cuándo las suscripciones pasan a estar en espera

Una suscripción se pone en espera cuando:

Falla el pago de renovación: el cobro automático de renovación falla por fondos insuficientes, una tarjeta caducada o el rechazo del banco
Falla el cobro por cambio de plan: falla un cobro inmediato durante la actualización o degradación del plan
Falla la autorización del método de pago: no se puede autorizar el método de pago para cobros 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 cobro por las cantidades pendientes
Genera una factura por el cobro
Procesa el pago usando el nuevo método de pago
Reactiva la suscripción al estado active cuando el pago se realiza correctamente

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, {
  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,
    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, {
  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 cobro por las cantidades pendientes se realizó correctamente
subscription.active - La suscripción se ha reactivado

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 Tipos de eventos
`data`	object	Sí	El payload de datos principal. Consulta Objeto de datos

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 la prorrata 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 prorrata

Al cambiar de plan de suscripción, tienes dos opciones para gestionar el cobro inmediato:

1. `prorated_immediately`

Calcula el importe prorrateado según el tiempo restante del ciclo de facturación actual
Cobra al cliente únicamente la diferencia entre el plan anterior y el nuevo
Durante un período de prueba, 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
Ignora el tiempo restante o los créditos del plan anterior
Es útil cuando quieres reiniciar el ciclo de facturación o cobrar el importe total independientemente de la prorrata

3. `difference_immediately`

Al actualizar el plan, se cobra inmediatamente al cliente la diferencia entre los importes de ambos planes.
Por ejemplo, si el plan actual cuesta 30 dólares y el cliente cambia a uno de 80 dólares, se le cobran $50 al instante.
Al degradar el plan, el importe no utilizado del plan actual se añade como crédito interno y se aplica automáticamente a futuras renovaciones de la suscripción.
Por ejemplo, si el plan actual cuesta 50 dólares y el cliente cambia a un plan de 20 dólares, los $30 restantes se acreditan y se utilizan en el siguiente ciclo de facturación.

4. `do_not_bill`

Aplica el cambio de plan inmediatamente, pero no realiza ningún cobro en el momento del cambio.
El plan actualizado (y la cantidad/add-ons) 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 trasladan 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 cobro inmediato.

Comportamiento

Al invocar esta API, Dodo Payments inicia inmediatamente un cobro según la opción de prorrata seleccionada
Si el cambio de plan es una degradación y usas prorated_immediately, los créditos se calcularán automáticamente y se añadirán 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
La opción full_immediately omite los cálculos de crédito y cobra el importe completo del nuevo plan

Elige cuidadosamente la opción de prorrata: usa prorated_immediately para una facturación justa que tenga en cuenta el tiempo no utilizado, o full_immediately cuando quieras cobrar el importe completo del nuevo plan independientemente del ciclo de facturación actual.

Procesamiento del cobro

El cobro inmediato iniciado al cambiar de plan normalmente termina de procesarse en menos de 2 minutos
Si este cobro inmediato falla por cualquier motivo, la suscripción se pone automáticamente 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 siguiendo 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 /subscriptions e incluye el campo on_demand en el cuerpo de la solicitud. Esto te permite autorizar un método de pago sin realizar un cobro inmediato o establecer un precio inicial personalizado. Para cobrar una suscripción bajo demanda: Para los cobros 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/respuestas, políticas de reintento seguras y gestión de webhooks), consulta la Guía de suscripciones bajo demanda.

Aspectos clave de la facturación de suscripciones

Establece un período de suscripción superior a la frecuencia de pago. Si el período de suscripción equivale a la frecuencia de pago (por ejemplo, período = 1 mes, frecuencia = 1 mes), la suscripción será válida durante un solo ciclo y después pasará 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 fija con el primer cobro correcto. Incluye siempre billing_currency y 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 realizado el primer cobro de la suscripción, la moneda queda fijada durante toda su vigencia. Si el cliente viaja posteriormente, no podrá cambiarla.

Las pruebas utilizan una autorización de $0, no un cobro. Cuando una suscripción tiene una prueba, el inicio de la prueba crea una autorización de mandato de $0 para guardar la tarjeta; el primer cobro real se produce al finalizar la prueba. En la lista de pagos, una suscripción en período de prueba muestra exactamente un pago con amount: 0.

Ciclo de vida de la suscripción: on_hold = falló una renovación (se puede recuperar: solicita al cliente que actualice su método de pago; se aplican reintentos de dunning). expired = el plazo terminó sin renovación y no se puede reactivar. El cliente debe volver a suscribirse. cancelled = finalizada por el cliente o el comerciante. 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 cobros sin sesión (renovaciones y cobros por cambios de plan) pueden tardar hasta aproximadamente 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 cobro siga en processing, un segundo cobro 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.

Los cobros de suscripciones tienen un mínimo de $1 (o su equivalente en otra moneda). Los importes de $0.01–$0.99 se rechazan con product_price: value out of range; solo se permite $0 mediante una configuración bajo demanda de mandate_only.

Referencia de API relacionada

Create Subscription

Referencia de API para crear productos de suscripción y gestionar el ciclo de vida de las suscripciones

Change Subscription Plan

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

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

Prerequisites

API Integration

Checkout Sessions

API Response

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 las suscripciones pasan 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 prorrata

1. `prorated_immediately`

2. `full_immediately`

3. `difference_immediately`

4. `do_not_bill`

Comportamiento

Procesamiento del cobro

Suscripciones bajo demanda

Aspectos clave de la facturación de suscripciones

Referencia de API relacionada

Create Subscription

Change Subscription Plan

Update Payment Method

Patch Subscription

​Prerequisites

​API Integration

​Checkout Sessions

​API Response

​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 las suscripciones pasan 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 prorrata

​1. prorated_immediately

​2. full_immediately

​3. difference_immediately

​4. do_not_bill

​Comportamiento

​Procesamiento del cobro

​Suscripciones bajo demanda

​Aspectos clave de la facturación de suscripciones

​Referencia de API relacionada

Create Subscription

Change Subscription Plan

Update Payment Method

Patch Subscription

Prerequisites

API Integration

Checkout Sessions

API Response

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 las suscripciones pasan a estar en espera

Reactivar suscripciones en espera

Ejemplo de payload de evento de suscripción

Cambiar planes de suscripción

Opciones de prorrata

1. `prorated_immediately`

2. `full_immediately`

3. `difference_immediately`

4. `do_not_bill`

Comportamiento

Procesamiento del cobro

Suscripciones bajo demanda

Aspectos clave de la facturación de suscripciones

Referencia de API relacionada