Cambiar Plan

Modifica el plan de una suscripción existente, permitiendo tanto actualizaciones como degradaciones a diferentes niveles de precios.

Nota: Esto utilizará la información de pago existente del cliente para actualizar/degradar el plan.

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,
});

​

Manejo de Fallos de Pago

Utiliza el parámetro on_payment_failure para controlar lo que ocurre cuando el pago del cambio de plan falla:

Valor	Comportamiento
prevent_change	Mantener la suscripción en el plan actual hasta que el pago tenga éxito. El cambio de plan permanece pendiente.
apply_change	Aplicar el cambio de plan de inmediato independientemente del resultado del pago. Esta es la opción predeterminada.

Si on_payment_failure no se especifica, el comportamiento predeterminado es la configuración a nivel de negocio que hayas configurado en el panel.

​

Códigos de Descuento

Puedes aplicar un código de descuento al cambiar de plan pasando el parámetro discount_code.

Escenario	Comportamiento
discount_code proporcionado	Valida y aplica el descuento al nuevo plan.
discount_code no proporcionado, descuento existente con preserve_on_plan_change=true	El descuento existente se conserva si es aplicable al nuevo producto.
discount_code no proporcionado, ningún descuento conservable	No se aplica descuento.

Usa códigos de descuento durante los cambios de plan para ofrecer precios promocionales en actualizaciones, o pasa un código al migrar clientes a un nuevo nivel de plan.

Usa prevent_change para actualizaciones críticas donde quieres asegurar el pago antes de conceder 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

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

Opciones disponibles: 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.

Opciones disponibles: prevent_change, apply_change

Respuesta

200

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