Subscription Integration Guide - Dodo Payments Documentation

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"
}

Redirect the customer to checkout_url.

Webhooks

When integrating subscriptions, you’ll receive webhooks to track the subscription lifecycle. These webhooks help you manage subscription states and payment scenarios effectively. To set up your webhook endpoint, please follow our Detailed Integration Guide.

Subscription Event Types

The following webhook events track subscription status changes:

subscription.active - Subscription is successfully activated.
subscription.updated - Subscription object was updated (fires on any field change).
subscription.on_hold - Subscription is put on hold due to failed renewal.
subscription.failed - Subscription creation failed during mandate creation.
subscription.renewed - Subscription is renewed for the next billing period.

For reliable subscription lifecycle management, we recommend tracking these subscription events.

Use subscription.updated to get real-time notifications about any subscription changes, keeping your application state in sync without polling the API.

Payment Scenarios

Successful Payment Flow When a payment succeeds, you’ll receive the following webhooks:

subscription.active - Indicates subscription activation
payment.succeeded - Confirms the initial payment:
- For immediate billing (0 trial days): Expect within 2-10 minutes
- For trial days: whenever that ends
subscription.renewed - Indicates payment deduction and renewal for next cycle. (Basically, whenever payment gets deducted for subscription products, you will get subscription.renewed webhook along with payment.succeeded)

Payment Failure Scenarios

Subscription Failure

subscription.failed - Subscription creation failed due to failure to create a mandate.
payment.failed - Indicates failed payment.

Subscription On Hold

subscription.on_hold - Subscription is put on hold due to failed renewal payment or failed plan change charge.
When a subscription goes on hold, it will not renew automatically until the payment method is updated.

Best Practice: To simplify implementation, we recommend primarily tracking subscription events for managing the subscription lifecycle.

Para um tutorial completo sobre leitura de error_code/error_message, decidindo quando tentar novamente e informando falhas aos clientes, consulte Tratar Falhas de Pagamento.

`subscription.failed` vs. `subscription.on_hold`

Esses dois eventos são fáceis de confundir, mas requerem manejos muito diferentes:

Evento	Quando ocorre	Status	Recuperável?	O que fazer
`subscription.failed`	O mandato inicial não pôde ser criado na criação da assinatura	`failed`	Não — terminal	Não conceda acesso. Peça ao cliente para iniciar uma nova assinatura com um método de pagamento diferente.
`subscription.on_hold`	Um pagamento de renovação (ou cobrança de mudança de plano) falhou em uma assinatura já ativa	`on_hold`	Sim	Recupere atualizando o método de pagamento; veja Tratamento de Assinatura Em Suspensão abaixo.

subscription.failed é terminal — a assinatura não pode ser reativada. O cliente deve criar uma nova assinatura. Nunca conceda direitos quando este evento ocorrer.

Tratamento de Assinatura Em Suspensão

Quando uma assinatura entra no estado on_hold, é necessário atualizar o método de pagamento para reativá-la. Esta seção explica quando assinaturas são colocadas em suspensão e como tratá-las.

Quando Assinaturas São Colocadas Em Suspensão

Uma assinatura é colocada em suspensão quando:

Pagamento de renovação falha: A cobrança automática de renovação falha devido a fundos insuficientes, cartão expirado ou recusa do banco
Cobrança de mudança de plano falha: Uma cobrança imediata durante upgrade/downgrade de plano falha
Autorização do método de pagamento falha: O método de pagamento não pode ser autorizado para cobranças recorrentes

Assinaturas em estado on_hold não se renovarão automaticamente. É necessário atualizar o método de pagamento para reativar a assinatura.

Reativando Assinaturas de Em Suspensão

Para reativar uma assinatura do estado on_hold, use a API de Atualização de Método de Pagamento. Isso automaticamente:

Cria uma cobrança para os valores devidos
Gera uma fatura para a cobrança
Processa o pagamento usando o novo método de pagamento
Reativa a assinatura para o estado active após o pagamento bem-sucedido

Handle subscription.on_hold webhook

Quando você recebe um webhook subscription.on_hold, atualize o estado do seu aplicativo e notifique o 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

Quando o cliente estiver pronto para atualizar seu método de pagamento, chame a API de Atualização de Método de Pagamento:

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

Você também pode usar um ID de método de pagamento existente se o cliente tiver métodos de pagamento salvos:

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

Monitor webhook events

Após atualizar o método de pagamento, monitore estes eventos de webhook:

payment.succeeded - A cobrança pelos valores devidos foi bem-sucedida
subscription.active - A assinatura foi reativada

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.'
  });
}

Exemplo de Payload de Evento de Assinatura

Propriedade	Tipo	Obrigatório	Descrição
`business_id`	string	Sim	O identificador único para o negócio
`timestamp`	string	Sim	O carimbo de data e hora de quando o evento ocorreu (não necessariamente o mesmo que quando foi entregue)
`type`	string	Sim	O tipo de evento. Veja Tipos de Evento
`data`	object	Sim	O payload principal de dados. Veja Objeto de Dados

Mudança de Planos de Assinatura

Você pode fazer upgrade ou downgrade de um plano de assinatura usando o endpoint da API de mudança de plano. Isso permite modificar o produto, a quantidade da assinatura e lidar com a prorrateação.

Change Plan API Reference

Para informações detalhadas sobre a mudança de planos de assinatura, por favor, consulte nossa documentação da API de Mudança de Plano.

Opções de Prorrateação

Ao mudar planos de assinatura, você tem duas opções para lidar com a cobrança imediata:

1. `prorated_immediately`

Calcula o valor prorrateado com base no tempo restante no ciclo de faturamento atual
Cobra do cliente apenas a diferença entre o plano antigo e o novo
Durante um período de teste, isso mudará imediatamente o usuário para o novo plano, cobrando do cliente imediatamente

2. `full_immediately`

Cobra do cliente o valor total da assinatura para o novo plano
Ignora qualquer tempo restante ou créditos do plano anterior
Útil quando você deseja reiniciar o ciclo de faturamento ou cobrar o valor total independente da prorrateação

3. `difference_immediately`

Ao fazer upgrade, o cliente é imediatamente cobrado pela diferença entre os valores dos dois planos.
Por exemplo, se o plano atual é de 30 Dólares e o cliente faz upgrade para 80 Dólares, ele é cobrado $50 instantaneamente.
Ao fazer downgrade, o valor não utilizado do plano atual é adicionado como crédito interno e aplicado automaticamente nas futuras renovações da assinatura.
Por exemplo, se o plano atual é de 50 Dólares e o cliente muda para um plano de 20 Dólares, os $30 restantes são creditados e usados no próximo ciclo de faturamento.

Comportamento

Quando você invoca esta API, o Dodo Payments inicia imediatamente uma cobrança com base na opção de prorrateação selecionada
Se a mudança de plano for um downgrade e você usar prorated_immediately, os créditos serão calculados automaticamente e adicionados ao saldo de crédito da assinatura. Esses créditos são específicos para aquela assinatura e só serão usados para compensar futuros pagamentos recorrentes da mesma assinatura
A opção full_immediately ignora cálculos de crédito e cobra o valor completo do novo plano

Escolha sua opção de prorrateação com cuidado: Use prorated_immediately para uma cobrança justa que contabilize o tempo não utilizado, ou full_immediately quando você quiser cobrar o valor completo do novo plano independentemente do ciclo de faturamento atual.

Processamento de Cobranças

A cobrança imediata iniciada na mudança de plano geralmente completa o processamento em menos de 2 minutos
Se essa cobrança imediata falhar por qualquer motivo, a assinatura é automaticamente colocada em suspensão até que o problema seja resolvido

Assinaturas Sob Demanda

Assinaturas sob demanda permitem cobrar clientes de forma flexível, não apenas em um cronograma fixo. Este recurso está disponível para todas as contas.

Para criar uma assinatura sob demanda: Para criar uma assinatura sob demanda, use o endpoint da API POST /subscriptions e inclua o campo on_demand em seu corpo de solicitação. Isso permite autorizar um método de pagamento sem uma cobrança imediata, ou definir um preço inicial personalizado. Para cobrar uma assinatura sob demanda: Para cobranças subsequentes, use o endpoint POST /subscriptions//charge e especifique o valor a ser cobrado do cliente para essa transação.

Para um guia completo, passo a passo — incluindo exemplos de solicitação/resposta, políticas de tentativa segura, e tratamento de webhooks — veja o Guia de Assinaturas Sob Demanda.

Referência da API Relacionada

Create Subscription

Referência da API para criar produtos de assinatura e gerenciar o ciclo de vida da assinatura

Change Subscription Plan

Referência da API para fazer upgrade, downgrade ou alterar planos de assinatura com opções de prorrateação

Update Payment Method

Referência da API para atualizar métodos de pagamento e reativar assinaturas em suspensão

Patch Subscription

Referência da API para atualizar detalhes e configurações de assinatura

​Prerequisites

​API Integration

​Checkout Sessions

​API Response

​Webhooks

​Subscription Event Types

​Payment Scenarios

​subscription.failed vs. subscription.on_hold

​Tratamento de Assinatura Em Suspensão

​Quando Assinaturas São Colocadas Em Suspensão

​Reativando Assinaturas de Em Suspensão

​Exemplo de Payload de Evento de Assinatura

​Mudança de Planos de Assinatura

Change Plan API Reference

​Opções de Prorrateação

​1. prorated_immediately

​2. full_immediately

​3. difference_immediately

​Comportamento

​Processamento de Cobranças

​Assinaturas Sob Demanda

​Referência da API Relacionada

Create Subscription

Change Subscription Plan

Update Payment Method

Patch Subscription

Prerequisites

API Integration

Checkout Sessions

API Response

Webhooks

Subscription Event Types

Payment Scenarios

`subscription.failed` vs. `subscription.on_hold`

Tratamento de Assinatura Em Suspensão

Quando Assinaturas São Colocadas Em Suspensão

Reativando Assinaturas de Em Suspensão

Exemplo de Payload de Evento de Assinatura

Mudança de Planos de Assinatura

Opções de Prorrateação

1. `prorated_immediately`

2. `full_immediately`

3. `difference_immediately`

Comportamento

Processamento de Cobranças

Assinaturas Sob Demanda

Referência da API Relacionada