Subscription Integration Guide

​

Requisitos previos

• 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

​

Integración de API

​

Sesiones de checkout

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 API

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

​

Webhooks

​

Tipos de eventos de suscripción

1. subscription.active — La suscripción se activa
2. subscription.updated — Un campo de la suscripción cambió
3. subscription.on_hold — Falló un cobro de renovación o de cambio de plan
4. subscription.failed — Falló la creación de la suscripción (terminal; el cliente debe suscribirse de nuevo)
5. subscription.renewed — Un cobro recurrente se realizó correctamente
6. subscription.past_due — Falló una renovación y comenzó el período de gracia; el cliente conserva el acceso hasta past_due_ends_at
7. subscription.plan_changed — El plan se actualizó, degradó o modificó
8. subscription.cancelled — La suscripción se canceló
9. subscription.expired — La suscripción llegó al final de su plazo

​

Escenarios de pago

1. subscription.active: el mandato se autoriza y la suscripción se activa.
2. payment.succeeded: confirma el primer cobro. Recíbelo entre 2 y 10 minutos después del checkout.

1. Al comenzar 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 aplaza hasta que finalice la prueba.
2. Al finalizar la prueba: se cobra el importe recurrente y recibes payment.succeeded junto con subscription.renewed.

• 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.

1. Fallo de la suscripción

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

2. 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. Si tu negocio tiene un período de gracia, una renovación fallida mueve primero la suscripción a past_due (subscription.past_due), y solo pasa a on_hold (o cancelled, según la configuración del período de gracia) cuando este finaliza. Consulta Estados de la suscripción.
• Cuando una suscripción pasa a estar en espera, no se renovará automáticamente hasta que se actualice el método de pago.

​

subscription.failed frente a subscription.on_hold

​

Gestionar una suscripción en espera

​

Cuándo las suscripciones pasan a estar en espera

• Falla el pago de renovación: falla el cobro automático de renovación debido a fondos insuficientes, una tarjeta vencida o un rechazo bancario
• 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

​

Reactivar suscripciones en espera

1. Crea un cobro por las cantidades pendientes
2. Genera una factura para el cobro
3. Procesa el pago con el nuevo método de pago
4. Reactiva la suscripción al estado active cuando el pago se realiza correctamente

// 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 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

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

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

​

Cambiar planes de suscripción

​

Opciones de prorrateo

​

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 cobro nunca se prorratea
• Cobro 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 de inmediato

​

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 total independientemente del tiempo restante del plan anterior

​

3. difference_immediately

• El cliente paga únicamente la diferencia entre el precio del plan anterior y el nuevo
• El importe no depende de cuándo se realiza el cambio dentro del ciclo. La misma actualización cuesta lo mismo el día 1 y el día 29
• Al actualizar el plan, al cliente se le cobra inmediatamente la diferencia. Por ejemplo, $30/mes → $80/mes = se cobran $50 al instante
• Al degradar el plan, la diferencia de precio se almacena como crédito asociado a la suscripción y se aplica automáticamente a futuras renovaciones. Por ejemplo, $50/mes → $20/mes = se almacenan $30 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 ahora, 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

​

Comportamiento

• Cuando llamas a esta API, Dodo Payments inicia inmediatamente un cobro 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 cobro del nuevo ciclo, el importe restante 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 la diferencia exacta de precio. En las degradaciones, el excedente se almacena 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 aplaza la facturación hasta la siguiente fecha de renovación, que se conserva

​

Procesamiento del cobro

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

​

Suscripciones bajo demanda

​

Aspectos clave de la facturación de suscripciones

​

Referencia de API relacionada