Subscription Upgrade & Downgrade Guide - Dodo Payments Documentation

Change Plan API

Full API docs for updating subscriptions.

Plan Change Preview

See charge amounts before changing plans.

Integration Guide

Step-by-step subscription setup.

What Is a Subscription Upgrade or Downgrade?

Change a customer’s subscription plan to move them between tiers, adjust quantity for seat-based products, or migrate to a new product. The API automatically calculates prorations and charges based on your chosen billing mode.

Plan changes can trigger an immediate charge depending on the proration mode you choose.

When to Use Plan Changes

Upgrade when a customer needs more features, usage, or seats
Downgrade when usage decreases
Migrate users to a new product or price without cancelling their subscription

Plan Change Flow

Prerequisites

Before implementing subscription plan changes, ensure you have:

A Dodo Payments merchant account with active subscription products
API credentials (API key and webhook secret key) from the dashboard
An existing active subscription to modify
Webhook endpoint configured to handle subscription events

For detailed setup instructions, see the Integration Guide.

Step-by-Step Implementation Guide

Follow this comprehensive guide to implement subscription plan changes in your application:

Understand Plan Change Requirements

Before implementing, determine:

Which subscription products can be changed to which others
What proration mode fits your business model
How to handle failed plan changes gracefully
Which webhook events to track for state management

Test plan changes thoroughly in test mode before implementing in production.

Choose Your Proration Strategy

Select the billing approach that aligns with your business needs:

prorated_immediately
difference_immediately
full_immediately
do_not_bill

Best for: SaaS applications that want to credit unused time on the old plan.

Credits the unused portion of the current cycle, prorated by time remaining
Then charges a full cycle at the new plan — the new plan price is never prorated
Net charge = full new cycle − (remaining fraction × full old cycle)

Implement the Change Plan API

Use the Change Plan API to modify subscription details:

string

مطلوب

The ID of the active subscription to modify.

string

مطلوب

معرّف المنتج الجديد الذي سيتم تغيير الاشتراك إليه.

integer

مطلوب

عدد الوحدات للخطة الجديدة (للمنتجات القائمة على المقاعد).

string

مطلوب

كيفية التعامل مع الفوترة الفورية: prorated_immediately أو full_immediately أو difference_immediately أو do_not_bill.

array

الإضافات الاختيارية للخطة الجديدة. يؤدي حذف هذا الحقل أو إرسال null أو إرسال مصفوفة فارغة إلى إزالة أي إضافات موجودة، لذا يجب تضمين الإضافات الحالية للاحتفاظ بها.

string

يتحكم في السلوك عند فشل دفعة تغيير الخطة:

prevent_change: إبقاء الاشتراك على الخطة الحالية حتى نجاح الدفع
apply_change (الافتراضي): تطبيق تغيير الخطة فورًا بصرف النظر عن نتيجة الدفع

If not specified, uses the business-level default setting.

boolean

تحصيل مبلغ تغيير الخطة عبر رابط دفع بدلًا من خصم المبلغ من طريقة الدفع المحفوظة للاشتراك. يدفع العميل في صفحة دفع مستضافة.Requires the business’s allow_plan_change_via_payment_link capability (Settings → Subscriptions → Collect Plan Change Payments by Payment Link), effective_at: immediately, and on_payment_failure: prevent_change. See Collecting Payment via a Checkout Link. Ignored by the preview route.

string

عنوان URL الذي يستقبل العميل بعد دفع رابط الدفع. يضيف إعادة التوجيه subscription_id وpayment_id وstatus. يتطلب collect_via_payment_link: true؛ وإلا يفشل الطلب مع 422. راجع إعادة توجيه العميل بعد الدفع.

boolean

افتراضي:"false"

إلغاء رابط الدفع غير المدفوع الخاص بتغيير خطة معلّق، بحيث يحل هذا الطلب محله. تُرجع الدفعة المدفوعة أو الجارية 409. راجع استبدال رابط دفع معلّق. يتجاهل مسار المعاينة هذا الحقل.

array

رموز خصم متسلسلة اختيارية لتطبيقها على الخطة الجديدة (بحد أقصى 20، وتُطبّق بترتيب المصفوفة). يعتمد السلوك على القيمة التي تمررها:

غير مقدمة / null — يتم الاحتفاظ بالخصومات الحالية التي تحتوي على preserve_on_plan_change=true إذا كانت تنطبق على المنتج الجديد.
[] (مصفوفة فارغة) — إزالة جميع الخصومات الحالية من الاشتراك.
["CODE_A", "CODE_B", ...] — استبدال أي خصومات حالية بهذه المجموعة المتسلسلة.

string

مهمل

مهمل — يُفضّل استخدام discount_codes للتكاملات الجديدة. يظل هذا الحقل يعمل للتوافق مع الإصدارات السابقة، لكن لا يمكن دمجه مع discount_codes في الطلب نفسه.

string

افتراضي:"immediately"

متى يتم تطبيق تغيير الخطة:

immediately (الافتراضي): تطبيق تغيير الخطة فورًا
next_billing_date: جدولة التغيير لموعد الفوترة التالي. يحتفظ العميل بخطته الحالية حتى انتهاء فترة الفوترة. استخدم هذا الخيار للتخفيضات كي يحتفظ العملاء بمزايا خطتهم الحالية حتى نهاية فترة الفوترة.

Handle Webhook Events

أعد إعداد معالجة webhook لتتبع نتائج تغيير الخطة:

subscription.active: نجاح تغيير الخطة وتحديث الاشتراك
subscription.plan_changed: تغيير خطة الاشتراك (ترقية/تخفيض/تحديث الإضافة)
subscription.on_hold: فشل تحصيل مبلغ تغيير الخطة وإيقاف التجديدات
payment.succeeded: نجاح التحصيل الفوري لتغيير الخطة
payment.failed: فشل التحصيل الفوري

تحقق دائمًا من توقيعات webhook وطبّق معالجة idempotent للأحداث.

Update Your Application State

حدّث تطبيقك استنادًا إلى أحداث webhook:

منح الميزات أو سحبها بناءً على الخطة الجديدة
تحديث لوحة تحكم العميل بتفاصيل الخطة الجديدة
إرسال رسائل بريد إلكتروني لتأكيد تغييرات الخطة
تسجيل تغييرات الفوترة لأغراض التدقيق

Test and Monitor

اختبر تطبيقك بدقة:

اختبر جميع أوضاع proration في سيناريوهات مختلفة
تحقق من عمل معالجة webhook بصورة صحيحة
راقب معدلات نجاح تغيير الخطة
أعد إعداد تنبيهات لتغييرات الخطة الفاشلة

أصبح تطبيق تغيير خطة الاشتراك جاهزًا للاستخدام في بيئة الإنتاج.

معاينة تغييرات الخطة

قبل اعتماد تغيير الخطة، استخدم Preview API لعرض المبلغ الذي سيُحصّل من العملاء بدقة:

Node.js SDK
Python SDK

const preview = await client.subscriptions.previewChangePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

// Show customer the charge before confirming
console.log('Immediate charge:', preview.immediate_charge.summary.total_amount, preview.immediate_charge.summary.currency);
console.log('New plan details:', preview.new_plan);

preview = client.subscriptions.preview_change_plan(
    subscription_id="sub_123",
    product_id="pdt_pro",
    quantity=1,
    proration_billing_mode="prorated_immediately"
)

# Show customer the charge before confirming
print("Immediate charge:", preview.immediate_charge.summary.total_amount, preview.immediate_charge.summary.currency)
print("New plan details:", preview.new_plan)

استخدم Preview API لإنشاء مربعات حوار للتأكيد تعرض للعملاء المبلغ الدقيق الذي سيُحصّل منهم قبل تأكيد تغيير الخطة.

في immediate_charge.summary، يمثل customer_credits صافي التغيير في رصيد ائتمان العميل، بعملة customer_credits_currency. وهذه هي عملة محفظة ائتمان العميل، وهي عملة الاشتراك. وقد تختلف عن currency في الملخص، الذي ينطبق على total_amount وtax. على سبيل المثال، يرى العميل الذي يدفع بالروبية الهندية مقابل اشتراك بالدولار أرصدة ائتمانية بالدولار.

Change Plan API

استخدم Change Plan API لتعديل المنتج والكمية وسلوك proration لاشتراك نشط.

أمثلة البدء السريع

Node.js SDK
Python SDK
Go SDK
HTTP

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

async function changePlan() {
  // change-plan returns 200 with a ChangePlanResponse body (payment_id, payment_link,
  // client_secret, expires_on) — all null for an ordinary off-session change.
  await client.subscriptions.changePlan('sub_123', {
    product_id: 'pdt_new',
    quantity: 3,
    proration_billing_mode: 'prorated_immediately',
    on_payment_failure: 'prevent_change', // Optional: control behavior on payment failure
  });
  console.log('Plan change accepted; awaiting webhooks');
}

changePlan();

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",  # defaults to "live_mode"
)

# change_plan returns 200 with a ChangePlanResponse body (payment_id, payment_link,
# client_secret, expires_on) — all None for an ordinary off-session change.
client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="pdt_new",
    quantity=3,
    proration_billing_mode="prorated_immediately",
    on_payment_failure="prevent_change",  # Optional: control behavior on payment failure
)
print("Plan change accepted; awaiting webhooks")

package main

import (
  "context"
  "fmt"
  "github.com/dodopayments/dodopayments-go"
  "github.com/dodopayments/dodopayments-go/option"
)

func main() {
  client := dodopayments.NewClient(option.WithBearerToken("YOUR_TOKEN"))
  // ChangePlan returns a SubscriptionChangePlanResponse alongside the error.
  _, err := client.Subscriptions.ChangePlan(context.TODO(), "sub_123", dodopayments.SubscriptionChangePlanParams{
    UpdateSubscriptionPlanReq: dodopayments.UpdateSubscriptionPlanReqParam{
      ProductID:            dodopayments.F("pdt_new"),
      Quantity:             dodopayments.F(int64(3)),
      ProrationBillingMode: dodopayments.F(dodopayments.UpdateSubscriptionPlanReqProrationBillingModeProratedImmediately),
      OnPaymentFailure:     dodopayments.F(dodopayments.UpdateSubscriptionPlanReqOnPaymentFailurePreventChange), // Optional
    },
  })
  if err != nil { panic(err) }
  fmt.Println("Plan change applied")
}

curl -X POST "$DODO_API_BASE/subscriptions/sub_123/change-plan" \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "pdt_new",
    "quantity": 3,
    "proration_billing_mode": "prorated_immediately",
    "on_payment_failure": "prevent_change"
  }'

يُرجع تغيير الخطة الناجح 200 OK فورًا — قبل تسوية أي مبلغ فعليًا. ويعتمد محتوى الجسم (ChangePlanResponse) على طريقة تحصيل التغيير:

الحالة	`payment_id` / `payment_link` / `client_secret` / `expires_on`
تغيير مجدول (`effective_at: next_billing_date`)	جميعها `null` — لم يُحصّل أي مبلغ بعد
`proration_billing_mode: do_not_bill`	جميعها `null` — لا يوجد مبلغ لتحصيله
تحصيل فوري عادي (طريقة الدفع المحفوظة)	جميعها `null`
`collect_via_payment_link: true` (تم إصدار الرابط)	جميعها معبّأة — معرّفات checkout للعميل

يؤكد هذا الرد قبول الطلب، وليس نجاح التحصيل. في حالة التحصيل الفوري العادي، تُحسم النتيجة خارج الجلسة مباشرة بعد الاستدعاء. أما في طلب collect_via_payment_link، فيبقى الاشتراك على خطته الحالية حتى يكمل العميل الدفع.أكد النتيجة عبر webhook (payment.succeeded وpayment.failed وsubscription.plan_changed)، أو أعد قراءة الاشتراك باستخدام GET /subscriptions/{subscription_id} — راجع ما يحدث أثناء عدم دفع الرابط لحالة رابط الدفع.

إذا فشل التحصيل الفوري، فقد ينتقل الاشتراك إلى subscription.on_hold حتى نجاح الدفع.

تحصيل الدفع عبر رابط Checkout

افتراضيًا، يخصم تغيير الخطة الفوري المبلغ مباشرةً من طريقة الدفع المحفوظة للاشتراك. اضبط collect_via_payment_link: true لإرسال العميل إلى صفحة checkout مستضافة بدلًا من ذلك — وهذا مفيد عند عدم وجود طريقة دفع محفوظة أو عند رغبتك في أن يؤكد العميل السعر الجديد بنفسه.

يشغّل هذا الخيار مفتاح تحصيل دفعات تغيير الخطة عبر رابط الدفع في الإعدادات ← الاشتراكات، الذي يوجّه مسار تغيير الخطة في Customer Portal عبر checkout.

المتطلبات

ينجح collect_via_payment_link: true فقط عند تحقق جميع الشروط التالية — وإلا يفشل الطلب مع 422:

يجب تفعيل قدرة allow_plan_change_via_payment_link للنشاط التجاري (الإعدادات ← الاشتراكات ← تحصيل دفعات تغيير الخطة عبر رابط الدفع).
يجب أن تكون effective_at هي immediately (الافتراضية). لا يحتاج التغيير المجدول (next_billing_date) إلى صفحة checkout.
يجب أن يعيّن الطلب on_payment_failure: prevent_change. ويفشل apply_change الصريح مع 422.

ينطبق collect_via_payment_link على أي تغيير فوري ينتج عنه تحصيل، بما في ذلك التخفيضات، ما دامت المتطلبات أعلاه مستوفاة.

إذا كان صافي التغيير صفراً أو رصيداً دائناً، فلن يُصدر رابط دفع: يصبح payment_link وتعود حقول checkout الأخرى null، ويُطبّق التغيير فورًا. هذا ليس 422. استدعِ Preview Plan Change أولًا للتحقق من المبلغ قبل طلب رابط.

Node.js SDK
Python SDK
HTTP

const response = await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  effective_at: 'immediately',
  on_payment_failure: 'prevent_change',
  collect_via_payment_link: true,
});

// Hand response.payment_link to your frontend and send the customer there
console.log(response.payment_link);

response = client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="pdt_pro",
    quantity=1,
    proration_billing_mode="prorated_immediately",
    effective_at="immediately",
    on_payment_failure="prevent_change",
    collect_via_payment_link=True,
)

# Hand response.payment_link to your frontend and send the customer there
print(response.payment_link)

curl -X POST "$DODO_API_BASE/subscriptions/sub_123/change-plan" \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "pdt_pro",
    "quantity": 1,
    "proration_billing_mode": "prorated_immediately",
    "effective_at": "immediately",
    "on_payment_failure": "prevent_change",
    "collect_via_payment_link": true
  }'

يُرجع الطلب الناجح معرّفات checkout:

{
  "payment_id": "<payment_id>",
  "payment_link": "https://checkout.dodopayments.com/...",
  "client_secret": "<client_secret>",
  "expires_on": "<expires_on>"
}

ما يحدث أثناء عدم دفع الرابط

يبقى الاشتراك على خطته الحالية — ولا يتغير product_id أو recurring_pre_tax_amount أو next_billing_date حتى دفع الرابط.
يُرفض أي طلب change-plan إضافي مع 409 PendingPlanChangeExists أثناء تعليق الرابط. لاستبدال التغيير المعلّق، أرسل الطلب الجديد مع cancel_older_payment_link: true. راجع استبدال رابط دفع معلّق.
لإعادة المحاولة بعد رفض الدفع، استدعِ change-plan مجددًا للحصول على رابط جديد.
إذا لم يُدفع الرابط مطلقًا، فسيتوقف عن العمل بعد expires_on — ويصبح الاشتراك متاحًا تلقائيًا لقبول طلب تغيير خطة جديد بعد ذلك بوقت قصير.
إذا كان هناك تغيير مجدول مسبقًا واستبدلته بـ cancel_scheduled_change_plan: true، يظل الجدول الأصلي قائمًا أثناء عدم دفع الرابط ولا يُلغى إلا بعد دفع الرابط — في المعاملة نفسها التي تطبّق الخطة الجديدة.

بعد إصدار تغيير فوري عبر رابط دفع، يُحظر كل طلب تغيير خطة لاحق على ذلك الاشتراك — بما في ذلك المعاينة الخالية من الآثار الجانبية — حتى تُحسم حالة الرابط. ويمكن لطلب change-plan استبدال الرابط بتعيين cancel_older_payment_link: true. وتتجاهل المعاينة هذا الحقل، لذلك تظل المعاينة محظورة.

إعادة توجيه العميل بعد الدفع

اضبط return_url لإعادة العميل إلى موقعك بعد دفع الرابط:

{
  "product_id": "pdt_pro",
  "quantity": 1,
  "proration_billing_mode": "prorated_immediately",
  "on_payment_failure": "prevent_change",
  "collect_via_payment_link": true,
  "return_url": "https://example.com/billing/done"
}

بعد checkout، ينتقل العميل إلى return_url باستخدام معلمات query التالية:

المعلمة	القيمة
`subscription_id`	الاشتراك الذي يخصه تغيير الخطة.
`payment_id`	دفعة تغيير الخطة.
`status`	حالة دفعة تغيير الخطة، وليست حالة الاشتراك: `active` عند الدفع، و`failed` عند الرفض، و`pending` أثناء المعالجة.

عند فشل الدفع، يظل الاشتراك نشطًا على خطته الحالية. وقد تُطبّق الخطة الجديدة بعد إعادة التوجيه بقليل، عند وصول webhook الدفع، لذا أعد قراءة الاشتراك قبل عرض الخطة الجديدة. يتطلب return_url وجود collect_via_payment_link: true. وبدونه يفشل الطلب مع 422.

استبدال رابط دفع معلّق

إذا غادر العميل checkout دون الدفع، فعيّن cancel_older_payment_link: true في طلب change-plan التالي. تلغي Dodo Payments الرابط غير المدفوع، ويستبدل تغيير الخطة الجديد التغيير المعلّق. ولا يقبل الرابط الملغى أي دفعة، حتى من صفحة checkout مفتوحة مسبقًا.

{
  "product_id": "pdt_pro",
  "quantity": 1,
  "proration_billing_mode": "prorated_immediately",
  "on_payment_failure": "prevent_change",
  "collect_via_payment_link": true,
  "cancel_older_payment_link": true
}

يُتحقق من صحة الطلب قبل إلغاء الرابط، لذلك يحافظ الطلب غير الصالح على رابط العميل. ولا يُلغى الرابط إلا إذا لم يبدأ العميل الدفع:

الدفعة السابقة	الاستجابة
لم يُفتح الرابط، أو فُتح دون دفع، أو رُفضت الدفعة	`200` مع الرابط الجديد.
العميل يدفع حاليًا، مثلًا أثناء 3D Secure	`409` `PLAN_CHANGE_PAYMENT_IN_PROGRESS`. أعد المحاولة بعد اكتمال الدفع أو فشله.
تم الدفع مسبقًا	`409` `PLAN_CHANGE_PAYMENT_ALREADY_COMPLETED`. لا تعاود المحاولة: سيُطبّق تغيير الخطة السابق.
تعذر إلغاء الرابط	`503` `PLAN_CHANGE_LINK_CANCEL_FAILED`. لم يتغير شيء، ويمكنك إعادة المحاولة.

يُصدر كل طلب change-plan فاتورة خاصة به. ويُلغى تغيير الخطة المستبدل وفاتورته. وإذا لم يكن هناك تغيير خطة معلّق، فلن يكون لـ cancel_older_payment_link أي تأثير.

قد يفشل فحص يُجرى بعد التحقق، مثل الحد الأدنى لمبلغ التحصيل، بعد إلغاء الرابط. عندئذ يبقى الاشتراك على خطته الحالية دون رابط مفتوح. أرسل الطلب مجددًا لإصدار رابط جديد.

إدارة Addons

عند تغيير خطط الاشتراك، يمكنك أيضًا تعديل الإضافات:

// Add addons to the new plan
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [
    { addon_id: 'addon_123', quantity: 2 }
  ]
});

// Remove all existing addons
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [] // Empty array removes all existing addons
});

تُدرج الإضافات في حساب proration وتُحصّل وفق وضع proration المحدد.

تطبيق رموز الخصم

طبّق رمز خصم متسلسلًا واحدًا أو أكثر عند تغيير خطط الاشتراك (بحد أقصى 20، وتُطبّق بترتيب المصفوفة):

Node.js SDK
Python SDK
HTTP

// Apply stacked discount codes during plan change
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_codes: ['UPGRADE20']
});

# Apply stacked discount codes during plan change
client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="pdt_pro",
    quantity=1,
    proration_billing_mode="prorated_immediately",
    discount_codes=["UPGRADE20"]
)

curl -X POST "$DODO_API_BASE/subscriptions/sub_123/change-plan" \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "pdt_pro",
    "quantity": 1,
    "proration_billing_mode": "prorated_immediately",
    "discount_codes": ["UPGRADE20"]
  }'

سلوك الخصم عند تغيير الخطة

قيمة `discount_codes`	السلوك
غير مقدمة / `null`	تُحفظ الخصومات الحالية التي تحتوي على `preserve_on_plan_change=true` تلقائيًا إذا كانت تنطبق على المنتج الجديد.
`[]` (مصفوفة فارغة)	تُزال كل الخصومات الحالية من الاشتراك.
`["CODE_A", "CODE_B", ...]`	استبدال أي خصومات حالية بهذه المجموعة المتسلسلة، بعد التحقق منها وتطبيقها بترتيب المصفوفة.

حقل discount_code المفرد في نقطة النهاية هذه مهمل لكنه لا يزال يعمل للتوافق مع الإصدارات السابقة — ولا تحتاج التكاملات الحالية إلى التغيير فورًا. ولا يمكن دمجه مع discount_codes في الطلب نفسه. انقل التكامل إلى صيغة المصفوفة عندما يناسبك.

استخدم Preview Plan Change API مع discount_codes لعرض المبلغ الذي سيوفره العملاء بدقة قبل تأكيد تغيير الخطة.

أوضاع Proration

اختر كيفية فوترة العميل عند تغيير الخطط:

`prorated_immediately`

إضافة رصيد للجزء غير المستخدم من الدورة الحالية — الخطة الأساسية والكمية والإضافات — محسوبًا تناسبيًا وفق الوقت المتبقي
ثم تحصيل دورة كاملة بالخطة والكمية والإضافات الجديدة. ولا يُحسب مبلغ التحصيل نفسه تناسبيًا
صافي التحصيل الفوري = (الدورة الجديدة الكاملة) − (الكسر المتبقي × الدورة القديمة الكاملة)
إذا تجاوز الرصيد مبلغ الدورة الجديدة (وهو شائع في التخفيضات)، يُحتفظ بالفرق كرصيد خاص بالاشتراك للتجديدات المستقبلية
أثناء الفترة التجريبية، يتم التحصيل فورًا والتبديل إلى الخطة الجديدة الآن

`full_immediately`

تحصيل المبلغ الكامل للخطة الجديدة فورًا
تجاهل الوقت المتبقي من الخطة القديمة — لا يوجد رصيد للدورة الحالية

الأرصدة التي ينشئها prorated_immediately وتلك الناتجة عن التخفيضات باستخدام difference_immediately تكون خاصة بالاشتراك، وهي منفصلة عن استحقاقات Credit-Based Billing. وتُطبّق تلقائيًا على التجديدات المستقبلية للاشتراك نفسه، ولا يمكن نقلها بين الاشتراكات.

`difference_immediately`

الترقية: تحصيل فرق السعر بين الخطتين القديمة والجديدة فورًا
التخفيض: إضافة القيمة المتبقية كرصيد داخلي إلى الاشتراك وتطبيقها تلقائيًا عند التجديد

`do_not_bill`

لا تُحسب أي تحصيلات أو أرصدة
ينتقل العميل إلى الخطة الجديدة فورًا دون تعديل في الفوترة
تبقى دورة الفوترة دون تغيير
مناسب لعمليات النقل المجانية أو المجاملة أو استيعاب فروق التكلفة

الميزة	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
تحصيل الترقية	دورة جديدة كاملة مطروحًا منها رصيد الوقت غير المستخدم	فرق السعر الكامل بين الخطتين	السعر الكامل للخطة الجديدة	لا يوجد تحصيل
رصيد التخفيض	رصيد الوقت غير المستخدم مطروحًا منه دورة جديدة كاملة	فرق السعر الكامل كرَصيد	لا يوجد رصيد	لا يوجد رصيد
دورة الفوترة	تُعاد من تاريخ اليوم	تُعاد من تاريخ اليوم	تُعاد من تاريخ اليوم	دون تغيير
سلوك الفترة التجريبية	تنتهي الفترة التجريبية ويُحصّل المبلغ فورًا	تنتهي الفترة التجريبية ويُحصّل المبلغ فورًا	تنتهي الفترة التجريبية ويُحصّل المبلغ كاملًا	يبقى تاريخ انتهاء الفترة التجريبية دون تحصيل
مناسب لـ	إضافة رصيد للوقت غير المستخدم	حسابات الترقية/التخفيض البسيطة	إعادة ضبط دورات الفوترة	عمليات النقل المجانية أو المجاملة
التعقيد	متوسط (حساب الأيام)	منخفض (طرح بسيط)	منخفض (تحصيل كامل)	لا يوجد

أمثلة على السيناريوهات

استخدم هذه الأرقام الأساسية باستمرار:

الخطة الحالية: Basic بسعر $30/شهر
هدف الترقية: Pro بسعر $80/شهر
هدف التخفيض (من Pro): Starter بسعر $20/شهر
دورة الفوترة: 30 يومًا، بدأت في 1 يناير
يحدث تغيير الخطة في 16 يناير (15 يومًا متبقية، و15 يومًا مستخدمة)

Upgrade: Basic ($30) → Pro ($80) with prorated_immediately

Step 1: Credit the unused time on the current plan
  Unused days = 15 out of 30 days
  Credit = $30 × (15/30) = $15.00

Step 2: Charge a full cycle at the new plan
  New plan cost = $80.00 (never prorated)

Step 3: Calculate immediate charge
  Charge = Full new cycle − Credit
  Charge = $80.00 − $15.00 = $65.00

→ Customer pays $65.00 now
→ Customer starts a full month of Pro today
→ Billing cycle resets to today (January 16)
→ Next renewal (Feb 15): $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
})

Downgrade: Pro ($80) → Starter ($20) with prorated_immediately

Step 1: Credit the unused time on the current plan
  Unused days = 15 out of 30 days
  Credit = $80 × (15/30) = $40.00

Step 2: Charge a full cycle at the new plan
  New plan cost = $20.00 (never prorated)

Step 3: Net the two
  Net = $20.00 − $40.00 = −$20.00

→ No charge — $20.00 credit added to subscription
→ Billing cycle resets to today (January 16)
→ Credit auto-applies to future renewals
→ Next renewal (Feb 15): $20.00 − $20.00 (from credit) = $0.00 (credit exhausted)
→ Following renewal (Mar 15): $20.00

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_starter',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
})

Upgrade: Basic ($30) → Pro ($80) with difference_immediately

Immediate charge = New plan price − Old plan price
                 = $80 − $30
                 = $50.00

→ Customer pays $50.00 now (regardless of cycle position)
→ Billing cycle resets to today (January 16)
→ Next renewal (Feb 15): $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
})

Downgrade: Pro ($80) → Starter ($20) with difference_immediately

Credit = Old plan price − New plan price
       = $80 − $20
       = $60.00

→ No charge — $60.00 credit added to subscription
→ Credit auto-applies to future renewals
→ Next renewal: $20.00 − $20.00 (from credit) = $0.00
→ Following renewal: $20.00 − $20.00 (from credit) = $0.00
→ Third renewal: $20.00 − $20.00 (from remaining credit) = $0.00

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_starter',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
})

Upgrade: Basic ($30) → Pro ($80) with full_immediately

Immediate charge = Full new plan price = $80.00

→ Customer pays $80.00 now
→ No credit for unused time on old plan
→ Billing cycle resets to today (January 16)
→ Next renewal: February 16 at $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'full_immediately'
})

Mid-cycle upgrade with add-ons using prorated_immediately

Current: Basic plan ($30/month), no add-ons
New: Pro plan ($80/month) + Extra Seats add-on ($10/seat × 3 seats = $30/month)
Change on day 16 of 30 (15 days remaining)

Step 1: Credit the unused time on the current plan
  Credit = $30 × (15/30) = $15.00

Step 2: Charge a full cycle at the new plan + add-ons
  New plan = $80.00
  Add-ons  = $30.00
  Total new = $110.00 (never prorated)

Step 3: Immediate charge
  Charge = $110.00 − $15.00 = $95.00

→ Customer pays $95.00 now
→ Next renewal: $80.00 + $30.00 = $110.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  addons: [
    { addon_id: 'addon_seats', quantity: 3 }
  ]
})

كيفية معالجة كل وضع للفوترة

اختر prorated_immediately لإضافة رصيد للوقت غير المستخدم في الخطة القديمة مع تحصيل دورة كاملة من الخطة الجديدة؛ واختر full_immediately لإعادة بدء الفوترة؛ واستخدم difference_immediately للترقيات البسيطة وإضافة رصيد تلقائية عند التخفيضات؛ أو استخدم do_not_bill لتبديل الخطط دون أي تعديل في الفوترة.

معالجة حالات فشل الدفع

تحكم في ما يحدث عند فشل دفعة تغيير الخطة باستخدام المعلمة on_payment_failure.

أوضاع فشل الدفع

prevent_change (Recommended for critical upgrades)
apply_change (Default)

السلوك: إبقاء الاشتراك على خطته الحالية حتى نجاح الدفع.

يُعلّم تغيير الخطة بأنه “معلّق”
يحتفظ العميل بإمكانية الوصول إلى خطته الحالية
ينتقل الاشتراك إلى حالة active فقط بعد نجاح الدفع
مفيد عند الرغبة في ضمان الدفع قبل منح الميزات المُرقّاة

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  on_payment_failure: 'prevent_change'
});

السلوك: تطبيق تغيير الخطة فورًا بصرف النظر عن نتيجة الدفع.

يُطبّق تغيير الخطة حتى عند فشل الدفع
يحصل العميل فورًا على إمكانية الوصول إلى الخطة الجديدة
قد ينتقل الاشتراك إلى حالة on_hold عند فشل الدفع
مناسب للترقيات غير الحرجة أو عند الثقة بالعميل

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  on_payment_failure: 'apply_change' // This is the default
});

إذا لم تُحدّد، تستخدم المعلمة on_payment_failure إعدادك الافتراضي على مستوى النشاط التجاري والمكوّن في لوحة التحكم.

متى تستخدم كل وضع

السيناريو	الوضع الموصى به	السبب
الترقية إلى ميزات متميزة	`prevent_change`	ضمان الدفع قبل منح الوصول
زيادة الكمية (مقاعد أكثر)	`prevent_change`	منع الاستخدام دون دفع
تخفيض الخطط	`apply_change`	العميل يقلل إنفاقه
عملاء المؤسسات الموثوقون	`apply_change`	مخاطر أقل لعدم الدفع
التحويل من التجربة إلى الدفع	`prevent_change`	لحظة دفع حاسمة

الإعدادات الافتراضية للنشاط التجاري والتحصيل

عيّن سلوك الترقية والتخفيض الافتراضي على مستوى النشاط التجاري ضمن الإعدادات ← الاشتراكات. وتنطبق هذه الإعدادات الافتراضية على جميع تغييرات الخطة في بوابة العملاء، ويمكن تجاوزها لكل مجموعة منتجات. توجد إعدادات افتراضية منفصلة للترقيات والتخفيضات:

الإعداد	الحقل (الترقية / التخفيض)	الافتراضي (الترقية)	الافتراضي (التخفيض)
متى تبدأ الخطة الجديدة	`effective_at_on_upgrade` / `effective_at_on_downgrade`	`immediately`	`next_billing_date`
كيفية تحصيل المبلغ من العميل	`proration_billing_mode_on_upgrade` / `proration_billing_mode_on_downgrade`	`difference_immediately`	`difference_immediately`
إذا فشل دفع العميل	`on_payment_failure`	`apply_change`	`apply_change`

اضبط الإعدادات الافتراضية للنشاط التجاري ضمن الإعدادات ← الاشتراكات، وتجاوزات المجموعات في كل مجموعة منتجات. كل حقل في المجموعة مستقل — اتركه دون تعيين ليرث الإعداد الافتراضي للنشاط التجاري، أو عيّن قيمة لتجاوز ذلك الإعداد.

ترتيب تحديد القيمة

بالنسبة إلى أي تغيير خطة، تُحدّد قيمة كل إعداد بالترتيب التالي:

per-request value (Change Plan API) → collection field (if set) → business field → system default

تتغلب القيمة الممررة صراحةً إلى Change Plan API دائمًا على غيرها. ولا تصبح الإعدادات الافتراضية للنشاط التجاري والمجموعة فعالة إلا عند عدم توفير قيمة صريحة — وهذا هو الحال لجميع تغييرات الخطة التي تبدأ من بوابة العملاء.

إعداد شائع: أبقِ الترقيات على immediately + difference_immediately كي يدفع العملاء الفرق ويحصلوا على الوصول فورًا، وأبقِ التخفيضات على next_billing_date كي يحتفظ العملاء بخطتهم الحالية حتى انتهاء الدورة.

معالجة Webhooks

تتبّع حالة الاشتراك عبر webhooks لتأكيد تغييرات الخطة والمدفوعات.

أنواع الأحداث التي يجب معالجتها

subscription.active: تفعيل الاشتراك
subscription.plan_changed: تغيير خطة الاشتراك (ترقية/تخفيض/تغييرات الإضافات)
subscription.on_hold: فشل التحصيل وإيقاف التجديدات
subscription.renewed: نجاح التجديد
payment.succeeded: نجاح الدفع الخاص بتغيير الخطة أو التجديد
payment.failed: فشل الدفع

أنشئ منطق الأعمال استنادًا إلى أحداث الاشتراك، واستخدم أحداث الدفع للتأكيد والمطابقة.

التحقق من التوقيعات ومعالجة النوايا

Next.js Route Handler
Express.js

import { NextRequest, NextResponse } from 'next/server';

export async function POST(req) {
  const webhookId = req.headers.get('webhook-id');
  const webhookSignature = req.headers.get('webhook-signature');
  const webhookTimestamp = req.headers.get('webhook-timestamp');
  const secret = process.env.DODO_PAYMENTS_WEBHOOK_KEY;

  const payload = await req.text();
  // verifySignature is a placeholder – in production, use a Standard Webhooks library
  const { valid, event } = await verifySignature(
    payload,
    { id: webhookId, signature: webhookSignature, timestamp: webhookTimestamp },
    secret
  );
  if (!valid) return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });

  switch (event.type) {
    case 'subscription.active':
      // mark subscription active in your DB
      break;
    case 'subscription.plan_changed':
      // refresh entitlements and reflect the new plan in your UI
      break;
    case 'subscription.on_hold':
      // notify user to update payment method
      break;
    case 'subscription.renewed':
      // extend access window
      break;
    case 'payment.succeeded':
      // reconcile payment for plan change
      break;
    case 'payment.failed':
      // log and alert
      break;
    default:
      // ignore unknown events
      break;
  }

  return NextResponse.json({ received: true });
}

import express from 'express';

const app = express();
app.post('/webhooks/dodo', express.raw({ type: 'application/json' }), async (req, res) => {
  const webhookId = req.header('webhook-id');
  const webhookSignature = req.header('webhook-signature');
  const webhookTimestamp = req.header('webhook-timestamp');
  const secret = process.env.DODO_PAYMENTS_WEBHOOK_KEY;
  const payload = req.body.toString('utf8');

  const { valid, event } = await verifySignature(
    payload,
    { id: webhookId, signature: webhookSignature, timestamp: webhookTimestamp },
    secret
  );
  if (!valid) return res.status(400).send('Invalid signature');

  // handle events like above
  res.json({ received: true });
});

app.listen(3000);

للاطلاع على مخططات payload التفصيلية، راجع payloads الخاصة بـ Subscription webhook وpayloads الخاصة بـ Payment webhook.

أفضل الممارسات

استراتيجية تغيير الخطة

اختبر بدقة: اختبر دائمًا تغييرات الخطة في وضع الاختبار قبل الإنتاج
اختر proration بعناية: حدّد وضع proration المتوافق مع نموذج نشاطك التجاري
تعامل مع حالات الفشل بسلاسة: طبّق معالجة مناسبة للأخطاء ومنطقًا لإعادة المحاولة
راقب معدلات النجاح: تتبّع معدلات نجاح وفشل تغيير الخطة وحقق في المشكلات

تطبيق Webhook

تحقق من التوقيعات: تحقق دائمًا من توقيعات webhook لضمان الأصالة
طبّق idempotency: عالج أحداث webhook المكررة بسلاسة
عالج الأحداث بشكل غير متزامن: لا تحظر استجابات webhook بعمليات ثقيلة
سجّل كل شيء: احتفظ بسجلات مفصلة لتصحيح الأخطاء وأغراض التدقيق

تجربة المستخدم

تواصل بوضوح: أبلغ العملاء بتغييرات الفوترة وتوقيتها
وفّر التأكيدات: أرسل رسائل بريد إلكتروني لتأكيد تغييرات الخطة الناجحة
تعامل مع الحالات الحدّية: ضع الفترات التجريبية وproration والمدفوعات الفاشلة في الاعتبار
حدّث الواجهة فورًا: اعكس تغييرات الخطة في واجهة تطبيقك

المشكلات الشائعة والحلول

حل المشكلات المعتادة التي تحدث أثناء تغييرات خطة الاشتراك:

Charge created but subscription not updated

الأعراض: ينجح استدعاء API لكن يظل الاشتراك على الخطة القديمةالأسباب الشائعة:

فشلت معالجة webhook أو تأخرت
لم تُحدّث حالة التطبيق بعد استلام webhooks
مشكلات في معاملة قاعدة البيانات أثناء تحديث الحالة

الحلول:

طبّق معالجة webhook مع منطق لإعادة المحاولة
استخدم عمليات idempotent لتحديث الحالة
أضف المراقبة لاكتشاف أحداث webhook الفائتة والتنبيه إليها
تحقق من إمكانية الوصول إلى نقطة نهاية webhook واستجابتها بصورة صحيحة

Credits not applied after downgrade

الأعراض: يخفض العميل خطته لكنه لا يرى رصيدًا ائتمانيًاالأسباب الشائعة:

توقعات وضع proration: تمنح التخفيضات رصيد فرق سعر الخطة الكامل باستخدام difference_immediately، بينما يمنح prorated_immediately رصيد الوقت غير المستخدم في الدورة القديمة ثم يحصّل دورة كاملة بالخطة الجديدة — لذلك لا يبقى رصيد إلا عندما يتجاوز ذلك الرصيد سعر الخطة الجديدة
الأرصدة خاصة بالاشتراك ولا تنتقل بين الاشتراكات
رصيد الائتمان غير ظاهر في لوحة تحكم العميل

الحلول:

استخدم difference_immediately للتخفيضات عندما تريد أرصدة تلقائية
وضّح للعملاء أن الأرصدة تُطبّق على التجديدات المستقبلية للاشتراك نفسه
طبّق Customer Portal لعرض الأرصدة الائتمانية
تحقق من معاينة الفاتورة التالية لرؤية الأرصدة المطبّقة

Webhook signature verification fails

الأعراض: رُفضت أحداث webhook بسبب توقيع غير صالحالأسباب الشائعة:

مفتاح webhook السري غير صحيح
تعديل جسم الطلب الخام قبل التحقق من التوقيع
خوارزمية تحقق من التوقيع غير صحيحة

الحلول:

تحقق من استخدام DODO_PAYMENTS_WEBHOOK_KEY الصحيح من لوحة التحكم
اقرأ جسم الطلب الخام قبل أي middleware لتحليل JSON
استخدم مكتبة التحقق القياسية من webhook لمنصتك
اختبر التحقق من توقيع webhook في بيئة التطوير

Plan change fails with 422 error

الأعراض: تُرجع API خطأ 422 Unprocessable Entityالأسباب الشائعة:

معرّف اشتراك أو منتج غير صالح
الاشتراك ليس في حالة نشطة
معلمات مطلوبة مفقودة
المنتج غير متاح لتغييرات الخطة

الحلول:

تحقق من وجود الاشتراك وكونه نشطًا
تحقق من صلاحية معرّف المنتج وتوفره
تأكد من توفير جميع المعلمات المطلوبة
راجع وثائق API لمعرفة متطلبات المعلمات

Immediate charge fails during plan change

الأعراض: بدأ تغيير الخطة لكن فشل التحصيل الفوريالأسباب الشائعة:

عدم كفاية الأموال في طريقة دفع العميل
انتهاء صلاحية طريقة الدفع أو عدم صلاحيتها
رفض البنك للمعاملة
حظر التحصيل بواسطة اكتشاف الاحتيال

الحلول:

عالج أحداث webhook الخاصة بـ payment.failed بصورة مناسبة
أبلغ العميل بتحديث طريقة الدفع
طبّق منطق إعادة المحاولة لحالات الفشل المؤقتة
فكّر في السماح بتغييرات الخطة مع فشل التحصيلات الفورية

Subscription on hold after plan change

الأعراض: فشلت دفعة تغيير الخطة وانتقل الاشتراك إلى حالة on_holdما يحدث: عند فشل تحصيل تغيير الخطة، يُوضَع الاشتراك تلقائيًا في حالة on_hold. ولن يُجدّد الاشتراك تلقائيًا حتى تُحدّث طريقة الدفع.الحل: حدّث طريقة الدفع لإعادة تفعيل الاشتراكلإعادة تفعيل اشتراك من حالة on_hold بعد فشل تغيير الخطة:

حدّث طريقة الدفع باستخدام Update Payment Method API
إنشاء التحصيل تلقائيًا: تنشئ API تحصيلًا تلقائيًا للمبالغ المستحقة المتبقية
إنشاء الفاتورة: تُنشأ فاتورة للتحصيل
معالجة الدفع: تُعالج الدفعة باستخدام طريقة الدفع الجديدة
إعادة التفعيل: عند نجاح الدفع، يُعاد تفعيل الاشتراك إلى حالة active

// Reactivate subscription from on_hold after failed plan change
async function reactivateAfterFailedPlanChange(subscriptionId) {
  // Update payment method - automatically creates charge for remaining dues
  const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
    payment_method: { type: 'new', return_url: 'https://example.com/return' }
  });
  
  if (response.payment_id) {
    console.log('Charge created for remaining dues:', response.payment_id);
    console.log('Payment link:', response.payment_link);
    
    // Redirect customer to payment_link to complete payment
    // Monitor webhooks for:
    // 1. payment.succeeded - charge succeeded
    // 2. subscription.active - subscription reactivated
  }
  
  return response;
}

// Or use existing payment method if available
async function reactivateWithExistingPaymentMethod(subscriptionId, paymentMethodId) {
  const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
    payment_method: { type: 'existing', payment_method_id: paymentMethodId }
  });
  
  // Monitor webhooks for payment.succeeded and subscription.active
  return response;
}

# Reactivate subscription from on_hold after failed plan change
def reactivate_after_failed_plan_change(subscription_id):
    # Update payment method - automatically creates charge for remaining dues
    response = client.subscriptions.update_payment_method(
        subscription_id=subscription_id,
        payment_method={"type": "new", "return_url": "https://example.com/return"},
    )
    
    if response.payment_id:
        print("Charge created for remaining dues:", response.payment_id)
        print("Payment link:", response.payment_link)
        
        # Redirect customer to payment_link to complete payment
        # Monitor webhooks for:
        # 1. payment.succeeded - charge succeeded
        # 2. subscription.active - subscription reactivated
    
    return response

# Or use existing payment method if available
def reactivate_with_existing_payment_method(subscription_id, payment_method_id):
    response = client.subscriptions.update_payment_method(
        subscription_id=subscription_id,
        payment_method={"type": "existing", "payment_method_id": payment_method_id},
    )
    
    # Monitor webhooks for payment.succeeded and subscription.active
    return response

أحداث webhook التي يجب مراقبتها:

subscription.on_hold: وضع الاشتراك قيد التعليق (يُستلم عند فشل تحصيل تغيير الخطة)
payment.succeeded: نجاح دفع المبالغ المستحقة المتبقية (بعد تحديث طريقة الدفع)
subscription.active: إعادة تفعيل الاشتراك بعد نجاح الدفع

أفضل الممارسات:

أبلغ العملاء فورًا عند فشل تحصيل تغيير الخطة
وفّر تعليمات واضحة حول كيفية تحديث طريقة الدفع
راقب أحداث webhook لتتبع حالة إعادة التفعيل
فكّر في تطبيق منطق إعادة المحاولة التلقائية لفشل الدفع المؤقت

Update Payment Method API Reference

اطّلع على وثائق API الكاملة لتحديث طرق الدفع وإعادة تفعيل الاشتراكات.

اختبار تطبيقك

اختبر تطبيق تغيير خطة الاشتراك بدقة:

Set up test environment

استخدم مفاتيح API ومنتجات الاختبار
أنشئ اشتراكات اختبار بأنواع خطط مختلفة
اضبط نقطة نهاية webhook للاختبار
أعد إعداد المراقبة والتسجيل

Test different proration modes

اختبر prorated_immediately مع مواضع مختلفة في دورة الفوترة
اختبر difference_immediately للترقيات والتخفيضات
اختبر full_immediately لإعادة ضبط دورات الفوترة
اختبر do_not_bill لتبديلات الخطط دون تحصيل أو رصيد
تحقق من صحة حسابات الأرصدة

Test webhook handling

تحقق من استلام جميع أحداث webhook ذات الصلة
اختبر التحقق من توقيع webhook
عالج أحداث webhook المكررة بسلاسة
اختبر سيناريوهات فشل معالجة webhook

Test error scenarios

اختبر باستخدام معرّفات اشتراك غير صالحة
اختبر باستخدام طرق دفع منتهية الصلاحية
اختبر حالات فشل الشبكة وانتهاء المهلة
اختبر باستخدام أموال غير كافية

Monitor in production

أعد إعداد تنبيهات لتغييرات الخطة الفاشلة
راقب أوقات معالجة webhook
تتبّع معدلات نجاح تغيير الخطة
راجع تذاكر دعم العملاء بحثًا عن مشكلات تغيير الخطة

معالجة الأخطاء

عالج أخطاء API الشائعة بسلاسة في تطبيقك:

رموز حالة HTTP

200 OK

تمت معالجة طلب تغيير الخطة بنجاح. جسم الاستجابة هو ChangePlanResponse مع payment_id وpayment_link وclient_secret وexpires_on. وجميعها الأربعة قابلة لأن تكون null، لذلك يُسلسل الجسم كـ {} في حالة التغيير العادي خارج الجلسة؛ وتُملأ عند نجاح طلب collect_via_payment_link، الذي يُرجع معرّفات checkout — راجع تحصيل الدفع عبر رابط Checkout. وإذا كان on_payment_failure=prevent_change، يظل تغيير الخطة معلّقًا حتى نجاح الدفع.

400 Bad Request

معلمات الطلب غير صالحة. تحقق من توفير جميع الحقول المطلوبة وتنسيقها بصورة صحيحة.

401 Unauthorized

مفتاح API غير صالح أو مفقود. تحقق من صحة DODO_PAYMENTS_API_KEY وامتلاكه الأذونات المناسبة.

409 Conflict

يوجد تغيير خطة معلّق بالفعل لهذا الاشتراك (PendingPlanChangeExists). بالنسبة إلى تغيير مجدول، ألغِه باستخدام DELETE /subscriptions/{subscription_id}/change-plan/scheduled قبل إرسال تغيير جديد. وبالنسبة إلى تغيير عبر رابط دفع معلّق، أرسل الطلب الجديد مع cancel_older_payment_link: true لاستبداله. راجع استبدال رابط دفع معلّق.عند استخدام cancel_older_payment_link: true، يعني 409 أن العميل يدفع الرابط السابق الآن (PLAN_CHANGE_PAYMENT_IN_PROGRESS) أو دفعه بالفعل (PLAN_CHANGE_PAYMENT_ALREADY_COMPLETED).

503 Service Unavailable

عند استخدام cancel_older_payment_link: true، تعذر إلغاء رابط الدفع السابق (PLAN_CHANGE_LINK_CANCEL_FAILED). لم يتغير شيء، ويمكنك إعادة محاولة الطلب.

422 Unprocessable Entity

الاشتراك غير نشط أو عند الطلب، أو أن الطلب غير مؤهل لـ collect_via_payment_link — إذ لم يفعّل النشاط التجاري القدرة، أو أن effective_at ليست immediately، أو أن on_payment_failure ليست prevent_change. راجع المتطلبات. ويُرجع معرّف الاشتراك غير الموجود أو غير التابع لحسابك 404 مع رمز NOT_FOUND.

500 Internal Server Error

حدث خطأ في الخادم. أعد محاولة الطلب بعد تأخير قصير.

تنسيق استجابة الخطأ

تُرجع الأخطاء جسم JSON يحتوي على code وmessage قابل للقراءة البشرية:

{
  "code": "INACTIVE_SUBSCRIPTION_PLAN_CHANGE_NOT_SUPPORTED",
  "message": "Changing plans is not supported for inactive subscriptions"
}

راجع رموز الخطأ للاطلاع على القائمة الكاملة.

الخطوات التالية

راجع Change Plan API
استكشف Credit-Based Billing
طبّق تنبيهات لـ subscription.on_hold
اطّلع على دليل تكامل Webhook

آخر تعديل في ٨ أكتوبر ٢٠٢٦

Change Plan API

Plan Change Preview

Integration Guide

​What Is a Subscription Upgrade or Downgrade?

​When to Use Plan Changes

​Plan Change Flow

​Prerequisites

​Step-by-Step Implementation Guide

​معاينة تغييرات الخطة

​Change Plan API

​أمثلة البدء السريع

​تحصيل الدفع عبر رابط Checkout

​المتطلبات

​ما يحدث أثناء عدم دفع الرابط

​إعادة توجيه العميل بعد الدفع

​استبدال رابط دفع معلّق

​إدارة Addons

​تطبيق رموز الخصم

​سلوك الخصم عند تغيير الخطة

​أوضاع Proration

​prorated_immediately

​full_immediately

​difference_immediately

​do_not_bill

​أمثلة على السيناريوهات

​كيفية معالجة كل وضع للفوترة

​معالجة حالات فشل الدفع

​أوضاع فشل الدفع

​متى تستخدم كل وضع

​الإعدادات الافتراضية للنشاط التجاري والتحصيل

​ترتيب تحديد القيمة

​معالجة Webhooks

​أنواع الأحداث التي يجب معالجتها

​التحقق من التوقيعات ومعالجة النوايا

​أفضل الممارسات

​استراتيجية تغيير الخطة

​تطبيق Webhook

​تجربة المستخدم

​المشكلات الشائعة والحلول

Update Payment Method API Reference

​اختبار تطبيقك

​معالجة الأخطاء

​رموز حالة HTTP

​تنسيق استجابة الخطأ

​الخطوات التالية

What Is a Subscription Upgrade or Downgrade?

When to Use Plan Changes

Plan Change Flow

Prerequisites

Step-by-Step Implementation Guide

معاينة تغييرات الخطة

Change Plan API

أمثلة البدء السريع

تحصيل الدفع عبر رابط Checkout

المتطلبات

ما يحدث أثناء عدم دفع الرابط

إعادة توجيه العميل بعد الدفع

استبدال رابط دفع معلّق

إدارة Addons

تطبيق رموز الخصم

سلوك الخصم عند تغيير الخطة

أوضاع Proration

`prorated_immediately`

`full_immediately`

`difference_immediately`

`do_not_bill`

أمثلة على السيناريوهات

كيفية معالجة كل وضع للفوترة

معالجة حالات فشل الدفع

أوضاع فشل الدفع

متى تستخدم كل وضع

الإعدادات الافتراضية للنشاط التجاري والتحصيل

ترتيب تحديد القيمة

معالجة Webhooks

أنواع الأحداث التي يجب معالجتها

التحقق من التوقيعات ومعالجة النوايا

أفضل الممارسات

استراتيجية تغيير الخطة

تطبيق Webhook

تجربة المستخدم

المشكلات الشائعة والحلول

اختبار تطبيقك

معالجة الأخطاء

رموز حالة HTTP

تنسيق استجابة الخطأ

الخطوات التالية