Alterar Plano

Modifique o plano de uma assinatura existente, permitindo tanto upgrades quanto downgrades para diferentes níveis de preços.

Nota: Isso usará as informações de pagamento existentes do cliente para atualizar/diminuir o plano.

POST /subscriptions/{subscription_id}/change-plan

JavaScript

JavaScript

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
});

await client.subscriptions.changePlan('subscription_id', {
  product_id: 'product_id',
  proration_billing_mode: 'prorated_immediately',
  quantity: 0,
});

​

Tratamento de Falhas de Pagamento

Use o parâmetro on_payment_failure para controlar o que acontece quando o pagamento da alteração de plano falha:

Value	Comportamento
prevent_change	Mantenha a assinatura no plano atual até que o pagamento seja aprovado. A alteração de plano permanece pendente.
apply_change	Aplique a alteração de plano imediatamente independentemente do resultado do pagamento. Este é o padrão.

Se on_payment_failure não for especificado, o comportamento padrão será o definido nas configurações do nível empresarial no painel.

​

Códigos de Desconto

Você pode aplicar um código de desconto ao mudar de plano passando o parâmetro discount_code.

Cenário	Comportamento
discount_code fornecido	Valida e aplica o desconto ao novo plano.
discount_code não fornecido, desconto existente com preserve_on_plan_change=true	Desconto existente é preservado se aplicável ao novo produto.
discount_code não fornecido, nenhum desconto preservável	Nenhum desconto aplicado.

Use códigos de desconto durante mudanças de plano para oferecer preços promocionais em upgrades, ou passe um código ao migrar clientes para um novo nível de plano.

Use prevent_change para upgrades críticos onde você deseja garantir o pagamento antes de conceder acesso a recursos premium.

Autorizações

Authorization · string · header · obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Parâmetros de caminho

subscription_id · string · obrigatório

Subscription Id

Corpo

application/json

product_id · string · obrigatório

Unique identifier of the product to subscribe to

proration_billing_mode · enum<string> · obrigatório

Proration Billing Mode

Opções disponíveis: prorated_immediately, full_immediately, difference_immediately, do_not_bill

quantity · integer<int32> · obrigatório

Number of units to subscribe for. Must be at least 1.

Intervalo obrigatório: x >= 0

addons · Attach Addon Request · object[] | null

Addons for the new plan. Note : Leaving this empty would remove any existing addons

Show child attributes

discount_code · string | null

Optional discount code to apply to the new plan. If provided, validates and applies the discount to the plan change. If not provided and the subscription has an existing discount with preserve_on_plan_change=true, the existing discount will be preserved (if applicable to the new product).

effective_at · enum<string>

When to apply the plan change.

• immediately (default): Apply the plan change right away
• next_billing_date: Schedule the change for the next billing date

Opções disponíveis: immediately, next_billing_date

metadata · object

Metadata for the payment. If not passed, the metadata of the subscription will be taken

Show child attributes

on_payment_failure · null | enum<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.

Opções disponíveis: prevent_change, apply_change

Resposta

200

Subscription plan changed. If on_payment_failure=prevent_change, the plan change is pending until payment succeeds.