Pré-visualizar Mudança de Plano

Pré-visualize os efeitos de uma mudança de plano de assinatura antes de se comprometer com ela. Retorna o valor da cobrança imediata e os detalhes da nova assinatura sem fazer alterações reais.

POST /subscriptions/{subscription_id}/change-plan/preview

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

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

console.log(response.immediate_charge);

200

{
  "immediate_charge": {
    "effective_at": "2023-11-07T05:31:56Z",
    "line_items": [
      {
        "currency": "AED",
        "id": "<string>",
        "product_id": "<string>",
        "proration_factor": 123,
        "quantity": 123,
        "tax_inclusive": true,
        "type": "subscription",
        "unit_price": 123,
        "description": "<string>",
        "name": "<string>",
        "tax": 123,
        "tax_rate": 123
      }
    ],
    "summary": {
      "currency": "AED",
      "customer_credits": 123,
      "settlement_amount": 123,
      "settlement_currency": "AED",
      "total_amount": 123,
      "settlement_tax": 123,
      "tax": 123
    }
  },
  "new_plan": {
    "addons": [
      {
        "addon_id": "<string>",
        "quantity": 123
      }
    ],
    "billing": {
      "country": "AF",
      "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_behavior": "forgive_at_reset",
        "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,
        "rollover_timeframe_interval": "Day"
      }
    ],
    "currency": "AED",
    "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": [
      {
        "currency": "AED",
        "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,
    "payment_frequency_interval": "Day",
    "previous_billing_date": "2023-11-07T05:31:56Z",
    "product_id": "<string>",
    "quantity": 123,
    "recurring_pre_tax_amount": 123,
    "status": "pending",
    "subscription_id": "<string>",
    "subscription_period_count": 123,
    "subscription_period_interval": "Day",
    "tax_inclusive": true,
    "trial_period_days": 123,
    "cancelled_at": "2023-11-07T05:31:56Z",
    "custom_field_responses": [
      {
        "key": "<string>",
        "value": "<string>"
      }
    ],
    "discount_cycles_remaining": 123,
    "discount_id": "<string>",
    "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>"
  }
}

Use este endpoint para mostrar aos clientes exatamente o que será cobrado ao fazer upgrade ou downgrade da assinatura, melhorando a transparência e reduzindo solicitações de suporte.

​

Casos de Uso

• Confirmação de checkout: Exiba a cobrança proporcional antes de os clientes confirmarem a mudança de plano
• Calculadoras de preços: Construa calculadoras de upgrade/downgrade em sua aplicação
• Autoatendimento do cliente: Permita que os clientes explorem opções de planos com preços precisos
• Validação de desconto: Preveja como um código de desconto afeta o preço da mudança de plano

Você pode incluir um discount_code na solicitação de pré-visualização para ver como o desconto afeta a cobrança imediata e o novo preço do plano antes de confirmar a alteração.

​

Campos de Resposta

A resposta de pré-visualização inclui:

Campo	Descrição
immediate_charge	A cobrança que seria criada imediatamente, incluindo itens de linha e resumo
new_plan	O objeto completo da assinatura mostrando como ficaria após a mudança de plano

O immediate_charge.summary contém o valor total que seria cobrado. Use isso para exibir os preços aos seus clientes antes de confirmarem a mudança de plano.

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

application/json

Preview of subscription plan change

immediate_charge · object · obrigatório

Show child attributes

new_plan · object · obrigatório

Response struct representing subscription details

Show child attributes