Saltar al contenido principal
POST
/
subscriptions
/
{subscription_id}
/
change-plan
/
preview
JavaScript
import DodoPayments from 'dodopayments';

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

const response = await client.subscriptions.previewChangePlan('subscription_id', {
  product_id: 'product_id',
  proration_billing_mode: 'prorated_immediately',
  quantity: 0,
});

console.log(response.immediate_charge);
{
  "immediate_charge": {
    "effective_at": "2023-11-07T05:31:56Z",
    "line_items": [
      {
        "id": "<string>",
        "product_id": "<string>",
        "proration_factor": 123,
        "quantity": 123,
        "tax_inclusive": true,
        "unit_price": 123,
        "description": "<string>",
        "name": "<string>",
        "tax": 123,
        "tax_rate": 123
      }
    ],
    "summary": {
      "customer_credits": 123,
      "settlement_amount": 123,
      "total_amount": 123,
      "settlement_tax": 123,
      "tax": 123
    }
  },
  "new_plan": {
    "addons": [
      {
        "addon_id": "<string>",
        "quantity": 123
      }
    ],
    "billing": {
      "city": "<string>",
      "state": "<string>",
      "street": "<string>",
      "zipcode": "<string>"
    },
    "cancel_at_next_billing_date": true,
    "created_at": "2023-11-07T05:31:56Z",
    "credit_entitlement_cart": [
      {
        "credit_entitlement_id": "<string>",
        "credit_entitlement_name": "<string>",
        "credits_amount": "<string>",
        "overage_balance": "<string>",
        "overage_enabled": true,
        "product_id": "<string>",
        "remaining_balance": "<string>",
        "rollover_enabled": true,
        "unit": "<string>",
        "expires_after_days": 123,
        "low_balance_threshold_percent": 123,
        "max_rollover_count": 123,
        "overage_limit": "<string>",
        "rollover_percentage": 123,
        "rollover_timeframe_count": 123
      }
    ],
    "customer": {
      "customer_id": "<string>",
      "email": "<string>",
      "name": "<string>",
      "metadata": {},
      "phone_number": "<string>"
    },
    "metadata": {},
    "meter_credit_entitlement_cart": [
      {
        "credit_entitlement_id": "<string>",
        "meter_id": "<string>",
        "meter_name": "<string>",
        "meter_units_per_credit": "<string>",
        "product_id": "<string>"
      }
    ],
    "meters": [
      {
        "free_threshold": 123,
        "measurement_unit": "<string>",
        "meter_id": "<string>",
        "name": "<string>",
        "description": "<string>",
        "price_per_unit": "10.50"
      }
    ],
    "next_billing_date": "2023-11-07T05:31:56Z",
    "on_demand": true,
    "payment_frequency_count": 123,
    "previous_billing_date": "2023-11-07T05:31:56Z",
    "product_id": "<string>",
    "quantity": 123,
    "recurring_pre_tax_amount": 123,
    "subscription_id": "<string>",
    "subscription_period_count": 123,
    "tax_inclusive": true,
    "trial_period_days": 123,
    "cancellation_comment": "<string>",
    "cancelled_at": "2023-11-07T05:31:56Z",
    "custom_field_responses": [
      {
        "key": "<string>",
        "value": "<string>"
      }
    ],
    "customer_business_name": "<string>",
    "discount_cycles_remaining": 123,
    "discount_id": "<string>",
    "discounts": [
      {
        "amount": 123,
        "business_id": "<string>",
        "code": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "discount_id": "<string>",
        "metadata": {},
        "position": 123,
        "preserve_on_plan_change": true,
        "restricted_to": [
          "<string>"
        ],
        "times_used": 123,
        "cycles_remaining": 123,
        "expires_at": "2023-11-07T05:31:56Z",
        "name": "<string>",
        "subscription_cycles": 123,
        "usage_limit": 123
      }
    ],
    "expires_at": "2023-11-07T05:31:56Z",
    "payment_method_id": "<string>",
    "scheduled_change": {
      "addons": [
        {
          "addon_id": "<string>",
          "name": "<string>",
          "quantity": 123
        }
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "effective_at": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "product_id": "<string>",
      "quantity": 123,
      "product_description": "<string>",
      "product_name": "<string>"
    },
    "tax_id": "<string>"
  }
}
Utiliza este endpoint para mostrar a los clientes exactamente qué se les cobrará al actualizar o degradar su suscripción, mejorando la transparencia y reduciendo las solicitudes de soporte.

​
Casos de uso

  • Confirmación de pago: Muestra el cargo prorrateado antes de que los clientes confirmen un cambio de plan
  • Calculadoras de precios: Construya calculadoras de actualización/reducción en su aplicación
  • Autoservicio para clientes: Permita que los clientes exploren opciones de planes con precios precisos
  • Validación de descuentos: Previsualice cómo afectan los códigos de descuento acumulados al precio del cambio de plan
You can include discount_codes (an array of up to 20 codes, applied in order) in the preview request to see how the stacked discounts affect the immediate charge and new plan pricing before committing to the change. The singular discount_code field is deprecated but still supported for backward compatibility; we recommend discount_codes going forward.

​
Campos de Respuesta

La respuesta de la vista previa incluye:
CampoDescripción
immediate_chargeEl cargo que se crearía inmediatamente, incluyendo elementos de línea y resumen
new_planEl objeto completo de la suscripción mostrando cómo se vería después del cambio de plan
El immediate_charge.summary contiene la cantidad total que se cobraría. Usa esto para mostrar los precios a tus clientes antes de que confirmen el cambio de plan.

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

Preview of subscription plan change

​
immediate_charge
object
requerido
​
new_plan
object
requerido

Response struct representing subscription details

Last modified on May 22, 2026