دليل ترقية وتخفيض الاشتراك

​

ما هي ترقية أو تخفيض الاشتراك؟

• مواءمة الأسعار مع الاستخدام أو الميزات
• الانتقال من شهري إلى سنوي (أو العكس)
• ضبط الكمية للمنتجات المعتمدة على المقاعد

​

متى يجب استخدام تغييرات الخطط

• ترقية عندما يحتاج العميل إلى المزيد من الميزات أو الاستخدام أو المقاعد
• تخفيض عندما ينخفض الاستخدام
• نقل المستخدمين إلى منتج أو سعر جديد دون إلغاء اشتراكهم

​

المتطلبات الأساسية

• حساب تاجر Dodo Payments مع منتجات اشتراك نشطة
• بيانات اعتماد واجهة برمجة التطبيقات (مفتاح API ومفتاح سر الويب هوك) من لوحة التحكم
• اشتراك نشط موجود لتعديله
• نقطة نهاية الويب هوك مكونة للتعامل مع أحداث الاشتراك

​

دليل التنفيذ خطوة بخطوة

​

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

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

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

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

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

​

واجهة برمجة التطبيقات لتغيير الخطة

​

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

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() {
  const result = await client.subscriptions.changePlan('sub_123', {
    product_id: 'prod_new',
    quantity: 3,
    proration_billing_mode: 'prorated_immediately',
  });
  console.log(result.status, result.invoice_id, result.payment_id);
}

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"
)

result = client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="prod_new",
    quantity=3,
    proration_billing_mode="prorated_immediately",
)
print(result.status, result.get("invoice_id"), result.get("payment_id"))

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"))
  res, err := client.Subscriptions.ChangePlan(context.TODO(), dodopayments.SubscriptionChangePlanParams{
    SubscriptionID: dodopayments.F("sub_123"),
    ProductID:             dodopayments.F("prod_new"),
    Quantity:              dodopayments.F(int64(3)),
    ProrationBillingMode:  dodopayments.F(dodopayments.SubscriptionChangePlanParamsProrationBillingModeProratedImmediately),
  })
  if err != nil { panic(err) }
  fmt.Println(res.Status, res.InvoiceID, res.PaymentID)
}

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": "prod_new",
    "quantity": 3,
    "proration_billing_mode": "prorated_immediately"
  }'

{
  "status": "processing",
  "subscription_id": "sub_123",
  "invoice_id": "inv_789",
  "payment_id": "pay_456",
  "proration_billing_mode": "prorated_immediately"
}

​

إدارة الإضافات

// Add addons to the new plan
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_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: 'prod_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [] // Empty array removes all existing addons
});

​

أوضاع النسبة المئوية

​

prorated_immediately

• تحصيل الرسوم عن الفرق الجزئي في الدورة الحالية
• إذا كانت في فترة تجريبية، يتم التحصيل على الفور ويتم الانتقال إلى الخطة الجديدة الآن
• تخفيض: قد ينتج عنه ائتمان نسبي يُطبق على التجديدات المستقبلية

​

full_immediately

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

​

difference_immediately

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

​

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

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
})
// Immediate charge: $50

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_starter',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
})
// Credit added: $30 (auto-applied to future renewals for this subscription)

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_new',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
})
// Immediate prorated charge based on remaining days in cycle

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_new',
  quantity: 1,
  proration_billing_mode: 'full_immediately'
})
// Immediate full charge for new plan; no credits calculated

​

التعامل مع الويب هوكس

​

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

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

​

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

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_WEBHOOK_SECRET;

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

​

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

​

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

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

​

تنفيذ الويب هوك

• تحقق من التوقيعات: تحقق دائمًا من توقيعات الويب هوك لضمان الأصالة
• نفذ عدم القابلية للتكرار: تعامل مع أحداث الويب هوك المكررة بسلاسة
• قم بالمعالجة بشكل غير متزامن: لا تقم بحظر استجابات الويب هوك بعمليات ثقيلة
• سجل كل شيء: احتفظ بسجلات مفصلة لأغراض التصحيح والتدقيق

​

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

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

​

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

// 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, {
    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, {
    type: 'existing',
    payment_method_id: paymentMethodId
  });
  
  // Monitor webhooks for payment.succeeded and subscription.active
  return response;
}

​

اختبار تنفيذك

​

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

​

رموز حالة HTTP

​

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

{
  "error": {
    "code": "subscription_not_found",
    "message": "The subscription with ID 'sub_123' was not found",
    "details": {
      "subscription_id": "sub_123"
    }
  }
}

​

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

• مراجعة واجهة برمجة التطبيقات لتغيير الخطة
• استكشاف الائتمانات الخاصة بالعملاء
• تنفيذ تنبيهات لـ subscription.on_hold
• تحقق من دليل تكامل الويب هوك