Chuyển đến nội dung chính
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": [
      {
        "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>"
  }
}
Sử dụng endpoint này để hiển thị cho khách hàng chính xác số tiền họ sẽ bị tính khi nâng cấp hoặc hạ cấp đăng ký, tăng cường tính minh bạch và giảm số lượng yêu cầu hỗ trợ.

Trường hợp sử dụng

  • Xác nhận thanh toán: Hiển thị phí chiết khấu trước khi khách hàng xác nhận thay đổi gói.
  • Máy tính giá: Xây dựng máy tính nâng cấp/hạ cấp trong ứng dụng của bạn.
  • Khách hàng tự phục vụ: Cho phép khách hàng khám phá các tùy chọn gói với giá chính xác.
  • Xác minh giảm giá: Xem trước mã giảm giá sẽ ảnh hưởng thế nào đến giá thay đổi gói.
You can include a discount_code in the preview request to see how the discount affects the immediate charge and new plan pricing before committing to the change.

Các trường phản hồi

Phản hồi xem trước bao gồm:
TrườngMô tả
immediate_chargeChi phí sẽ được tạo ngay lập tức, bao gồm mục dòng và tóm tắt
new_planĐối tượng đăng ký đầy đủ hiển thị trông như thế nào sau khi thay đổi gói
The immediate_charge.summary contains the total amount that would be charged. Use this to display pricing to your customers before they confirm the plan change.

Ủy quyền

Authorization
string
header
bắt buộc

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

Tham số đường dẫn

subscription_id
string
bắt buộc

Subscription Id

Nội dung

application/json
product_id
string
bắt buộc

Unique identifier of the product to subscribe to

proration_billing_mode
enum<string>
bắt buộc

Proration Billing Mode

Tùy chọn có sẵn:
prorated_immediately,
full_immediately,
difference_immediately,
do_not_bill
quantity
integer<int32>
bắt buộc

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

Phạm vi bắt buộc: x >= 0
addons
Attach Addon Request · object[] | null

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

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
Tùy chọn có sẵn:
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.

Tùy chọn có sẵn:
prevent_change,
apply_change

Phản hồi

Preview of subscription plan change

immediate_charge
object
bắt buộc
new_plan
object
bắt buộc

Response struct representing subscription details

Last modified on March 24, 2026