Saltar al contenido principal
POST
/
subscriptions
/
{subscription_id}
/
change-plan
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,
});

​
Cambios Programados de Plan

Use el parámetro effective_at para controlar cuándo entrará en vigor el cambio de plan:
ValorComportamiento
immediatelyAplica el cambio de plan de inmediato. Este es el valor predeterminado.
next_billing_datePrograma el cambio para la próxima fecha de facturación. El cliente conserva el acceso a su plan actual hasta que finalice el período de facturación.
Los cambios de plan programados son ideales para degradaciones: los clientes mantienen los beneficios de su plan actual hasta el final del período de facturación, y luego cambian automáticamente al nuevo plan.
Para cancelar un cambio de plan programado antes de que entre en vigor, use el endpoint Cancelar Cambio de Plan Programado.

​
Manejo de Fallos de Pago

Use el parámetro on_payment_failure para controlar lo que sucede cuando falla el pago del cambio de plan:
ValorComportamiento
prevent_changeMantiene la suscripción en el plan actual hasta que el pago sea exitoso. El cambio de plan permanece pendiente.
apply_changeAplica el cambio de plan inmediatamente, independientemente del resultado del pago. Este es el valor predeterminado.
Si no se especifica on_payment_failure, el comportamiento predeterminado es el configurado a nivel de negocio en el panel de control.

​
Códigos de Descuento

Puedes aplicar uno o más códigos de descuento acumulados al cambiar de planes pasando el array discount_codes (máximo 20 entradas, aplicadas en el orden del array). El campo singular discount_code está obsoleto pero aún funciona para integraciones existentes; no se puede combinar con discount_codes en la misma solicitud.
Valor de discount_codesComportamiento
No proporcionado (null / omitido)Los descuentos existentes con preserve_on_plan_change=true se preservan si son aplicables al nuevo producto.
[] (array vacío)Todos los descuentos existentes se eliminan de la suscripción.
["CODE_A", "CODE_B", ...]Reemplaza cualquier descuento existente con este conjunto acumulado, validado y aplicado en el orden del array.
Usa códigos de descuento durante los cambios de plan para ofrecer precios promocionales en actualizaciones, o pasa códigos al migrar clientes a un nuevo nivel de plan.
Use prevent_change para actualizaciones críticas donde desea asegurar el pago antes de otorgar acceso a características premium.

Autorizaciones

​
Authorization
string
header
requerido

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

Parámetros de ruta

​
subscription_id
string
requerido

Subscription Id

Cuerpo

application/json
​
product_id
string
requerido

Unique identifier of the product to subscribe to

​
proration_billing_mode
enum<string>
requerido

Proration Billing Mode

Opciones disponibles:
prorated_immediately,
full_immediately,
difference_immediately,
do_not_bill
​
quantity
integer<int32>
requerido

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

Rango requerido: x >= 0
​
adaptive_currency_fees_inclusive
boolean | null

Whether adaptive currency fees should be included in the price (true) or added on top (false). If not specified, uses the subscription's stored setting.

​
addons
Attach Addon Request · object[] | null

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

​
discount_code
string | null
obsoleto

DEPRECATED: Use discount_codes instead. Cannot be used together with discount_codes.

​
discount_codes
string[] | null

Stacked discount codes to apply to the new plan. Max 20. Cannot be used together with discount_code. If provided, replaces any existing discount codes. Empty array removes all discounts. If not provided (None), existing discounts with preserve_on_plan_change=true are preserved.

​
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
Opciones disponibles:
immediately,
next_billing_date
​
metadata
object

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

​
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.

Opciones disponibles:
prevent_change,
apply_change

Respuesta

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

Last modified on May 22, 2026