الانتقال إلى المحتوى الرئيسي
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>"
  }
}
استخدم هذا الموجه لإظهار التكلفة المحددة التي سيتم فرضها على العملاء عند ترقية أو تخفيض اشتراكهم، مما يحسن الشفافية ويقلل من طلبات الدعم.

حالات الاستخدام

  • تأكيد الدفع: عرض الرسوم المحسوبة بالتناسب قبل أن يؤكد العملاء تغيير الخطة
  • حسابات التسعير: بناء حاسبات الترقية/التقليل في تطبيقك
  • الخدمة الذاتية للعملاء: دع العملاء يستعرضون خيارات الخطط بأسعار دقيقة
  • التحقق من الخصم: معاينة كيفية تأثير رمز الخصم على تسعير تغيير الخطة
يمكنك تضمين discount_code في طلب المعاينة لمشاهدة كيفية تأثير الخصم على الرسوم الفورية وتسعير الخطة الجديدة قبل الالتزام بالتغيير.

حقول الاستجابة

تتضمن استجابة المعاينة:
الحقلالوصف
immediate_chargeالرسوم التي سيتم إنشاؤها فورًا، بما في ذلك عناصر الخط والملخص
new_planكائن الاشتراك الكامل الذي يوضح كيف سيبدو بعد تغيير الخطة
يحتوي immediate_charge.summary على المبلغ الإجمالي الذي سيتم تحصيله. استخدم هذا لعرض التسعير لعملائك قبل أن يؤكدوا تغيير الخطة.

التفويضات

Authorization
string
header
مطلوب

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

معلمات المسار

subscription_id
string
مطلوب

Subscription Id

الجسم

application/json
product_id
string
مطلوب

Unique identifier of the product to subscribe to

proration_billing_mode
enum<string>
مطلوب

Proration Billing Mode

الخيارات المتاحة:
prorated_immediately,
full_immediately,
difference_immediately,
do_not_bill
quantity
integer<int32>
مطلوب

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

النطاق المطلوب: 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
الخيارات المتاحة:
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.

الخيارات المتاحة:
prevent_change,
apply_change

الاستجابة

Preview of subscription plan change

immediate_charge
object
مطلوب
new_plan
object
مطلوب

Response struct representing subscription details

Last modified on April 1, 2026