Subscription Upgrade & Downgrade Guide - Dodo Payments Documentation

Change Plan API

Full API docs for updating subscriptions.

Plan Change Preview

See charge amounts before changing plans.

Integration Guide

Step-by-step subscription setup.

What is a subscription upgrade or downgrade?

Changing plans lets you move a customer between subscription tiers or quantities. Use it to:

Align pricing with usage or features
Move from monthly to annual (or vice versa)
Adjust quantity for seat-based products

Plan changes can trigger an immediate charge depending on the proration mode you choose.

When to use plan changes

Upgrade when a customer needs more features, usage, or seats
Downgrade when usage decreases
Migrate users to a new product or price without cancelling their subscription

Plan Change Flow

Prerequisites

Before implementing subscription plan changes, ensure you have:

A Dodo Payments merchant account with active subscription products
API credentials (API key and webhook secret key) from the dashboard
An existing active subscription to modify
Webhook endpoint configured to handle subscription events

For detailed setup instructions, see our Integration Guide.

Step-by-Step Implementation Guide

Follow this comprehensive guide to implement subscription plan changes in your application:

Understand Plan Change Requirements

Before implementing, determine:

Which subscription products can be changed to which others
What proration mode fits your business model
How to handle failed plan changes gracefully
Which webhook events to track for state management

Test plan changes thoroughly in test mode before implementing in production.

Choose Your Proration Strategy

Select the billing approach that aligns with your business needs:

prorated_immediately
difference_immediately
full_immediately
do_not_bill

Best for: SaaS applications wanting to charge fairly for unused time

Calculates exact prorated amount based on remaining cycle time
Charges a prorated amount based on unused time remaining in the cycle
Provides transparent billing to customers

Implement the Change Plan API

Use the Change Plan API to modify subscription details:

subscription_id

string

obrigatório

The ID of the active subscription to modify.

product_id

string

obrigatório

The new product ID to change the subscription to.

quantity

integer

padrão:"1"

Number of units for the new plan (for seat-based products).

proration_billing_mode

string

obrigatório

How to handle immediate billing: prorated_immediately, full_immediately, difference_immediately, or do_not_bill.

addons

array

Optional addons for the new plan. Leaving this empty removes any existing addons.

on_payment_failure

string

Controls behavior when the plan change payment fails:

prevent_change: Keep subscription on current plan until payment succeeds
apply_change (default): Apply plan change immediately regardless of payment outcome

If not specified, uses the business-level default setting.

discount_codes

array

Códigos de desconto empilhados opcionais para aplicar ao novo plano (máximo de 20, aplicados na ordem do array). O comportamento depende do que você passa:

Não fornecido / null — descontos existentes com preserve_on_plan_change=true são preservados se aplicáveis ao novo produto.
[] (array vazio) — remove todos os descontos existentes da assinatura.
["CODE_A", "CODE_B", ...] — substitui quaisquer descontos existentes por este conjunto empilhado.

discount_code

string

obsoleto

Descontinuado — prefira discount_codes para novas integrações. Este campo ainda funciona para compatibilidade com versões anteriores, mas não pode ser combinado com discount_codes na mesma solicitação.

effective_at

string

padrão:"immediately"

Quando aplicar a mudança de plano:

immediately (padrão): Aplica a mudança de plano imediatamente
next_billing_date: Agenda a mudança para a próxima data de cobrança. O cliente mantém o plano atual até o final do período de cobrança.

Use next_billing_date para downgrades para que os clientes mantenham os benefícios do plano atual até o final do período de cobrança.

Handle Webhook Events

Configure o tratamento de webhook para rastrear os resultados das mudanças de plano:

subscription.active: Mudança de plano bem-sucedida, assinatura atualizada
subscription.plan_changed: Plano de assinatura alterado (upgrade/downgrade/atualização de addon)
subscription.on_hold: Cobrança de mudança de plano falhou, assinatura pausada
payment.succeeded: Cobrança imediata para mudança de plano bem-sucedida
payment.failed: Cobrança imediata falhou

Sempre verifique as assinaturas de webhook e implemente o processamento idempotente de eventos.

Update Your Application State

Com base nos eventos de webhook, atualize sua aplicação:

Conceda/revoque recursos com base no novo plano
Atualize o painel do cliente com os detalhes do novo plano
Envie emails de confirmação sobre mudanças de plano
Registre alterações de cobrança para auditoria

Test and Monitor

Teste completamente sua implementação:

Teste todos os modos de rateio com diferentes cenários
Verifique se o manuseio de webhook funciona corretamente
Monitore as taxas de sucesso de mudança de plano
Configure alertas para mudanças de plano falhadas

Sua implementação de mudança de plano de assinatura está agora pronta para uso em produção.

Prever Mudanças de Plano

Antes de confirmar uma mudança de plano, use a API de Pré-visualização para mostrar aos clientes exatamente o que será cobrado:

Node.js SDK
Python SDK

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('Immediate charge:', preview.immediate_charge.summary);
console.log('New plan details:', preview.new_plan);

preview = client.subscriptions.preview_change_plan(
    subscription_id="sub_123",
    product_id="prod_pro",
    quantity=1,
    proration_billing_mode="prorated_immediately"
)

# Show customer the charge before confirming
print("Immediate charge:", preview.immediate_charge.summary)
print("New plan details:", preview.new_plan)

Use a API de pré-visualização para construir diálogos de confirmação que mostrem aos clientes o valor exato que será cobrado antes de confirmarem uma mudança de plano.

API de Mudança de Plano

Use a API de Mudança de Plano para modificar o produto, quantidade e comportamento de rateio para uma assinatura ativa.

Exemplos de início rápido

Node.js SDK
Python SDK
Go SDK
HTTP

import DodoPayments from 'dodopayments';

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

async function changePlan() {
  const result = await client.subscriptions.changePlan('sub_123', {
    product_id: 'prod_new',
    quantity: 3,
    proration_billing_mode: 'prorated_immediately',
    on_payment_failure: 'prevent_change', // Optional: control behavior on payment failure
  });
  console.log(result.status, result.invoice_id, result.payment_id);
}

changePlan();

import os
from dodopayments import DodoPayments

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

result = client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="prod_new",
    quantity=3,
    proration_billing_mode="prorated_immediately",
    on_payment_failure="prevent_change",  # Optional: control behavior on payment failure
)
print(result.status, result.get("invoice_id"), result.get("payment_id"))

package main

import (
  "context"
  "fmt"
  "github.com/dodopayments/dodopayments-go"
  "github.com/dodopayments/dodopayments-go/option"
)

func main() {
  client := dodopayments.NewClient(option.WithBearerToken("YOUR_TOKEN"))
  res, err := client.Subscriptions.ChangePlan(context.TODO(), dodopayments.SubscriptionChangePlanParams{
    SubscriptionID: dodopayments.F("sub_123"),
    ProductID:             dodopayments.F("prod_new"),
    Quantity:              dodopayments.F(int64(3)),
    ProrationBillingMode:  dodopayments.F(dodopayments.SubscriptionChangePlanParamsProrationBillingModeProratedImmediately),
    OnPaymentFailure:      dodopayments.F(dodopayments.OnPaymentFailurePreventChange), // Optional
  })
  if err != nil { panic(err) }
  fmt.Println(res.Status, res.InvoiceID, res.PaymentID)
}

curl -X POST "$DODO_API_BASE/subscriptions/sub_123/change-plan" \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_new",
    "quantity": 3,
    "proration_billing_mode": "prorated_immediately",
    "on_payment_failure": "prevent_change"
  }'

Success

{
  "status": "processing",
  "subscription_id": "sub_123",
  "invoice_id": "inv_789",
  "payment_id": "pay_456",
  "proration_billing_mode": "prorated_immediately"
}

Campos como invoice_id e payment_id são retornados apenas quando uma cobrança imediata e/ou fatura é criada durante a mudança de plano. Sempre dependa de eventos de webhook (e.g., payment.succeeded, subscription.plan_changed) para confirmar os resultados.

Se a cobrança imediata falhar, a assinatura pode se mover para subscription.on_hold até que o pagamento seja bem-sucedido.

Gerenciando Addons

Ao alterar planos de assinatura, você também pode modificar addons:

// Add addons to the new plan
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [
    { addon_id: 'addon_123', quantity: 2 }
  ]
});

// Remove all existing addons
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [] // Empty array removes all existing addons
});

Os addons são incluídos no cálculo de rateio e serão cobrados de acordo com o modo de rateio selecionado.

Aplicando Códigos de Desconto

Você pode aplicar um ou mais códigos de desconto empilhados ao alterar planos de assinatura (máximo de 20, aplicados na ordem do array). Isso é útil para oferecer preços promocionais em upgrades ou migrações.

Node.js SDK
Python SDK
HTTP

// Apply stacked discount codes during plan change
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_codes: ['UPGRADE20']
});

# Apply stacked discount codes during plan change
client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="prod_pro",
    quantity=1,
    proration_billing_mode="prorated_immediately",
    discount_codes=["UPGRADE20"]
)

curl -X POST "$DODO_API_BASE/subscriptions/sub_123/change-plan" \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_pro",
    "quantity": 1,
    "proration_billing_mode": "prorated_immediately",
    "discount_codes": ["UPGRADE20"]
  }'

Comportamento do desconto na mudança de plano

`discount_codes` valor	Comportamento
Não fornecido / `null`	Descontos existentes com `preserve_on_plan_change=true` são automaticamente preservados se aplicáveis ao novo produto.
`[]` (array vazio)	Todos os descontos existentes são removidos da assinatura.
`["CODE_A", "CODE_B", ...]`	Substitui quaisquer descontos existentes por este conjunto empilhado, validado e aplicado na ordem do array.

O campo singular discount_code neste endpoint está descontinuado, mas ainda funciona para compatibilidade com versões anteriores — integrações existentes não precisam mudar imediatamente. Não pode ser combinado com discount_codes na mesma solicitação. Migre para a forma de array quando conveniente.

Use a API de Pré-visualização de Mudança de Plano com discount_codes para mostrar aos clientes exatamente quanto eles economizarão antes de confirmar a mudança de plano.

Modos de Rateio

Escolha como cobrar o cliente ao mudar de plano:

`prorated_immediately`

Cobra pela diferença parcial do ciclo atual
Se estiver em teste, cobra imediatamente e muda para o novo plano agora
Downgrade: pode gerar um crédito rateado aplicado a futuras renovações

`full_immediately`

Cobra o valor total do novo plano imediatamente
Ignora o tempo restante do antigo plano

Créditos criados por downgrades usando difference_immediately são específicos da assinatura e distintos de direitos de Faturamento Baseado em Crédito. Aplica-se automaticamente a futuras renovações da mesma assinatura e não são transferíveis entre assinaturas.

`difference_immediately`

Upgrade: cobra imediatamente a diferença de preço entre os planos antigo e novo
Downgrade: adiciona valor restante como crédito interno à assinatura e aplica automaticamente nas renovações

`do_not_bill`

Nenhuma cobrança ou crédito é calculado
O cliente muda para o novo plano imediatamente sem ajuste de cobrança
O ciclo de cobrança permanece inalterado
Melhor para migrações de cortesia, trocas de planos gratuitos ou absorção de diferenças de custo

Recurso	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
Cobrança por upgrade	Diferença rateada para dias restantes	Diferença total de preço entre planos	Preço total do novo plano	Sem cobrança
Crédito por downgrade	Crédito rateado para dias restantes	Diferença total de preço como crédito	Sem crédito	Sem crédito
Ciclo de cobrança	Inalterado	Inalterado	Reinicia para hoje	Inalterado
Comportamento de teste	Termina teste, cobra imediatamente	Termina teste, cobra imediatamente	Termina teste, cobra valor total	Termina teste, sem cobrança
Melhor para	Cobrança justa baseada no tempo	Matemática simples de upgrade/downgrade	Reinício de ciclos de cobrança	Migrações gratuitas ou trocas de cortesia
Complexidade	Média (cálculo de dia)	Baixa (subtração simples)	Baixa (cobrança total)	Nenhuma

Exemplos de cenários

Use esses números canônicos de forma consistente:

Plano atual: Básico a $30/mês
Objetivo de upgrade: Pro a $80/mês
Objetivo de downgrade (de Pro): Inicial a $20/mês
Ciclo de cobrança: 30 dias, iniciado em 1º de janeiro
Mudança de plano ocorre em 16 de janeiro (15 dias restantes, 15 dias usados)

Upgrade: Basic ($30) → Pro ($80) with prorated_immediately

Step 1: Calculate unused credit from current plan
  Unused days = 15 out of 30 days
  Credit = $30 × (15/30) = $15.00

Step 2: Calculate prorated cost of new plan
  Remaining days = 15 out of 30 days
  New plan cost = $80 × (15/30) = $40.00

Step 3: Calculate immediate charge
  Charge = New plan cost − Credit
  Charge = $40.00 − $15.00 = $25.00

→ Customer pays $25.00 now
→ Next renewal (Feb 1): $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
})

Downgrade: Pro ($80) → Starter ($20) with prorated_immediately

Step 1: Calculate unused credit from current plan
  Unused days = 15 out of 30 days
  Credit = $80 × (15/30) = $40.00

Step 2: Calculate prorated cost of new plan
  Remaining days = 15 out of 30 days
  New plan cost = $20 × (15/30) = $10.00

Step 3: Calculate credit balance
  Credit = $40.00 − $10.00 = $30.00

→ No charge — $30.00 credit added to subscription
→ Credit auto-applies to future renewals
→ Next renewal (Feb 1): $20.00 − $30.00 credit = $0.00
→ Following renewal (Mar 1): $20.00 − $10.00 remaining credit = $10.00

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_starter',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
})

Upgrade: Basic ($30) → Pro ($80) with difference_immediately

Immediate charge = New plan price − Old plan price
                 = $80 − $30
                 = $50.00

→ Customer pays $50.00 now (regardless of cycle position)
→ Next renewal (Feb 1): $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
})

Downgrade: Pro ($80) → Starter ($20) with difference_immediately

Credit = Old plan price − New plan price
       = $80 − $20
       = $60.00

→ No charge — $60.00 credit added to subscription
→ Credit auto-applies to future renewals
→ Next renewal: $20.00 − $20.00 (from credit) = $0.00
→ Following renewal: $20.00 − $20.00 (from credit) = $0.00
→ Third renewal: $20.00 − $20.00 (from remaining credit) = $0.00

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_starter',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
})

Upgrade: Basic ($30) → Pro ($80) with full_immediately

Immediate charge = Full new plan price = $80.00

→ Customer pays $80.00 now
→ No credit for unused time on old plan
→ Billing cycle resets to today (January 16)
→ Next renewal: February 16 at $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'full_immediately'
})

Mid-cycle upgrade with add-ons using prorated_immediately

Current: Basic plan ($30/month), no add-ons
New: Pro plan ($80/month) + Extra Seats add-on ($10/seat × 3 seats = $30/month)
Change on day 16 of 30 (15 days remaining)

Step 1: Credit from current plan
  Credit = $30 × (15/30) = $15.00

Step 2: Prorated cost of new plan + add-ons
  New plan = $80 × (15/30) = $40.00
  Add-ons = $30 × (15/30) = $15.00
  Total new = $55.00

Step 3: Immediate charge
  Charge = $55.00 − $15.00 = $40.00

→ Customer pays $40.00 now
→ Next renewal: $80.00 + $30.00 = $110.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  addons: [
    { addon_id: 'addon_seats', quantity: 3 }
  ]
})

Como cada modo processa a cobrança

Escolha prorated_immediately para contabilidade de tempo justo; escolha full_immediately para reiniciar a cobrança; use difference_immediately para upgrades simples e crédito automático em downgrades; ou use do_not_bill para mudar planos sem qualquer ajuste de cobrança.

Lidando com Falhas de Pagamento

Controle o que acontece quando uma cobrança de mudança de plano falha usando o parâmetro on_payment_failure.

Modos de Falha de Pagamento

prevent_change (Recommended for critical upgrades)
apply_change (Default)

Comportamento: Mantenha a assinatura em seu plano atual até que o pagamento seja bem-sucedido.

A mudança de plano é marcada como “pendente”
O cliente mantém acesso ao seu plano atual
A assinatura muda para o estado active apenas após o pagamento bem-sucedido
Útil quando você quer garantir o pagamento antes de conceder recursos atualizados

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  on_payment_failure: 'prevent_change'
});

Comportamento: Aplique a mudança de plano imediatamente independentemente do resultado do pagamento.

A mudança de plano é aplicada mesmo se o pagamento falhar
O cliente obtém acesso imediato ao novo plano
A assinatura pode se mover para on_hold se o pagamento falhar
Bom para upgrades não críticos ou quando você confia no cliente

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  on_payment_failure: 'apply_change' // This is the default
});

Se não especificado, o parâmetro on_payment_failure usa a configuração padrão do nível de negócio configurada no painel.

Quando Usar Cada Modo

Cenário	Modo Recomendado	Razão
Atualização para recursos premium	`prevent_change`	Garantir pagamento antes de conceder acesso
Aumento de quantidade (mais assentos)	`prevent_change`	Prevenir uso sem pagamento
Downgrade de planos	`apply_change`	Cliente está reduzindo despesas
Clientes corporativos confiáveis	`apply_change`	Menor risco de falta de pagamento
Conversão de teste para pago	`prevent_change`	Momento crítico de pagamento

Lidando com Webhooks

Acompanhe o estado da assinatura através de webhooks para confirmar mudanças de plano e pagamentos.

Tipos de eventos a serem tratados

subscription.active: assinatura ativada
subscription.plan_changed: plano de assinatura alterado (upgrade/downgrade/mudanças de addon)
subscription.on_hold: cobrança falhou, assinatura pausada
subscription.renewed: renovação bem-sucedida
payment.succeeded: pagamento para mudança de plano ou renovação bem-sucedido
payment.failed: pagamento falhou

Recomendamos dirigir a lógica de negócios a partir de eventos de assinatura e usar eventos de pagamento para confirmação e reconciliação.

Verifique assinaturas e gerencie intenções

Next.js Route Handler
Express.js

import { NextRequest, NextResponse } from 'next/server';

export async function POST(req) {
  const webhookId = req.headers.get('webhook-id');
  const webhookSignature = req.headers.get('webhook-signature');
  const webhookTimestamp = req.headers.get('webhook-timestamp');
  const secret = process.env.DODO_WEBHOOK_SECRET;

  const payload = await req.text();
  // verifySignature is a placeholder – in production, use a Standard Webhooks library
  const { valid, event } = await verifySignature(
    payload,
    { id: webhookId, signature: webhookSignature, timestamp: webhookTimestamp },
    secret
  );
  if (!valid) return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });

  switch (event.type) {
    case 'subscription.active':
      // mark subscription active in your DB
      break;
    case 'subscription.plan_changed':
      // refresh entitlements and reflect the new plan in your UI
      break;
    case 'subscription.on_hold':
      // notify user to update payment method
      break;
    case 'subscription.renewed':
      // extend access window
      break;
    case 'payment.succeeded':
      // reconcile payment for plan change
      break;
    case 'payment.failed':
      // log and alert
      break;
    default:
      // ignore unknown events
      break;
  }

  return NextResponse.json({ received: true });
}

import express from 'express';

const app = express();
app.post('/webhooks/dodo', express.raw({ type: 'application/json' }), async (req, res) => {
  const webhookId = req.header('webhook-id');
  const webhookSignature = req.header('webhook-signature');
  const webhookTimestamp = req.header('webhook-timestamp');
  const secret = process.env.DODO_WEBHOOK_SECRET;
  const payload = req.body.toString('utf8');

  const { valid, event } = await verifySignature(
    payload,
    { id: webhookId, signature: webhookSignature, timestamp: webhookTimestamp },
    secret
  );
  if (!valid) return res.status(400).send('Invalid signature');

  // handle events like above
  res.json({ received: true });
});

app.listen(3000);

Para esquemas detalhados de payload, veja os Payloads de Webhook de Assinatura e Payloads de Webhook de Pagamento.

Melhores Práticas

Siga estas recomendações para mudanças de plano de assinatura confiáveis:

Estratégia de Mudança de Plano

Teste completamente: Sempre teste mudanças de plano em modo de teste antes da produção
Escolha o rateio com cuidado: Selecione o modo de rateio que alinha com seu modelo de negócios
Lide graciosamente com falhas: Implemente tratamento de erro adequado e lógica de retry
Monitore taxas de sucesso: Acompanhe taxas de sucesso/falha de mudança de plano e investigue problemas

Implementação de Webhook

Verifique assinaturas: Sempre valide assinaturas de webhook para garantir autenticidade
Implemente idempotência: Lide graciosamente com eventos duplicados de webhook
Processe de forma assíncrona: Não bloqueie respostas de webhook com operações pesadas
Registre tudo: Mantenha logs detalhados para depuração e auditoria

Experiência do Usuário

Comunique claramente: Informe os clientes sobre mudanças de cobrança e tempos
Forneça confirmações: Envie confirmações por email para mudanças de plano bem-sucedidas
Lide com casos extremos: Considere períodos de teste, rateios e pagamentos falhados
Atualize a UI imediatamente: Reflita mudanças de plano na interface do seu aplicativo

Problemas Comuns e Soluções

Resolva problemas típicos encontrados durante mudanças de plano de assinatura:

Charge created but subscription not updated

Sintomas: Chamada API bem-sucedida, mas assinatura permanece no plano antigoCausas comuns:

Processamento de Webhook falhou ou foi atrasado
Estado da aplicação não atualizado após receber webhooks
Problemas de transação de banco de dados durante atualização de estado

Soluções:

Implemente um manuseio robusto de webhook com lógica de retry
Use operações idempotentes para atualizações de estado
Adicione monitoramento para detectar e alertar sobre eventos de webhook perdidos
Verifique se o endpoint de webhook está acessível e respondendo corretamente

Credits not applied after downgrade

Sintomas: Cliente faz downgrade mas não vê saldo de créditoCausas comuns:

Expectativas do modo de rateio: downgrades creditam a diferença total do preço do plano com difference_immediately, enquanto prorated_immediately cria um crédito rateado com base no tempo restante no ciclo
Créditos são específicos da assinatura e não se transferem entre assinaturas
Saldo de crédito não visível no painel do cliente

Soluções:

Use difference_immediately para downgrades quando você quer créditos automáticos
Explique aos clientes que os créditos se aplicam a futuras renovações da mesma assinatura
Implemente um portal do cliente para mostrar saldos de crédito
Verifique a pré-visualização da próxima fatura para ver créditos aplicados

Webhook signature verification fails

Sintomas: Eventos de webhook rejeitados devido a assinatura inválidaCausas comuns:

Chave secreta de webhook incorreta
Corpo da solicitação bruto modificado antes da verificação de assinatura
Algoritmo de verificação de assinatura errado

Soluções:

Verifique se você está usando o correto DODO_WEBHOOK_SECRET do painel
Leia o corpo da solicitação bruto antes de qualquer middleware de análise JSON
Use a biblioteca padrão de verificação de webhook para sua plataforma
Teste a verificação de assinatura de webhook no ambiente de desenvolvimento

Plan change fails with 422 error

Sintomas: API retorna erro 422 Entidade Não ProcessávelCausas comuns:

ID de assinatura ou ID de produto inválido
Assinatura não está em estado ativo
Parâmetros obrigatórios ausentes
Produto não disponível para mudanças de plano

Soluções:

Verifique se a assinatura existe e está ativa
Verifique se o ID do produto é válido e disponível
Certifique-se de que todos os parâmetros obrigatórios são fornecidos
Revise a documentação da API para requisitos de parâmetro

Immediate charge fails during plan change

Sintomas: Mudança de plano iniciada mas cobrança imediata falhaCausas comuns:

Fundos insuficientes no método de pagamento do cliente
Método de pagamento expirado ou inválido
Banco recusou a transação
Detecção de fraude bloqueou a cobrança

Soluções:

Lide apropriadamente com eventos de webhook payment.failed
Notifique o cliente para atualizar o método de pagamento
Implemente lógica de retry para falhas temporárias
Considere permitir mudanças de plano com cobranças imediatas falhadas

Subscription on hold after plan change

Sintomas: Cobrança da mudança de plano falha e assinatura se move para estado on_holdO que acontece: Quando uma cobrança de mudança de plano falha, a assinatura é automaticamente colocada em estado on_hold. A assinatura não será renovada automaticamente até que o método de pagamento seja atualizado.Solução: Atualize o método de pagamento para reativar a assinaturaPara reativar uma assinatura do estado on_hold após uma mudança de plano falhada:

Atualize o método de pagamento usando a API de Atualização de Método de Pagamento
Criação automática de cobrança: A API cria automaticamente uma cobrança para as dívidas restantes
Geração de fatura: Uma fatura é gerada para a cobrança
Processamento de pagamento: O pagamento é processado usando o novo método de pagamento
Reativação: Após o pagamento bem-sucedido, a assinatura é reativada para o estado active

// Reactivate subscription from on_hold after failed plan change
async function reactivateAfterFailedPlanChange(subscriptionId) {
  // Update payment method - automatically creates charge for remaining dues
  const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
    type: 'new',
    return_url: 'https://example.com/return'
  });
  
  if (response.payment_id) {
    console.log('Charge created for remaining dues:', response.payment_id);
    console.log('Payment link:', response.payment_link);
    
    // Redirect customer to payment_link to complete payment
    // Monitor webhooks for:
    // 1. payment.succeeded - charge succeeded
    // 2. subscription.active - subscription reactivated
  }
  
  return response;
}

// Or use existing payment method if available
async function reactivateWithExistingPaymentMethod(subscriptionId, paymentMethodId) {
  const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
    type: 'existing',
    payment_method_id: paymentMethodId
  });
  
  // Monitor webhooks for payment.succeeded and subscription.active
  return response;
}

Eventos de webhook para monitorar:

subscription.on_hold: Assinatura colocada em espera (recebido quando cobrança de mudança de plano falha)
payment.succeeded: Pagamento pelas dívidas restantes bem-sucedido (após atualização do método de pagamento)
subscription.active: Assinatura reativada após pagamento bem-sucedido

Melhores práticas:

Notifique os clientes imediatamente quando uma cobrança de mudança de plano falhar
Forneça instruções claras sobre como atualizar seu método de pagamento
Monitore eventos de webhook para acompanhar o status de reativação
Considere implementar lógica de retry automático para falhas temporárias de pagamento

Update Payment Method API Reference

Veja a documentação completa da API para atualização de métodos de pagamento e reativação de assinaturas.

Testando Sua Implementação

Siga estas etapas para testar completamente sua implementação de mudança de plano de assinatura:

Set up test environment

Use chaves de API de teste e produtos de teste
Crie assinaturas de teste com diferentes tipos de plano
Configure endpoint de webhook de teste
Configure monitoramento e registro

Test different proration modes

Teste prorated_immediately com várias posições de ciclo de cobrança
Teste difference_immediately para upgrades e downgrades
Teste full_immediately para reiniciar ciclos de cobrança
Teste do_not_bill para trocas de plano sem cobrança/crédito
Verifique se os cálculos de crédito estão corretos

Test webhook handling

Verifique se todos os eventos relevantes de webhook são recebidos
Teste a verificação de assinatura do webhook
Lide graciosamente com eventos duplicados de webhook
Teste cenários de falha de processamento de webhook

Test error scenarios

Teste com IDs de assinatura inválidos
Teste com métodos de pagamento expirados
Teste falhas de rede e tempos de espera
Teste com fundos insuficientes

Monitor in production

Configure alertas para mudanças de plano falhadas
Monitore tempos de processamento de webhook
Acompanhe taxas de sucesso de mudança de plano
Revise tickets de suporte ao cliente para questões de mudança de plano

Tratamento de Erros

Trate adequadamente erros comuns de API em sua implementação:

Códigos de Status HTTP

200 OK

Solicitação de mudança de plano processada com sucesso. A assinatura está sendo atualizada e o processamento de pagamento foi iniciado.

400 Bad Request

Parâmetros de solicitação inválidos. Verifique se todos os campos obrigatórios são fornecidos e formatados corretamente.

401 Unauthorized

Chave de API inválida ou ausente. Verifique se o DODO_PAYMENTS_API_KEY está correto e possui permissões adequadas.

404 Not Found

ID de assinatura não encontrado ou não pertence à sua conta.

422 Unprocessable Entity

A assinatura não pode ser alterada (por exemplo, já cancelada, produto não disponível, etc.).

500 Internal Server Error

Erro de servidor ocorreu. Tente novamente após um breve atraso.

Formato de Resposta de Erro

{
  "error": {
    "code": "subscription_not_found",
    "message": "The subscription with ID 'sub_123' was not found",
    "details": {
      "subscription_id": "sub_123"
    }
  }
}

Próximos Passos

Reveja a API de Mudança de Plano
Explore Faturamento Baseado em Crédito
Implemente alertas para subscription.on_hold
Confira nosso Guia de Integração de Webhooks

Documentation Index

Change Plan API

Plan Change Preview

Integration Guide

​What is a subscription upgrade or downgrade?

​When to use plan changes

​Plan Change Flow

​Prerequisites

​Step-by-Step Implementation Guide

​Prever Mudanças de Plano

​API de Mudança de Plano

​Exemplos de início rápido

​Gerenciando Addons

​Aplicando Códigos de Desconto

​Comportamento do desconto na mudança de plano

​Modos de Rateio

​prorated_immediately

​full_immediately

​difference_immediately

​do_not_bill

​Exemplos de cenários

​Como cada modo processa a cobrança

​Lidando com Falhas de Pagamento

​Modos de Falha de Pagamento

​Quando Usar Cada Modo

​Lidando com Webhooks

​Tipos de eventos a serem tratados

​Verifique assinaturas e gerencie intenções

​Melhores Práticas

​Estratégia de Mudança de Plano

​Implementação de Webhook

​Experiência do Usuário

​Problemas Comuns e Soluções

Update Payment Method API Reference

​Testando Sua Implementação

​Tratamento de Erros

​Códigos de Status HTTP

​Formato de Resposta de Erro

​Próximos Passos

What is a subscription upgrade or downgrade?

When to use plan changes

Plan Change Flow

Prerequisites

Step-by-Step Implementation Guide

Prever Mudanças de Plano

API de Mudança de Plano

Exemplos de início rápido

Gerenciando Addons

Aplicando Códigos de Desconto

Comportamento do desconto na mudança de plano

Modos de Rateio

`prorated_immediately`

`full_immediately`

`difference_immediately`

`do_not_bill`

Exemplos de cenários

Como cada modo processa a cobrança

Lidando com Falhas de Pagamento

Modos de Falha de Pagamento

Quando Usar Cada Modo

Lidando com Webhooks

Tipos de eventos a serem tratados

Verifique assinaturas e gerencie intenções

Melhores Práticas

Estratégia de Mudança de Plano

Implementação de Webhook

Experiência do Usuário

Problemas Comuns e Soluções

Testando Sua Implementação

Tratamento de Erros

Códigos de Status HTTP

Formato de Resposta de Erro

Próximos Passos