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.

¿Qué es una actualización o degradación de una suscripción?

Cambia el plan de suscripción de un cliente para moverlo entre niveles, ajustar la cantidad de productos basados en asientos o migrarlo a un producto nuevo. La API calcula automáticamente los prorrateos y los cargos según el modo de facturación elegido.

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

Cuándo usar cambios de plan

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 obtener instrucciones detalladas de configuración, consulta la Guía de integración.

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: aplicaciones SaaS que desean acreditar el tiempo no utilizado del plan anterior.

Acredita la parte no utilizada del ciclo actual, prorrateada según el tiempo restante
Después cobra un ciclo completo del plan nuevo; el precio del plan nuevo nunca se prorratea
Cargo neto = ciclo nuevo completo − (fracción restante × ciclo anterior completo)

Implement the Change Plan API

Use the Change Plan API to modify subscription details:

string

requerido

The ID of the active subscription to modify.

string

requerido

The new product ID to change the subscription to.

integer

requerido

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

string

requerido

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

array

Complementos opcionales para el nuevo plan. Omitir este campo, enviar null o enviar un array vacío elimina cualquier complemento existente, por lo que debes incluir los complementos actuales para conservarlos.

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.

boolean

Recopila el importe del cambio de plan mediante un enlace de pago en lugar de cargar el método de pago guardado de la suscripción. El cliente paga en una página de checkout alojada.Requiere que la empresa tenga habilitada la capacidad allow_plan_change_via_payment_link (Settings → Subscriptions → Collect Plan Change Payments by Payment Link), effective_at: immediately y on_payment_failure: prevent_change. Consulta Cobrar pagos mediante un enlace de Checkout. La ruta de vista previa lo ignora.

array

Códigos de descuento apilados opcionales que se aplicarán al plan nuevo (máximo 20, aplicados en el orden del array). El comportamiento depende de lo que envíes:

No proporcionado / null — los descuentos existentes con preserve_on_plan_change=true se conservan si son aplicables al producto nuevo.
[] (array vacío) — elimina todos los descuentos existentes de la suscripción.
["CODE_A", "CODE_B", ...] — reemplaza los descuentos existentes por este conjunto apilado.

string

obsoleto

Obsoleto — para nuevas integraciones, prefiere discount_codes. Este campo sigue funcionando por compatibilidad con versiones anteriores, pero no se puede combinar con discount_codes en la misma solicitud.

string

predeterminado:"immediately"

Cuándo aplicar el cambio de plan:

immediately (predeterminado): aplica el cambio de plan de inmediato
next_billing_date: programa el cambio para la próxima fecha de facturación. El cliente conserva su plan actual hasta que finaliza el período de facturación. Úsalo para degradaciones, de modo que los clientes mantengan los beneficios de su plan actual hasta el final del período de facturación.

Handle Webhook Events

Configura el manejo de webhooks para realizar un seguimiento de los resultados de los cambios de plan:

subscription.active: cambio de plan exitoso, suscripción actualizada
subscription.plan_changed: plan de suscripción cambiado (actualización/degradación/actualización de addon)
subscription.on_hold: falló el cargo del cambio de plan, renovaciones detenidas
payment.succeeded: el cargo inmediato del cambio de plan se realizó correctamente
payment.failed: falló el cargo inmediato

Verifica siempre las firmas de los webhooks e implementa el procesamiento idempotente de eventos.

Update Your Application State

Según los eventos de webhook, actualiza tu aplicación:

Concede o revoca funciones según el plan nuevo
Actualiza el panel del cliente con los detalles del plan nuevo
Envía correos electrónicos de confirmación sobre los cambios de plan
Registra los cambios de facturación para fines de auditoría

Test and Monitor

Prueba exhaustivamente tu implementación:

Prueba todos los modos de prorrateo con diferentes escenarios
Verifica que el manejo de webhooks funcione correctamente
Supervisa las tasas de éxito de los cambios de plan
Configura alertas para los cambios de plan fallidos

Tu implementación de cambios de plan de suscripción ya está lista para usarse en producción.

Vista previa de cambios de plan

Antes de confirmar un cambio de plan, usa la API de vista previa para mostrar a los clientes exactamente cuánto se les cobrará:

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)

Usa la API de vista previa para crear diálogos de confirmación que muestren a los clientes el importe exacto que se les cobrará antes de confirmar un cambio de plan.

API de cambio de plan

Usa la API de cambio de plan para modificar el producto, la cantidad y el comportamiento del prorrateo de una suscripción activa.

Ejemplos de inicio 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() {
  // 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"
  }'

Un cambio de plan exitoso devuelve 200 OK inmediatamente, antes de que se liquide realmente cualquier cargo. El contenido del cuerpo (ChangePlanResponse) depende de cómo se haya cobrado el cambio:

Caso	`payment_id` / `payment_link` / `client_secret` / `expires_on`
Cambio programado (`effective_at: next_billing_date`)	Todo `null`; todavía no se cobra nada
`proration_billing_mode: do_not_bill`	Todo `null`; no hay nada que cobrar
Cargo inmediato normal (método de pago guardado)	Todo `null`
`collect_via_payment_link: true` (enlace emitido)	Todo completado; identificadores de Checkout para el cliente

Esta respuesta confirma que la solicitud fue aceptada, no que el cargo se haya realizado correctamente. En un cargo inmediato normal, el resultado se resuelve fuera de sesión justo después de la llamada. Para una solicitud collect_via_payment_link, la suscripción conserva su plan actual hasta que el cliente complete el pago.Confirma el resultado mediante un webhook (payment.succeeded, payment.failed, subscription.plan_changed) o volviendo a leer la suscripción con GET /subscriptions/{subscription_id}. Consulta Qué ocurre mientras el enlace no está pagado para el caso de un enlace de pago.

Si falla el cargo inmediato, la suscripción puede pasar al estado subscription.on_hold hasta que se complete el pago.

Cobrar mediante un enlace de Checkout

De forma predeterminada, un cambio de plan inmediato cobra directamente al método de pago guardado de la suscripción. Establece collect_via_payment_link: true para enviar al cliente a una página de Checkout alojada; resulta útil cuando no hay un método de pago guardado o cuando deseas que el cliente confirme activamente el precio nuevo.

Esto habilita el interruptor Collect Plan Change Payments by Payment Link en Settings → Subscriptions, que dirige el flujo de cambio de plan del Customer Portal a través de Checkout.

Requisitos

collect_via_payment_link: true solo funciona correctamente cuando se cumplen todas las condiciones siguientes; de lo contrario, la solicitud falla con 422:

La empresa tiene habilitada la capacidad allow_plan_change_via_payment_link (Settings → Subscriptions → Collect Plan Change Payments by Payment Link).
effective_at es immediately (el valor predeterminado). Un cambio programado (next_billing_date) nunca necesita una página de Checkout.
El on_payment_failure efectivo se resuelve en prevent_change. No tienes que enviarlo explícitamente: si el valor predeterminado de tu empresa ya es prevent_change, omitir el campo cumple este requisito. Un apply_change explícito falla con 422.

collect_via_payment_link se aplica a cualquier cambio inmediato que genere un cargo, incluidas las degradaciones, siempre que se cumplan los requisitos anteriores.

Si el cambio resulta en un importe neto de cero o en un crédito, no se emite ningún enlace de pago: payment_link y los demás campos de Checkout devuelven null, y el cambio se aplica inmediatamente. Esto no es un 422. Llama primero a Vista previa del cambio de plan para comprobar el importe antes de solicitar un enlace.

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

Una solicitud exitosa devuelve los identificadores de Checkout:

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

Qué ocurre mientras el enlace no está pagado

La suscripción conserva su plan actual; product_id, recurring_pre_tax_amount e next_billing_date permanecen sin cambios hasta que se paga el enlace.
Una solicitud adicional de change-plan se rechaza con 409 PendingPlanChangeExists mientras el enlace está pendiente. Cancela un cambio programado con DELETE /subscriptions/{subscription_id}/change-plan/scheduled si es necesario, pero ese endpoint no cancela un cambio de enlace de pago pendiente; solo un pago exitoso o el vencimiento pueden hacerlo.
El cliente puede volver a intentar pagar con tarjeta en la misma sesión de Checkout después de un rechazo; una nueva llamada a change-plan no es el método para reintentar.
Si el enlace nunca se paga, deja de funcionar después de expires_on; la suscripción vuelve a estar disponible automáticamente para aceptar una nueva solicitud de cambio de plan poco después.
Si ya existía un cambio programado y lo reemplazas con cancel_scheduled_change_plan: true, la programación original permanece mientras el enlace no se haya pagado y solo se cancela cuando se paga el enlace, en la misma transacción que aplica el plan nuevo.

Una vez emitido un cambio de plan mediante un enlace de pago inmediato, cualquier solicitud posterior de cambio de plan para esa suscripción, incluida la vista previa sin efectos secundarios, queda bloqueada hasta que el enlace se resuelva. No emitas un enlace si no tienes la intención de que el cliente lo pague de inmediato.

Gestión de addons

Al cambiar los planes de suscripción, también puedes modificar los 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
});

Los addons se incluyen en el cálculo del prorrateo y se cobran según el modo de prorrateo seleccionado.

Aplicación de códigos de descuento

Aplica uno o más códigos de descuento apilados al cambiar los planes de suscripción (máximo 20, aplicados en el orden del 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"]
  }'

Comportamiento de los descuentos al cambiar de plan

Valor de `discount_codes`	Comportamiento
No proporcionado / `null`	Los descuentos existentes con `preserve_on_plan_change=true` se conservan automáticamente si son aplicables al producto nuevo.
`[]` (array vacío)	Se eliminan todos los descuentos existentes de la suscripción.
`["CODE_A", "CODE_B", ...]`	Reemplaza los descuentos existentes por este conjunto apilado, validado y aplicado en el orden del array.

El campo singular discount_code de este endpoint está obsoleto, pero sigue funcionando por compatibilidad con versiones anteriores; las integraciones existentes no necesitan cambiar de inmediato. No se puede combinar con discount_codes en la misma solicitud. Migra al formato de array cuando te resulte conveniente.

Usa la API de vista previa del cambio de plan con discount_codes para mostrar a los clientes exactamente cuánto ahorrarán antes de confirmar el cambio de plan.

Modos de prorrateo

Elige cómo cobrar al cliente al cambiar de plan:

`prorated_immediately`

Acredita la parte no utilizada del ciclo actual —plan base, cantidad y addons— prorrateada según el tiempo restante
Después cobra un ciclo completo del plan, la cantidad y los addons nuevos. El cargo en sí nunca se prorratea
Cargo inmediato neto = (ciclo nuevo completo) − (fracción restante × ciclo anterior completo)
Si el crédito supera el cargo del ciclo nuevo, algo habitual en las degradaciones, la diferencia se conserva como crédito asociado a la suscripción para futuras renovaciones
Si está en período de prueba, cobra inmediatamente y cambia al plan nuevo ahora

`full_immediately`

Cobra inmediatamente el importe completo del plan nuevo
Ignora el tiempo restante del plan anterior; no hay crédito por el ciclo actual

Los créditos creados por prorated_immediately y por degradaciones que usan difference_immediately están asociados a la suscripción y son distintos de las asignaciones de Credit-Based Billing. Se aplican automáticamente a futuras renovaciones de la misma suscripción y no se pueden transferir entre suscripciones.

`difference_immediately`

Actualización: cobra inmediatamente la diferencia de precio entre los planes anterior y nuevo
Degradación: añade el valor restante como crédito interno a la suscripción y lo aplica automáticamente en las renovaciones

`do_not_bill`

No se calculan cargos ni créditos
El cliente cambia inmediatamente al plan nuevo sin ningún ajuste de facturación
El ciclo de facturación no cambia
Ideal para migraciones de cortesía, cambios a planes gratuitos o para absorber diferencias de costo

Función	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
Cargo de actualización	Ciclo nuevo completo, menos el crédito por el tiempo no utilizado	Diferencia de precio completa entre los planes	Precio completo del plan nuevo	Sin cargo
Crédito de degradación	Crédito por el tiempo no utilizado, menos un ciclo nuevo completo	Diferencia de precio completa como crédito	Sin crédito	Sin crédito
Ciclo de facturación	Se reinicia hoy	Se reinicia hoy	Se reinicia hoy	Sin cambios
Comportamiento durante la prueba	Finaliza la prueba y cobra inmediatamente	Finaliza la prueba y cobra inmediatamente	Finaliza la prueba y cobra el importe completo	Conserva la fecha de finalización de la prueba, sin cargo
Ideal para	Acreditar tiempo no utilizado	Cálculos simples de actualización/degradación	Reiniciar ciclos de facturación	Migraciones gratuitas o cambios de cortesía
Complejidad	Media (cálculo por días)	Baja (resta simple)	Baja (cargo completo)	Ninguna

Ejemplos de escenarios

Usa estos valores canónicos de forma coherente:

Plan actual: Basic a $30/mes
Objetivo de actualización: Pro a $80/mes
Objetivo de degradación (desde Pro): Starter a $20/mes
Ciclo de facturación: 30 días, iniciado el 1 de enero
El cambio de plan ocurre el 16 de enero (quedan 15 días y se han utilizado 15 días)

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 }
  ]
})

Cómo procesa la facturación cada modo

Elige prorated_immediately para acreditar el tiempo no utilizado del plan anterior mientras cobras un ciclo completo del nuevo; elige full_immediately para reiniciar la facturación; usa difference_immediately para actualizaciones simples y créditos automáticos en degradaciones; o usa do_not_bill para cambiar de plan sin ningún ajuste de facturación.

Gestión de fallos de pago

Controla qué ocurre cuando falla el pago de un cambio de plan mediante el parámetro on_payment_failure.

Modos de fallo de pago

prevent_change (Recommended for critical upgrades)
apply_change (Default)

Comportamiento: mantiene la suscripción en su plan actual hasta que se complete el pago.

El cambio de plan se marca como “pending”
El cliente conserva el acceso a su plan actual
La suscripción pasa al estado active solo después de que el pago se realice correctamente
Es útil cuando deseas asegurarte de recibir el pago antes de conceder funciones actualizadas

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

Comportamiento: aplica el cambio de plan inmediatamente, independientemente del resultado del pago.

El cambio de plan se aplica aunque falle el pago
El cliente obtiene acceso inmediato al plan nuevo
La suscripción puede pasar al estado on_hold si falla el pago
Es adecuado para actualizaciones no críticas o cuando confías en el 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
});

Si no se especifica, el parámetro on_payment_failure usa la configuración predeterminada de tu empresa establecida en el dashboard.

Cuándo usar cada modo

Escenario	Modo recomendado	Motivo
Actualización a funciones premium	`prevent_change`	Asegurar el pago antes de conceder acceso
Aumento de cantidad (más asientos)	`prevent_change`	Evitar el uso sin pago
Degradación de planes	`apply_change`	El cliente está reduciendo sus gastos
Clientes empresariales de confianza	`apply_change`	Menor riesgo de impago
Conversión de prueba a pago	`prevent_change`	Momento de pago crítico

Valores predeterminados de empresa y cobro

Establece el comportamiento predeterminado de las actualizaciones y degradaciones a nivel de empresa en Settings → Subscriptions. Estos valores se aplican a todos los cambios de plan del portal del cliente y se pueden sustituir por colección de productos. Existen valores predeterminados independientes para actualizaciones y degradaciones:

Configuración	Campo (actualización / degradación)	Predeterminado (actualización)	Predeterminado (degradación)
Cuándo comienza el plan nuevo	`effective_at_on_upgrade` / `effective_at_on_downgrade`	`immediately`	`next_billing_date`
Cómo se cobra al cliente	`proration_billing_mode_on_upgrade` / `proration_billing_mode_on_downgrade`	`difference_immediately`	`difference_immediately`
Si falla el pago del cliente	`on_payment_failure`	`apply_change`	`apply_change`

Configura los valores predeterminados de la empresa en Settings → Subscriptions y las sustituciones de cada colección en la colección de productos correspondiente. Cada campo de colección es independiente: déjalo sin establecer para heredar el valor predeterminado de la empresa o establece un valor para sustituirlo.

Orden de resolución

Para cualquier cambio de plan, cada configuración se resuelve en este orden:

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

Siempre prevalece un valor enviado explícitamente a la API de cambio de plan. Los valores predeterminados de la empresa y de la colección solo se aplican cuando no se proporciona ningún valor explícito; este es el caso de todos los cambios de plan iniciados desde el portal del cliente.

Una configuración habitual: mantener las actualizaciones en immediately + difference_immediately para que los clientes paguen la diferencia y obtengan acceso de inmediato, y mantener las degradaciones en next_billing_date para que conserven su plan actual hasta que termine el ciclo.

Gestión de webhooks

Realiza un seguimiento del estado de las suscripciones mediante webhooks para confirmar los cambios de plan y los pagos.

Tipos de eventos que se deben gestionar

subscription.active: suscripción activada
subscription.plan_changed: plan de suscripción cambiado (actualizaciones/degradaciones/cambios de addons)
subscription.on_hold: cargo fallido, renovaciones detenidas
subscription.renewed: renovación exitosa
payment.succeeded: pago del cambio de plan o de la renovación realizado correctamente
payment.failed: pago fallido

Basa la lógica empresarial en los eventos de suscripción y usa los eventos de pago para la confirmación y la conciliación.

Verificación de firmas y gestión de intents

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 consultar los esquemas detallados de las cargas útiles, consulta las cargas útiles de webhook de suscripción y las cargas útiles de webhook de pago.

Prácticas recomendadas

Estrategia de cambio de plan

Prueba exhaustivamente: prueba siempre los cambios de plan en modo de prueba antes de usarlos en producción
Elige el prorrateo con cuidado: selecciona el modo de prorrateo que se ajuste a tu modelo de negocio
Gestiona los fallos correctamente: implementa un manejo de errores y una lógica de reintentos adecuados
Supervisa las tasas de éxito: realiza un seguimiento de las tasas de éxito y fallo de los cambios de plan e investiga los problemas

Implementación de webhooks

Verifica las firmas: valida siempre las firmas de los webhooks para garantizar su autenticidad
Implementa la idempotencia: gestiona correctamente los eventos de webhook duplicados
Procesa de forma asíncrona: no bloquees las respuestas de los webhooks con operaciones pesadas
Regístralo todo: mantén registros detallados para la depuración y la auditoría

Experiencia de usuario

Comunica con claridad: informa a los clientes sobre los cambios de facturación y sus fechas
Proporciona confirmaciones: envía correos electrónicos de confirmación para los cambios de plan exitosos
Gestiona los casos extremos: considera los períodos de prueba, los prorrateos y los pagos fallidos
Actualiza la interfaz de inmediato: refleja los cambios de plan en la interfaz de tu aplicación

Problemas comunes y soluciones

Resuelve los problemas habituales que surgen durante los cambios de plan de suscripción:

Charge created but subscription not updated

Síntomas: la llamada a la API se realiza correctamente, pero la suscripción mantiene el plan anteriorCausas comunes:

El procesamiento del webhook falló o se retrasó
El estado de la aplicación no se actualizó después de recibir los webhooks
Problemas con la transacción de la base de datos durante la actualización del estado

Soluciones:

Implementa el manejo de webhooks con lógica de reintentos
Usa operaciones idempotentes para las actualizaciones de estado
Añade supervisión para detectar y alertar sobre eventos de webhook omitidos
Verifica que el endpoint del webhook sea accesible y responda correctamente

Credits not applied after downgrade

Síntomas: el cliente degrada su plan, pero no ve el saldo de créditoCausas comunes:

Expectativas sobre el modo de prorrateo: las degradaciones acreditan la diferencia de precio completa del plan con difference_immediately, mientras que prorated_immediately acredita el tiempo no utilizado del ciclo anterior y después cobra un ciclo completo del plan nuevo; por eso, solo queda un saldo de crédito cuando ese crédito supera el precio del plan nuevo
Los créditos son específicos de la suscripción y no se transfieren entre suscripciones
El saldo de crédito no es visible en el panel del cliente

Soluciones:

Usa difference_immediately para las degradaciones cuando quieras créditos automáticos
Explica a los clientes que los créditos se aplican a futuras renovaciones de la misma suscripción
Implementa el portal del cliente para mostrar los saldos de crédito
Consulta la vista previa de la próxima factura para ver los créditos aplicados

Webhook signature verification fails

Síntomas: los eventos de webhook se rechazan debido a una firma no válidaCausas comunes:

Clave secreta de webhook incorrecta
El cuerpo sin procesar de la solicitud se modificó antes de verificar la firma
Algoritmo de verificación de firma incorrecto

Soluciones:

Verifica que estés usando el DODO_PAYMENTS_WEBHOOK_KEY correcto del dashboard
Lee el cuerpo sin procesar de la solicitud antes de cualquier middleware de análisis JSON
Usa la biblioteca estándar de verificación de webhooks para tu plataforma
Prueba la verificación de firmas de webhook en el entorno de desarrollo

Plan change fails with 422 error

Síntomas: la API devuelve un error 422 Unprocessable EntityCausas comunes:

ID de suscripción o ID de producto no válido
La suscripción no está activa
Faltan parámetros obligatorios
El producto no está disponible para cambios de plan

Soluciones:

Verifica que la suscripción exista y esté activa
Comprueba que el ID de producto sea válido y esté disponible
Asegúrate de proporcionar todos los parámetros obligatorios
Consulta la documentación de la API para conocer los requisitos de los parámetros

Immediate charge fails during plan change

Síntomas: se inició el cambio de plan, pero falla el cargo inmediatoCausas comunes:

Fondos insuficientes en el método de pago del cliente
Método de pago vencido o no válido
El banco rechazó la transacción
La detección de fraude bloqueó el cargo

Soluciones:

Gestiona correctamente los eventos de webhook payment.failed
Notifica al cliente que actualice su método de pago
Implementa una lógica de reintentos para fallos temporales
Considera permitir cambios de plan con cargos inmediatos fallidos

Subscription on hold after plan change

Síntomas: falla el cargo del cambio de plan y la suscripción pasa al estado on_holdQué ocurre: Cuando falla el cargo de un cambio de plan, la suscripción pasa automáticamente al estado on_hold. La suscripción no se renovará automáticamente hasta que se actualice el método de pago.Solución: actualiza el método de pago para reactivar la suscripciónPara reactivar una suscripción desde el estado on_hold después de un cambio de plan fallido:

Actualiza el método de pago mediante la API de actualización del método de pago
Creación automática del cargo: la API crea automáticamente un cargo por los importes pendientes
Generación de la factura: se genera una factura para el cargo
Procesamiento del pago: el pago se procesa usando el método de pago nuevo
Reactivación: tras un pago exitoso, la suscripción se reactiva al 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 que se deben supervisar:

subscription.on_hold: suscripción puesta en espera (se recibe cuando falla el cargo del cambio de plan)
payment.succeeded: pago de los importes pendientes realizado correctamente (después de actualizar el método de pago)
subscription.active: suscripción reactivada después de un pago exitoso

Prácticas recomendadas:

Notifica inmediatamente a los clientes cuando falle un cargo de cambio de plan
Proporciona instrucciones claras sobre cómo actualizar el método de pago
Supervisa los eventos de webhook para realizar un seguimiento del estado de reactivación
Considera implementar una lógica de reintentos automáticos para fallos de pago temporales

Update Payment Method API Reference

Consulta la documentación completa de la API para actualizar métodos de pago y reactivar suscripciones.

Prueba de tu implementación

Prueba exhaustivamente tu implementación de cambios de plan de suscripción:

Set up test environment

Usa API keys de prueba y productos de prueba
Crea suscripciones de prueba con distintos tipos de planes
Configura el endpoint de webhook de prueba
Configura la supervisión y el registro

Test different proration modes

Prueba prorated_immediately con distintas posiciones del ciclo de facturación
Prueba difference_immediately para actualizaciones y degradaciones
Prueba full_immediately para reiniciar los ciclos de facturación
Prueba do_not_bill para cambios de plan sin cargo ni crédito
Verifica que los cálculos de crédito sean correctos

Test webhook handling

Verifica que se reciban todos los eventos de webhook relevantes
Prueba la verificación de firmas de webhook
Gestiona correctamente los eventos de webhook duplicados
Prueba escenarios de fallos en el procesamiento de webhooks

Test error scenarios

Prueba con IDs de suscripción no válidos
Prueba con métodos de pago vencidos
Prueba fallos de red y tiempos de espera agotados
Prueba con fondos insuficientes

Monitor in production

Configura alertas para los cambios de plan fallidos
Supervisa los tiempos de procesamiento de webhooks
Realiza un seguimiento de las tasas de éxito de los cambios de plan
Revisa los tickets de soporte al cliente relacionados con problemas de cambios de plan

Gestión de errores

Gestiona correctamente los errores comunes de la API en tu implementación:

Códigos de estado HTTP

200 OK

La solicitud de cambio de plan se procesó correctamente. El cuerpo de la respuesta es un ChangePlanResponse con payment_id, payment_link, client_secret e expires_on. Los cuatro valores aceptan null, por lo que el cuerpo se serializa como {} para un cambio normal fuera de sesión; se rellenan para una solicitud collect_via_payment_link exitosa, que devuelve identificadores de Checkout. Consulta Cobrar mediante un enlace de Checkout. Si on_payment_failure=prevent_change, el cambio de plan permanece pendiente hasta que se complete el pago.

400 Bad Request

Parámetros de solicitud no válidos. Comprueba que todos los campos obligatorios se hayan proporcionado y tengan el formato correcto.

401 Unauthorized

API key no válida o ausente. Verifica que tu DODO_PAYMENTS_API_KEY sea correcta y tenga los permisos adecuados.

409 Conflict

Ya existe un cambio de plan pendiente para esta suscripción (PendingPlanChangeExists). Para un cambio programado, cancélalo con DELETE /subscriptions/{subscription_id}/change-plan/scheduled antes de enviar uno nuevo. Para un cambio de enlace de pago pendiente, no existe ningún endpoint de cancelación; la suscripción acepta una nueva solicitud de cambio de plan cuando el cliente paga o el enlace vence.

422 Unprocessable Entity

La suscripción está inactiva o es bajo demanda, o la solicitud no cumple los requisitos para collect_via_payment_link: la empresa no tiene habilitada la capacidad, effective_at no es immediately o on_payment_failure no es prevent_change. Consulta Requisitos. Un ID de suscripción que no existe o no pertenece a tu cuenta devuelve 404 con el código NOT_FOUND.

500 Internal Server Error

Se produjo un error del servidor. Vuelve a intentar la solicitud después de una breve espera.

Formato de respuesta de error

Los errores devuelven un cuerpo JSON con un code y un message legible para las personas:

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

Consulta Códigos de error para ver la lista completa.

Próximos pasos

Revisa la API de cambio de plan
Explora Credit-Based Billing
Implementa alertas para subscription.on_hold
Consulta la Guía de integración de webhooks

Change Plan API

Plan Change Preview

Integration Guide

​¿Qué es una actualización o degradación de una suscripción?

​Cuándo usar cambios de plan

​Plan Change Flow

​Prerequisites

​Step-by-Step Implementation Guide

​Vista previa de cambios de plan

​API de cambio de plan

​Ejemplos de inicio rápido

​Cobrar mediante un enlace de Checkout

​Requisitos

​Qué ocurre mientras el enlace no está pagado

​Gestión de addons

​Aplicación de códigos de descuento

​Comportamiento de los descuentos al cambiar de plan

​Modos de prorrateo

​prorated_immediately

​full_immediately

​difference_immediately

​do_not_bill

​Ejemplos de escenarios

​Cómo procesa la facturación cada modo

​Gestión de fallos de pago

​Modos de fallo de pago

​Cuándo usar cada modo

​Valores predeterminados de empresa y cobro

​Orden de resolución

​Gestión de webhooks

​Tipos de eventos que se deben gestionar

​Verificación de firmas y gestión de intents

​Prácticas recomendadas

​Estrategia de cambio de plan

​Implementación de webhooks

​Experiencia de usuario

​Problemas comunes y soluciones

Update Payment Method API Reference

​Prueba de tu implementación

​Gestión de errores

​Códigos de estado HTTP

​Formato de respuesta de error

​Próximos pasos

¿Qué es una actualización o degradación de una suscripción?

Cuándo usar cambios de plan

Plan Change Flow

Prerequisites

Step-by-Step Implementation Guide

Vista previa de cambios de plan

API de cambio de plan

Ejemplos de inicio rápido

Cobrar mediante un enlace de Checkout

Requisitos

Qué ocurre mientras el enlace no está pagado

Gestión de addons

Aplicación de códigos de descuento

Comportamiento de los descuentos al cambiar de plan

Modos de prorrateo

`prorated_immediately`

`full_immediately`

`difference_immediately`

`do_not_bill`

Ejemplos de escenarios

Cómo procesa la facturación cada modo

Gestión de fallos de pago

Modos de fallo de pago

Cuándo usar cada modo

Valores predeterminados de empresa y cobro

Orden de resolución

Gestión de webhooks

Tipos de eventos que se deben gestionar

Verificación de firmas y gestión de intents

Prácticas recomendadas

Estrategia de cambio de plan

Implementación de webhooks

Experiencia de usuario

Problemas comunes y soluciones

Prueba de tu implementación

Gestión de errores

Códigos de estado HTTP

Formato de respuesta de error

Próximos pasos