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.

O que é um upgrade ou downgrade de assinatura?

Altere o plano de assinatura de um cliente para movê-lo entre níveis, ajustar a quantidade de produtos baseados em assentos ou migrar para um novo produto. A API calcula automaticamente os valores proporcionais e as cobranças com base no seu modo de cobrança escolhido.

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

Quando usar alterações de plano

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

Para obter instruções detalhadas de configuração, consulte o Guia de integração.

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

Ideal para: aplicações SaaS que desejam creditar o tempo não utilizado do plano antigo.

Credita a parte não utilizada do ciclo atual, proporcionalmente ao tempo restante
Em seguida, cobra um ciclo completo no novo plano — o preço do novo plano nunca é calculado proporcionalmente
Cobrança líquida = ciclo completo do novo plano − (fração restante × ciclo completo do plano antigo)

Implement the Change Plan API

Use the Change Plan API to modify subscription details:

string

obrigatório

The ID of the active subscription to modify.

string

obrigatório

O novo ID do produto para alterar a assinatura.

integer

obrigatório

Número de unidades do novo plano (para produtos baseados em assentos).

string

obrigatório

Como lidar com a cobrança imediata: prorated_immediately, full_immediately, difference_immediately ou do_not_bill.

array

Add-ons opcionais para o novo plano. Omitir este campo, enviar null ou enviar um array vazio remove quaisquer add-ons existentes; portanto, inclua os add-ons atuais para mantê-los.

string

Controla o comportamento quando o pagamento da alteração do plano falha:

prevent_change: mantém a assinatura no plano atual até que o pagamento seja bem-sucedido
apply_change (padrão): aplica a alteração do plano imediatamente, independentemente do resultado do pagamento

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

boolean

Colete o valor da alteração do plano com um link de pagamento em vez de cobrar o método de pagamento salvo da assinatura. O cliente paga em uma página de checkout hospedada.Requer que a empresa tenha o recurso allow_plan_change_via_payment_link (Settings → Subscriptions → Collect Plan Change Payments by Payment Link), effective_at: immediately e on_payment_failure: prevent_change. Consulte Collecting Payment via a Checkout Link. Ignorado pela rota de preview.

string

A URL que recebe o cliente depois que ele paga o link de pagamento. O redirecionamento adiciona subscription_id, payment_id e status. Requer collect_via_payment_link: true; caso contrário, a solicitação falha com 422. Consulte Redirecionando o Cliente Após o Pagamento.

boolean

padrão:"false"

Cancele o link de pagamento não pago de uma alteração de plano pendente, para que esta solicitação o substitua. Um pagamento pago ou em andamento retorna 409. Consulte Substituindo um Link de Pagamento Pendente. Ignorado pela rota de preview.

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ê enviar:

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

string

obsoleto

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

string

padrão:"immediately"

Quando aplicar a alteração do plano:

immediately (padrão): aplica a alteração do plano imediatamente
next_billing_date: agenda a alteração para a próxima data de cobrança. O cliente mantém o plano atual até o fim do período de cobrança. Use esta opção para downgrades, para que os clientes mantenham os benefícios do plano atual até o fim do período de cobrança.

Handle Webhook Events

Configure o tratamento de webhooks para acompanhar os resultados das alterações de plano:

subscription.active: alteração do plano bem-sucedida, assinatura atualizada
subscription.plan_changed: plano da assinatura alterado (upgrade/downgrade/atualização de addon)
subscription.on_hold: cobrança da alteração do plano falhou, renovações interrompidas
payment.succeeded: cobrança imediata da alteração do plano bem-sucedida
payment.failed: cobrança imediata falhou

Sempre verifique as assinaturas dos webhooks 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 dashboard do cliente com os detalhes do novo plano
Envie e-mails de confirmação sobre alterações de plano
Registre as alterações de cobrança para fins de auditoria

Test and Monitor

Teste completamente sua implementação:

Teste todos os modos de proration com diferentes cenários
Verifique se o tratamento de webhooks funciona corretamente
Monitore as taxas de sucesso das alterações de plano
Configure alertas para alterações de plano malsucedidas

Sua implementação de alteração de plano da assinatura está pronta para uso em produção.

Visualizar alterações de plano

Antes de confirmar uma alteração de plano, use a Preview API para mostrar aos clientes exatamente quanto será cobrado:

Node.js SDK
Python SDK

const preview = await client.subscriptions.previewChangePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

// Show customer the charge before confirming
console.log('Immediate charge:', preview.immediate_charge.summary.total_amount, preview.immediate_charge.summary.currency);
console.log('New plan details:', preview.new_plan);

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

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

Use a Preview API para criar diálogos de confirmação que mostrem aos clientes o valor exato que será cobrado antes que confirmem uma alteração de plano.

Em immediate_charge.summary, customer_credits é a alteração líquida no saldo de crédito do cliente, na moeda indicada por customer_credits_currency. Essa é a moeda da carteira de créditos do cliente, que corresponde à moeda da assinatura. Ela pode ser diferente de currency do resumo, que se aplica a total_amount e tax. Por exemplo, um cliente que paga em INR em uma assinatura em USD vê os créditos em USD.

Change Plan API

Use a Change Plan API para modificar o produto, a quantidade e o comportamento de proration de uma assinatura ativa.

Exemplos rápidos

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() {
  // change-plan returns 200 with a ChangePlanResponse body (payment_id, payment_link,
  // client_secret, expires_on) — all null for an ordinary off-session change.
  await client.subscriptions.changePlan('sub_123', {
    product_id: 'pdt_new',
    quantity: 3,
    proration_billing_mode: 'prorated_immediately',
    on_payment_failure: 'prevent_change', // Optional: control behavior on payment failure
  });
  console.log('Plan change accepted; awaiting webhooks');
}

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

# change_plan returns 200 with a ChangePlanResponse body (payment_id, payment_link,
# client_secret, expires_on) — all None for an ordinary off-session change.
client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="pdt_new",
    quantity=3,
    proration_billing_mode="prorated_immediately",
    on_payment_failure="prevent_change",  # Optional: control behavior on payment failure
)
print("Plan change accepted; awaiting webhooks")

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"))
  // ChangePlan returns a SubscriptionChangePlanResponse alongside the error.
  _, err := client.Subscriptions.ChangePlan(context.TODO(), "sub_123", dodopayments.SubscriptionChangePlanParams{
    UpdateSubscriptionPlanReq: dodopayments.UpdateSubscriptionPlanReqParam{
      ProductID:            dodopayments.F("pdt_new"),
      Quantity:             dodopayments.F(int64(3)),
      ProrationBillingMode: dodopayments.F(dodopayments.UpdateSubscriptionPlanReqProrationBillingModeProratedImmediately),
      OnPaymentFailure:     dodopayments.F(dodopayments.UpdateSubscriptionPlanReqOnPaymentFailurePreventChange), // Optional
    },
  })
  if err != nil { panic(err) }
  fmt.Println("Plan change applied")
}

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": "pdt_new",
    "quantity": 3,
    "proration_billing_mode": "prorated_immediately",
    "on_payment_failure": "prevent_change"
  }'

Uma alteração de plano bem-sucedida retorna 200 OK imediatamente — antes que qualquer cobrança seja efetivamente liquidada. O conteúdo do corpo (ChangePlanResponse) depende de como a alteração foi coletada:

Caso	`payment_id` / `payment_link` / `client_secret` / `expires_on`
Alteração agendada (`effective_at: next_billing_date`)	Todos `null` — nada é cobrado ainda
`proration_billing_mode: do_not_bill`	Todos `null` — não há nada a cobrar
Cobrança imediata comum (método de pagamento salvo)	Todos `null`
`collect_via_payment_link: true` (link emitido)	Todos preenchidos — identificadores de checkout para o cliente

Esta resposta confirma que a solicitação foi aceita, não que uma cobrança foi bem-sucedida. Para uma cobrança imediata comum, o resultado é resolvido fora da sessão logo após a chamada. Para uma solicitação collect_via_payment_link, a assinatura permanece no plano atual até que o cliente conclua o pagamento.Confirme o resultado por webhook (payment.succeeded, payment.failed, subscription.plan_changed) ou lendo novamente a assinatura com GET /subscriptions/{subscription_id} — consulte O que Acontece Enquanto o Link Não é Pago para o caso de link de pagamento.

Se a cobrança imediata falhar, a assinatura poderá passar para subscription.on_hold até que o pagamento seja bem-sucedido.

Coletando pagamento por meio de um link de checkout

Por padrão, uma alteração imediata de plano cobra diretamente o método de pagamento salvo da assinatura. Defina collect_via_payment_link: true para enviar o cliente a uma página de checkout hospedada — útil quando não há um método de pagamento salvo ou quando você quer que o cliente confirme ativamente o novo preço.

Isso habilita a opção Collect Plan Change Payments by Payment Link em Settings → Subscriptions, que direciona o fluxo de alteração de plano do Customer Portal pelo checkout.

Requisitos

collect_via_payment_link: true só funciona quando todas as condições a seguir são atendidas — caso contrário, a solicitação falha com 422:

A empresa tem o recurso allow_plan_change_via_payment_link habilitado (Settings → Subscriptions → Collect Plan Change Payments by Payment Link).
effective_at é immediately (o padrão). Uma alteração agendada (next_billing_date) nunca precisa de uma página de checkout.
A solicitação define on_payment_failure: prevent_change. Um apply_change explícito falha com 422.

collect_via_payment_link aplica-se a qualquer alteração imediata que resulte em uma cobrança, incluindo downgrades, desde que os requisitos acima sejam atendidos.

Se a alteração resultar em zero ou em um crédito, nenhum link de pagamento será emitido: payment_link e os outros campos de checkout retornam null, e a alteração é aplicada imediatamente. Isso não é um 422. Chame Preview Plan Change primeiro para verificar o valor antes de solicitar um link.

Node.js SDK
Python SDK
HTTP

const response = await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  effective_at: 'immediately',
  on_payment_failure: 'prevent_change',
  collect_via_payment_link: true,
});

// Hand response.payment_link to your frontend and send the customer there
console.log(response.payment_link);

response = client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="pdt_pro",
    quantity=1,
    proration_billing_mode="prorated_immediately",
    effective_at="immediately",
    on_payment_failure="prevent_change",
    collect_via_payment_link=True,
)

# Hand response.payment_link to your frontend and send the customer there
print(response.payment_link)

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": "pdt_pro",
    "quantity": 1,
    "proration_billing_mode": "prorated_immediately",
    "effective_at": "immediately",
    "on_payment_failure": "prevent_change",
    "collect_via_payment_link": true
  }'

Uma solicitação bem-sucedida retorna os identificadores de checkout:

{
  "payment_id": "<payment_id>",
  "payment_link": "https://checkout.dodopayments.com/...",
  "client_secret": "<client_secret>",
  "expires_on": "<expires_on>"
}

O que acontece enquanto o link não é pago

A assinatura permanece no plano atual — product_id, recurring_pre_tax_amount e next_billing_date permanecem inalterados até que o link seja pago.
Uma nova solicitação change-plan é rejeitada com 409 PendingPlanChangeExists enquanto o link estiver pendente. Para substituir a alteração pendente, envie a nova solicitação com cancel_older_payment_link: true. Consulte Substituindo um Link de Pagamento Pendente.
Para tentar novamente após um pagamento recusado, chame change-plan novamente para obter um novo link.
Se o link nunca for pago, ele deixará de funcionar após expires_on — a assinatura ficará automaticamente livre para aceitar uma nova solicitação de alteração de plano pouco depois.
Se já existia uma alteração agendada e você a substituir por cancel_scheduled_change_plan: true, o agendamento original permanece enquanto o link não for pago e só será cancelado quando o link for pago — na mesma transação que aplica o novo plano.

Depois que uma alteração imediata por link de pagamento é emitida, todas as solicitações posteriores de alteração de plano nessa assinatura — incluindo o preview sem efeitos colaterais — são bloqueadas até que o link seja resolvido. Uma solicitação change-plan pode substituir o link definindo cancel_older_payment_link: true. O preview ignora este campo, portanto um preview continua bloqueado.

Redirecionando o cliente após o pagamento

Defina return_url para enviar o cliente de volta ao seu site depois que ele pagar o link:

{
  "product_id": "pdt_pro",
  "quantity": 1,
  "proration_billing_mode": "prorated_immediately",
  "on_payment_failure": "prevent_change",
  "collect_via_payment_link": true,
  "return_url": "https://example.com/billing/done"
}

Após o checkout, o cliente será direcionado para return_url com estes parâmetros de consulta:

Parâmetro	Valor
`subscription_id`	A assinatura à qual a alteração de plano se aplica.
`payment_id`	O pagamento da alteração de plano.
`status`	O status do pagamento da alteração de plano, não da assinatura: `active` quando pago, `failed` quando recusado, `pending` enquanto estiver em andamento.

Quando o pagamento falha, a assinatura permanece ativa no plano atual. O novo plano pode ser aplicado pouco depois do redirecionamento, quando o webhook de pagamento chegar; portanto, leia a assinatura novamente antes de exibir o novo plano. return_url requer collect_via_payment_link: true. Sem ele, a solicitação falha com 422.

Substituindo um link de pagamento pendente

Se o cliente sair do checkout sem pagar, defina cancel_older_payment_link: true na próxima solicitação change-plan. Dodo Payments cancela o link não pago, e a nova alteração de plano substitui a pendente. O link cancelado não aceita mais pagamentos, mesmo em uma página de checkout já aberta.

{
  "product_id": "pdt_pro",
  "quantity": 1,
  "proration_billing_mode": "prorated_immediately",
  "on_payment_failure": "prevent_change",
  "collect_via_payment_link": true,
  "cancel_older_payment_link": true
}

A solicitação é validada antes que o link seja cancelado; portanto, uma solicitação inválida mantém o link do cliente. O link só é cancelado se o cliente ainda não tiver iniciado o pagamento:

Pagamento anterior	Resposta
Não aberto, aberto mas não pago ou recusado	`200` com o novo link.
Cliente está pagando agora, por exemplo durante o 3D Secure	`409` `PLAN_CHANGE_PAYMENT_IN_PROGRESS`. Tente novamente após o pagamento ser concluído ou falhar.
Já pago	`409` `PLAN_CHANGE_PAYMENT_ALREADY_COMPLETED`. Não tente novamente: a alteração de plano anterior será aplicada.
Não foi possível cancelar o link	`503` `PLAN_CHANGE_LINK_CANCEL_FAILED`. Nada foi alterado, então você pode tentar novamente.

Cada solicitação change-plan emite sua própria fatura. A alteração de plano substituída e sua fatura são canceladas. Se não houver uma alteração de plano pendente, cancel_older_payment_link não terá efeito.

Uma verificação executada após a validação, como o valor mínimo da cobrança, ainda pode falhar depois que o link for cancelado. A assinatura permanece no plano atual sem nenhum link aberto. Envie a solicitação novamente para emitir um novo link.

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: 'pdt_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: 'pdt_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 proration e serão cobrados de acordo com o modo de proration selecionado.

Aplicando códigos de desconto

Aplique um ou mais códigos de desconto empilhados ao alterar planos de assinatura (máximo de 20, aplicados na ordem do array):

Node.js SDK
Python SDK
HTTP

// Apply stacked discount codes during plan change
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_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="pdt_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": "pdt_pro",
    "quantity": 1,
    "proration_billing_mode": "prorated_immediately",
    "discount_codes": ["UPGRADE20"]
  }'

Comportamento dos descontos na alteração de plano

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

O campo singular discount_code neste endpoint está obsoleto, mas ainda funciona por compatibilidade retroativa — as integrações existentes não precisam ser alteradas imediatamente. Ele não pode ser combinado com discount_codes na mesma solicitação. Migre para o formato de array quando for conveniente.

Use a Preview Plan Change API com discount_codes para mostrar aos clientes exatamente quanto eles economizarão antes de confirmar a alteração do plano.

Modos de proration

Escolha como cobrar o cliente ao alterar os planos:

`prorated_immediately`

Credita a parte não utilizada do ciclo atual — plano base, quantidade e addons — proporcionalmente ao tempo restante
Em seguida, cobra um ciclo completo no novo plano, quantidade e addons. A cobrança em si nunca é proporcional
Cobrança imediata líquida = (novo ciclo completo) − (fração restante × ciclo antigo completo)
Se o crédito exceder a cobrança do novo ciclo (comum em downgrades), a diferença será mantida como crédito no escopo da assinatura para renovações futuras
Se estiver em período de teste, cobra imediatamente e muda para o novo plano agora

`full_immediately`

Cobra imediatamente o valor total do novo plano
Ignora o tempo restante do plano antigo — não há crédito referente ao ciclo atual

Os créditos criados por prorated_immediately e por downgrades usando difference_immediately pertencem ao escopo da assinatura e são distintos dos benefícios de Credit-Based Billing. Eles são aplicados automaticamente a renovações futuras da mesma assinatura e não podem ser transferidos entre assinaturas.

`difference_immediately`

Upgrade: cobra imediatamente a diferença de preço entre os planos antigo e novo
Downgrade: adiciona o 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 imediatamente para o novo plano sem nenhum ajuste de cobrança
O ciclo de cobrança permanece inalterado
Ideal para migrações de cortesia, mudanças para planos gratuitos ou absorção de diferenças de custo

Recurso	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
Cobrança de upgrade	Ciclo novo completo, menos o crédito pelo tempo não utilizado	Diferença de preço total entre os planos	Preço total do novo plano	Sem cobrança
Crédito de downgrade	Crédito pelo tempo não utilizado, menos um ciclo novo completo	Diferença de preço total como crédito	Sem crédito	Sem crédito
Ciclo de cobrança	Reinicia hoje	Reinicia hoje	Reinicia hoje	Inalterado
Comportamento no período de teste	Encerra o teste e cobra imediatamente	Encerra o teste e cobra imediatamente	Encerra o teste e cobra o valor total	Mantém a data final do teste, sem cobrança
Ideal para	Creditar tempo não utilizado	Cálculos simples de upgrade/downgrade	Reiniciar ciclos de cobrança	Migrações gratuitas ou mudanças de cortesia
Complexidade	Média (cálculo por dia)	Baixa (subtração simples)	Baixa (cobrança total)	Nenhuma

Cenários de exemplo

Use estes valores canônicos de forma consistente:

Plano atual: Basic a $30/mês
Destino do upgrade: Pro a $80/mês
Destino do downgrade (a partir do Pro): Starter a $20/mês
Ciclo de cobrança: 30 dias, iniciado em 1º de janeiro
A alteração do plano ocorre em 16 de janeiro (15 dias restantes, 15 dias utilizados)

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

Step 1: Credit the unused time on the current plan
  Unused days = 15 out of 30 days
  Credit = $30 × (15/30) = $15.00

Step 2: Charge a full cycle at the new plan
  New plan cost = $80.00 (never prorated)

Step 3: Calculate immediate charge
  Charge = Full new cycle − Credit
  Charge = $80.00 − $15.00 = $65.00

→ Customer pays $65.00 now
→ Customer starts a full month of Pro today
→ Billing cycle resets to today (January 16)
→ Next renewal (Feb 15): $80.00/month

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

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

Step 1: Credit the unused time on the current plan
  Unused days = 15 out of 30 days
  Credit = $80 × (15/30) = $40.00

Step 2: Charge a full cycle at the new plan
  New plan cost = $20.00 (never prorated)

Step 3: Net the two
  Net = $20.00 − $40.00 = −$20.00

→ No charge — $20.00 credit added to subscription
→ Billing cycle resets to today (January 16)
→ Credit auto-applies to future renewals
→ Next renewal (Feb 15): $20.00 − $20.00 (from credit) = $0.00 (credit exhausted)
→ Following renewal (Mar 15): $20.00

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_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)
→ Billing cycle resets to today (January 16)
→ Next renewal (Feb 15): $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_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: 'pdt_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: 'pdt_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 the unused time on the current plan
  Credit = $30 × (15/30) = $15.00

Step 2: Charge a full cycle at the new plan + add-ons
  New plan = $80.00
  Add-ons  = $30.00
  Total new = $110.00 (never prorated)

Step 3: Immediate charge
  Charge = $110.00 − $15.00 = $95.00

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

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_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 creditar o tempo não utilizado do plano antigo enquanto cobra um ciclo completo do novo; 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 de plano sem nenhum ajuste de cobrança.

Lidando com falhas de pagamento

Controle o que acontece quando o pagamento de uma alteração 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: mantém a assinatura no plano atual até que o pagamento seja bem-sucedido.

A alteração do plano é marcada como “pendente”
O cliente mantém acesso ao plano atual
A assinatura só passa para o estado active 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: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  on_payment_failure: 'prevent_change'
});

Comportamento: aplica a alteração do plano imediatamente, independentemente do resultado do pagamento.

A alteração do plano é aplicada mesmo que o pagamento falhe
O cliente obtém acesso imediato ao novo plano
A assinatura pode passar para o estado on_hold se o pagamento falhar
Ideal para upgrades não críticos ou quando você confia no cliente

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

Se não for especificado, o parâmetro on_payment_failure usará a configuração padrão no nível da empresa definida no dashboard.

Quando usar cada modo

Cenário	Modo recomendado	Motivo
Upgrade para recursos premium	`prevent_change`	Garantir o pagamento antes de conceder acesso
Aumento de quantidade (mais assentos)	`prevent_change`	Evitar uso sem pagamento
Downgrade de planos	`apply_change`	O cliente está reduzindo os gastos
Clientes corporativos confiáveis	`apply_change`	Menor risco de inadimplência
Conversão de teste para pago	`prevent_change`	Momento crítico do pagamento

Padrões da empresa e de cobrança

Defina o comportamento padrão de upgrades e downgrades no nível da empresa em Settings → Subscriptions. Esses padrões se aplicam a todas as alterações de plano do portal do cliente e podem ser substituídos por coleção de produtos. Há padrões separados para upgrades e downgrades:

Configuração	Campo (upgrade / downgrade)	Padrão (upgrade)	Padrão (downgrade)
Quando o novo plano começa	`effective_at_on_upgrade` / `effective_at_on_downgrade`	`immediately`	`next_billing_date`
Como o cliente é cobrado	`proration_billing_mode_on_upgrade` / `proration_billing_mode_on_downgrade`	`difference_immediately`	`difference_immediately`
Se o pagamento do cliente falhar	`on_payment_failure`	`apply_change`	`apply_change`

Configure os padrões da empresa em Settings → Subscriptions e as substituições de coleção em cada coleção de produtos. Cada campo da coleção é independente — deixe-o sem definição para herdar o padrão da empresa ou defina um valor para substituí-lo.

Ordem de resolução

Para qualquer alteração de plano, cada configuração é resolvida nesta ordem:

per-request value (Change Plan API) → collection field (if set) → business field → system default

Um valor enviado explicitamente para a Change Plan API sempre tem prioridade. Os padrões da empresa e da coleção só entram em vigor quando nenhum valor explícito é fornecido — o que ocorre em todas as alterações de plano iniciadas pelo portal do cliente.

Uma configuração comum: mantenha os upgrades em immediately + difference_immediately para que os clientes paguem a diferença e obtenham acesso imediatamente, e mantenha os downgrades em next_billing_date para que os clientes conservem o plano atual até o fim do ciclo.

Lidando com webhooks

Acompanhe o estado da assinatura por meio de webhooks para confirmar alterações de plano e pagamentos.

Tipos de evento a tratar

subscription.active: assinatura ativada
subscription.plan_changed: plano da assinatura alterado (upgrade/downgrade/alterações de addon)
subscription.on_hold: cobrança falhou, renovações interrompidas
subscription.renewed: renovação bem-sucedida
payment.succeeded: pagamento da alteração de plano ou renovação bem-sucedido
payment.failed: pagamento falhou

Baseie a lógica de negócio nos eventos da assinatura e use eventos de pagamento para confirmação e reconciliação.

Verifique assinaturas e trate 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_PAYMENTS_WEBHOOK_KEY;

  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_PAYMENTS_WEBHOOK_KEY;
  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 obter os schemas detalhados dos payloads, consulte payloads de webhook de assinatura e payloads de webhook de pagamento.

Práticas recomendadas

Estratégia de alteração de plano

Teste completamente: sempre teste as alterações de plano no modo de teste antes da produção
Escolha o proration com cuidado: selecione o modo de proration alinhado ao seu modelo de negócio
Lide com falhas adequadamente: implemente tratamento de erros e lógica de novas tentativas
Monitore as taxas de sucesso: acompanhe as taxas de sucesso/falha das alterações de plano e investigue os problemas

Implementação de webhook

Verifique as assinaturas: sempre valide as assinaturas dos webhooks para garantir a autenticidade
Implemente idempotência: trate eventos de webhook duplicados adequadamente
Processe de forma assíncrona: não bloqueie as respostas dos webhooks com operações pesadas
Registre tudo: mantenha logs detalhados para depuração e auditoria

Experiência do usuário

Comunique-se claramente: informe os clientes sobre as alterações de cobrança e os prazos
Forneça confirmações: envie confirmações por e-mail para alterações de plano bem-sucedidas
Lide com casos extremos: considere períodos de teste, prorations e pagamentos malsucedidos
Atualize a interface imediatamente: reflita as alterações de plano na interface da sua aplicação

Problemas comuns e soluções

Resolva problemas típicos encontrados durante alterações de planos de assinatura:

Charge created but subscription not updated

Sintomas: a chamada da API é bem-sucedida, mas a assinatura permanece no plano antigoCausas comuns:

O processamento do webhook falhou ou atrasou
O estado da aplicação não foi atualizado após o recebimento dos webhooks
Problemas de transação do banco de dados durante a atualização do estado

Soluções:

Implemente o tratamento de webhooks com lógica de novas tentativas
Use operações idempotentes para atualizações de estado
Adicione monitoramento para detectar e alertar sobre eventos de webhook perdidos
Verifique se o endpoint do webhook está acessível e respondendo corretamente

Credits not applied after downgrade

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

Expectativas sobre o modo de proration: downgrades creditam a diferença total de preço do plano com difference_immediately, enquanto prorated_immediately credita o tempo não utilizado do ciclo antigo e cobra um ciclo completo no novo plano — portanto, um saldo de crédito só permanece quando esse crédito excede o preço do novo plano
Os créditos são específicos da assinatura e não são transferidos entre assinaturas
O saldo de crédito não está visível no dashboard do cliente

Soluções:

Use difference_immediately para downgrades quando quiser créditos automáticos
Explique aos clientes que os créditos se aplicam a renovações futuras da mesma assinatura
Implemente o portal do cliente para exibir saldos de crédito
Verifique o preview da próxima fatura para ver os créditos aplicados

Webhook signature verification fails

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

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

Soluções:

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

Plan change fails with 422 error

Sintomas: a API retorna o erro 422 Unprocessable EntityCausas comuns:

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

Soluções:

Verifique se a assinatura existe e está ativa
Confira se o ID do produto é válido e está disponível
Garanta que todos os parâmetros obrigatórios sejam fornecidos
Consulte a documentação da API para conhecer os requisitos dos parâmetros

Immediate charge fails during plan change

Sintomas: alteração de plano iniciada, mas a cobrança imediata falhaCausas comuns:

Saldo insuficiente 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:

Trate os eventos de webhook payment.failed adequadamente
Notifique o cliente para atualizar o método de pagamento
Implemente lógica de novas tentativas para falhas temporárias
Considere permitir alterações de plano com cobranças imediatas malsucedidas

Subscription on hold after plan change

Sintomas: a cobrança da alteração do plano falha e a assinatura passa para o estado on_holdO que acontece: Quando uma cobrança de alteração de plano falha, a assinatura é automaticamente colocada no 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 alteração de plano malsucedida:

Atualize o método de pagamento usando a Update Payment Method API
Criação automática da cobrança: a API cria automaticamente uma cobrança para os valores pendentes
Geração da fatura: uma fatura é gerada para a cobrança
Processamento do 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, {
    payment_method: { 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, {
    payment_method: { type: 'existing', payment_method_id: paymentMethodId }
  });
  
  // Monitor webhooks for payment.succeeded and subscription.active
  return response;
}

# Reactivate subscription from on_hold after failed plan change
def reactivate_after_failed_plan_change(subscription_id):
    # Update payment method - automatically creates charge for remaining dues
    response = client.subscriptions.update_payment_method(
        subscription_id=subscription_id,
        payment_method={"type": "new", "return_url": "https://example.com/return"},
    )
    
    if response.payment_id:
        print("Charge created for remaining dues:", response.payment_id)
        print("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
def reactivate_with_existing_payment_method(subscription_id, payment_method_id):
    response = client.subscriptions.update_payment_method(
        subscription_id=subscription_id,
        payment_method={"type": "existing", "payment_method_id": payment_method_id},
    )
    
    # Monitor webhooks for payment.succeeded and subscription.active
    return response

Eventos de webhook a monitorar:

subscription.on_hold: assinatura colocada em espera (recebido quando a cobrança da alteração do plano falha)
payment.succeeded: pagamento dos valores pendentes bem-sucedido (após a atualização do método de pagamento)
subscription.active: assinatura reativada após pagamento bem-sucedido

Práticas recomendadas:

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

Update Payment Method API Reference

Consulte a documentação completa da API para atualizar métodos de pagamento e reativar assinaturas.

Testando sua implementação

Teste completamente sua implementação de alteração de plano da 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 um endpoint de webhook de teste
Configure monitoramento e logging

Test different proration modes

Teste prorated_immediately com várias posições no 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 alterações 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 de webhook relevantes são recebidos
Teste a verificação das assinaturas dos webhooks
Trate eventos de webhook duplicados adequadamente
Teste cenários de falha no processamento de webhooks

Test error scenarios

Teste com IDs de assinatura inválidos
Teste com métodos de pagamento expirados
Teste falhas de rede e timeouts
Teste com saldo insuficiente

Monitor in production

Configure alertas para alterações de plano malsucedidas
Monitore os tempos de processamento dos webhooks
Acompanhe as taxas de sucesso das alterações de plano
Analise os tickets de suporte ao cliente relacionados a problemas de alteração de plano

Tratamento de erros

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

Códigos de status HTTP

200 OK

Solicitação de alteração de plano processada com sucesso. O corpo da resposta é um ChangePlanResponse com payment_id, payment_link, client_secret e expires_on. Todos os quatro aceitam nulo, portanto o corpo é serializado como {} para uma alteração comum fora da sessão; eles são preenchidos para uma solicitação collect_via_payment_link bem-sucedida, que retorna identificadores de checkout — consulte Coletando pagamento por meio de um link de checkout. Se on_payment_failure=prevent_change, a alteração do plano permanece pendente até que o pagamento seja bem-sucedido.

400 Bad Request

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

401 Unauthorized

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

409 Conflict

Já existe uma alteração de plano pendente para esta assinatura (PendingPlanChangeExists). Para uma alteração agendada, cancele-a com DELETE /subscriptions/{subscription_id}/change-plan/scheduled antes de enviar uma nova. Para uma alteração de link de pagamento pendente, envie a nova solicitação com cancel_older_payment_link: true para substituí-la. Consulte Substituindo um Link de Pagamento Pendente.Com cancel_older_payment_link: true, um 409 significa que o cliente está pagando o link anterior agora (PLAN_CHANGE_PAYMENT_IN_PROGRESS) ou que já o pagou (PLAN_CHANGE_PAYMENT_ALREADY_COMPLETED).

503 Service Unavailable

Com cancel_older_payment_link: true, não foi possível cancelar o link de pagamento anterior (PLAN_CHANGE_LINK_CANCEL_FAILED). Nada foi alterado, então você pode tentar novamente.

422 Unprocessable Entity

A assinatura está inativa ou sob demanda, ou a solicitação não é elegível para collect_via_payment_link — a empresa não tem o recurso habilitado, effective_at não é immediately ou on_payment_failure não é prevent_change. Consulte Requisitos. Um ID de assinatura que não existe ou não pertence à sua conta retorna 404 com o código NOT_FOUND.

500 Internal Server Error

Ocorreu um erro no servidor. Tente novamente após um breve intervalo.

Formato da resposta de erro

Os erros retornam um corpo JSON com um code e um message legível por humanos:

{
  "code": "INACTIVE_SUBSCRIPTION_PLAN_CHANGE_NOT_SUPPORTED",
  "message": "Changing plans is not supported for inactive subscriptions"
}

Consulte Códigos de erro para ver a lista completa.

Próximas etapas

Consulte a Change Plan API
Explore Credit-Based Billing
Implemente alertas para subscription.on_hold
Confira o Guia de integração de webhooks

Change Plan API

Plan Change Preview

Integration Guide

​O que é um upgrade ou downgrade de assinatura?

​Quando usar alterações de plano

​Plan Change Flow

​Prerequisites

​Step-by-Step Implementation Guide

​Visualizar alterações de plano

​Change Plan API

​Exemplos rápidos

​Coletando pagamento por meio de um link de checkout

​Requisitos

​O que acontece enquanto o link não é pago

​Redirecionando o cliente após o pagamento

​Substituindo um link de pagamento pendente

​Gerenciando addons

​Aplicando códigos de desconto

​Comportamento dos descontos na alteração de plano

​Modos de proration

​prorated_immediately

​full_immediately

​difference_immediately

​do_not_bill

​Cenários de exemplo

​Como cada modo processa a cobrança

​Lidando com falhas de pagamento

​Modos de falha de pagamento

​Quando usar cada modo

​Padrões da empresa e de cobrança

​Ordem de resolução

​Lidando com webhooks

​Tipos de evento a tratar

​Verifique assinaturas e trate intenções

​Práticas recomendadas

​Estratégia de alteração 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 da resposta de erro

​Próximas etapas

O que é um upgrade ou downgrade de assinatura?

Quando usar alterações de plano

Plan Change Flow

Prerequisites

Step-by-Step Implementation Guide

Visualizar alterações de plano

Change Plan API

Exemplos rápidos

Coletando pagamento por meio de um link de checkout

Requisitos

O que acontece enquanto o link não é pago

Redirecionando o cliente após o pagamento

Substituindo um link de pagamento pendente

Gerenciando addons

Aplicando códigos de desconto

Comportamento dos descontos na alteração de plano

Modos de proration

`prorated_immediately`

`full_immediately`

`difference_immediately`

`do_not_bill`

Cenários de exemplo

Como cada modo processa a cobrança

Lidando com falhas de pagamento

Modos de falha de pagamento

Quando usar cada modo

Padrões da empresa e de cobrança

Ordem de resolução

Lidando com webhooks

Tipos de evento a tratar

Verifique assinaturas e trate intenções

Práticas recomendadas

Estratégia de alteração 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 da resposta de erro

Próximas etapas