Upsells & Downsells

تُتيح عمليات الترقيات والتخفيضات عرض منتجات إضافية أو تغييرات في الخطط للعملاء باستخدام طرق الدفع المحفوظة لديهم. هذا يمكِّن من عمليات شراء بنقرة واحدة تتخطى جمع بيانات الدفع، مما يحسّن معدلات التحويل بشكل كبير.

Post-Purchase Upsells

عرض منتجات تكميلية فور الانتهاء من الدفع مع إمكانية شراء بنقرة واحدة.

Subscription Upgrades

نقل العملاء إلى مستويات أعلى مع التوزيع التلقائي للرسوم والفوترة الفورية.

Cross-Sells

إضافة منتجات ذات صلة للعملاء الحاليين دون الحاجة إلى إعادة إدخال بيانات الدفع.

Overview

الترقيات والتخفيضات تعتبر استراتيجيات قوية لتحسين الإيرادات:

Upsells: عرض منتج أعلى قيمة أو ترقية (مثل خطة Pro بدلًا من Basic)
Downsells: عرض خيار بسعر أقل عندما يرفض العميل أو يطلب تخفيضًا
Cross-sells: اقتراح منتجات تكميلية (مثل الإضافات أو العناصر ذات الصلة)

تمكِّن Dodo Payments هذه التدفقات عبر المعامل payment_method_id، الذي يتيح لك تحصيل مقابل طريقة الدفع المحفوظة للعميل دون الحاجة لإعادة إدخال تفاصيل البطاقة.

Key Benefits

الميزة	التأثير
الشراء بنقرة واحدة	تخطي نموذج الدفع للعملاء العائدين
تحويل أعلى	تقليل الاحتكاك في لحظة اتخاذ القرار
المعالجة الفورية	تُعالج الرسوم فورًا باستخدام `confirm: true`
تجربة داخل التطبيق	يبقى العملاء داخل تطبيقك طوال العملية

How It Works

Prerequisites

قبل تنفيذ الترقيات والتخفيضات، تأكد من توفر ما يلي:

العملاء الذين لديهم طرق دفع محفوظة (تُحفظ تلقائيًا بعد أول عملية شراء)
منتجات Upsell المُعدّة في لوحة التحكم (دفعات لمرة واحدة أو اشتراكات أو إضافات)
نقطة نهاية webhook مُعدّة للتعامل مع أحداث payment.succeeded و payment.failed و subscription.plan_changed

الحصول على طرق دفع العملاء

قبل تقديم Upsell، استرجع طرق الدفع المحفوظة للعميل:

TypeScript
Python
Go

import DodoPayments from 'dodopayments';

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

async function getPaymentMethods(customerId: string) {
  const paymentMethods = await client.customers.retrievePaymentMethods(customerId);
  
  // Returns { items: [...] } — the list of saved payment methods.
  // Each item has: payment_method_id, payment_method, payment_method_type, last_used_at,
  // recurring_enabled, and card (last4_digits, card_network, card_type, expiry_month, expiry_year)
  return paymentMethods;
}

// Example usage
const methods = await getPaymentMethods('cus_123');
console.log('Available payment methods:', methods);

// Use the first available method for upsell
const primaryMethod = methods.items[0]?.payment_method_id;

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="live_mode",
)

def get_payment_methods(customer_id: str):
    payment_methods = client.customers.retrieve_payment_methods(customer_id)
    
    # Returns an object with an `items` list of saved payment methods.
    # Each item has: payment_method_id, payment_method, payment_method_type, last_used_at,
    # recurring_enabled, and card (last4_digits, card_network, card_type, expiry_month, expiry_year)
    return payment_methods

# Example usage
methods = get_payment_methods("cus_123")
print("Available payment methods:", methods)

# Use the first available method for upsell
primary_method = methods.items[0].payment_method_id if methods.items else None

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/dodopayments/dodopayments-go"
    "github.com/dodopayments/dodopayments-go/option"
)

func getPaymentMethods(customerID string) ([]dodopayments.CustomerGetPaymentMethodsResponseItem, error) {
    client := dodopayments.NewClient(
        option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
    )
    
    resp, err := client.Customers.GetPaymentMethods(
        context.TODO(),
        customerID,
    )
    if err != nil {
        return nil, err
    }
    
    return resp.Items, nil
}

func main() {
    methods, err := getPaymentMethods("cus_123")
    if err != nil {
        panic(err)
    }
    
    fmt.Println("Available payment methods:", methods)
    
    // Use the first available method for upsell
    if len(methods) > 0 {
        primaryMethod := methods[0].PaymentMethodID
        fmt.Println("Primary method:", primaryMethod)
    }
}

تُحفظ طرق الدفع تلقائيًا عند إكمال العملاء لعملية الدفع. لا تحتاج إلى حفظها بشكل صريح.

Upsell بنقرة واحدة بعد الشراء

قدّم منتجات إضافية فورًا بعد نجاح عملية الشراء. يمكن للعميل القبول بنقرة واحدة لأن طريقة الدفع الخاصة به محفوظة بالفعل.

التنفيذ

TypeScript
Python
Go

import DodoPayments from 'dodopayments';

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

async function createOneClickUpsell(
  customerId: string,
  paymentMethodId: string,
  upsellProductId: string
) {
  // Create checkout session with saved payment method
  // confirm: true processes the payment immediately
  const session = await client.checkoutSessions.create({
    product_cart: [
      {
        product_id: upsellProductId,
        quantity: 1
      }
    ],
    customer: {
      customer_id: customerId
    },
    payment_method_id: paymentMethodId,
    confirm: true,  // Required when using payment_method_id
    return_url: 'https://yourapp.com/upsell-success',
    feature_flags: {
      redirect_immediately: true  // Skip success page
    },
    metadata: {
      upsell_source: 'post_purchase',
      original_order_id: 'order_123'
    }
  });

  return session;
}

// Example: Offer premium add-on after initial purchase
async function handlePostPurchaseUpsell(customerId: string) {
  // Get customer's payment methods
  const methods = await client.customers.retrievePaymentMethods(customerId);
  
  if (methods.items.length === 0) {
    console.log('No saved payment methods available');
    return null;
  }

  // Create the upsell with one-click checkout
  const upsell = await createOneClickUpsell(
    customerId,
    methods.items[0].payment_method_id,
    'pdt_premium_addon'
  );

  console.log('Upsell processed:', upsell.session_id);
  return upsell;
}

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="live_mode",
)

def create_one_click_upsell(
    customer_id: str,
    payment_method_id: str,
    upsell_product_id: str
):
    """Create a one-click upsell using saved payment method."""
    
    # Create checkout session with saved payment method
    # confirm=True processes the payment immediately
    session = client.checkout_sessions.create(
        product_cart=[
            {
                "product_id": upsell_product_id,
                "quantity": 1
            }
        ],
        customer={
            "customer_id": customer_id
        },
        payment_method_id=payment_method_id,
        confirm=True,  # Required when using payment_method_id
        return_url="https://yourapp.com/upsell-success",
        feature_flags={
            "redirect_immediately": True  # Skip success page
        },
        metadata={
            "upsell_source": "post_purchase",
            "original_order_id": "order_123"
        }
    )
    
    return session

def handle_post_purchase_upsell(customer_id: str):
    """Offer premium add-on after initial purchase."""
    
    # Get customer's payment methods
    methods = client.customers.retrieve_payment_methods(customer_id)
    
    if not methods.items:
        print("No saved payment methods available")
        return None
    
    # Create the upsell with one-click checkout
    upsell = create_one_click_upsell(
        customer_id=customer_id,
        payment_method_id=methods.items[0].payment_method_id,
        upsell_product_id="pdt_premium_addon"
    )
    
    print(f"Upsell processed: {upsell.session_id}")
    return upsell

package main

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

func createOneClickUpsell(
    customerID string,
    paymentMethodID string,
    upsellProductID string,
) (*dodopayments.CheckoutSessionResponse, error) {
    client := dodopayments.NewClient(
        option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
    )
    
    // Create checkout session with saved payment method
    // Confirm: true processes the payment immediately
    session, err := client.CheckoutSessions.New(context.TODO(), dodopayments.CheckoutSessionNewParams{
        CheckoutSessionRequest: dodopayments.CheckoutSessionRequestParam{
            ProductCart: dodopayments.F([]dodopayments.ProductItemReqParam{
                {
                    ProductID: dodopayments.F(upsellProductID),
                    Quantity:  dodopayments.F(int64(1)),
                },
            }),
            Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](
                dodopayments.AttachExistingCustomerParam{
                    CustomerID: dodopayments.F(customerID),
                },
            ),
            PaymentMethodID: dodopayments.F(paymentMethodID),
            Confirm:         dodopayments.F(true), // Required when using payment_method_id
            ReturnURL:       dodopayments.F("https://yourapp.com/upsell-success"),
            FeatureFlags: dodopayments.F(dodopayments.CheckoutSessionFlagsParam{
                RedirectImmediately: dodopayments.F(true), // Skip success page
            }),
            Metadata: dodopayments.F(map[string]string{
                "upsell_source":     "post_purchase",
                "original_order_id": "order_123",
            }),
        },
    })
    
    return session, err
}

func handlePostPurchaseUpsell(customerID string) (*dodopayments.CheckoutSessionResponse, error) {
    client := dodopayments.NewClient(
        option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
    )
    
    // Get customer's payment methods
    resp, err := client.Customers.GetPaymentMethods(context.TODO(), customerID)
    if err != nil {
        return nil, err
    }
    
    if len(resp.Items) == 0 {
        fmt.Println("No saved payment methods available")
        return nil, nil
    }
    
    // Create the upsell with one-click checkout
    upsell, err := createOneClickUpsell(
        customerID,
        resp.Items[0].PaymentMethodID,
        "pdt_premium_addon",
    )
    if err != nil {
        return nil, err
    }
    
    fmt.Printf("Upsell processed: %s\n", upsell.SessionID)
    return upsell, nil
}

عند تمرير payment_method_id إلى جلسة دفع، يجب أيضًا تعيين confirm: true وتوفير customer_id موجود. يجب أن تكون طريقة الدفع مملوكة لذلك العميل. لا يحتوي POST /payments على حقل confirm.

ترقية الاشتراكات

انقل العملاء إلى خطط اشتراك ذات مستوى أعلى مع معالجة تلقائية للتوزيع النسبي.

المعاينة قبل التنفيذ

عاين دائمًا تغييرات الخطة لعرض المبلغ الذي سيتم تحصيله من العملاء بدقة:

TypeScript
Python
Go

async function previewUpgrade(
  subscriptionId: string,
  newProductId: string
) {
  const preview = await client.subscriptions.previewChangePlan(subscriptionId, {
    product_id: newProductId,
    quantity: 1,
    proration_billing_mode: 'difference_immediately'
  });

  return {
    immediateCharge: preview.immediate_charge?.summary,
    newPlan: preview.new_plan,
    effectiveAt: preview.immediate_charge?.effective_at
  };
}

// Show customer the charge before confirming
const preview = await previewUpgrade('sub_123', 'pdt_pro_plan');
console.log(`Upgrade will charge: ${preview.immediateCharge}`);

def preview_upgrade(subscription_id: str, new_product_id: str):
    preview = client.subscriptions.preview_change_plan(
        subscription_id=subscription_id,
        product_id=new_product_id,
        quantity=1,
        proration_billing_mode="difference_immediately"
    )
    
    return {
        "immediate_charge": preview.immediate_charge.summary if preview.immediate_charge else None,
        "new_plan": preview.new_plan,
        "effective_at": preview.immediate_charge.effective_at if preview.immediate_charge else None,
    }

# Show customer the charge before confirming
preview = preview_upgrade("sub_123", "pdt_pro_plan")
print(f"Upgrade will charge: {preview['immediate_charge']}")

func previewUpgrade(subscriptionID string, newProductID string) (map[string]interface{}, error) {
    client := dodopayments.NewClient(
        option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
    )
    
    preview, err := client.Subscriptions.PreviewChangePlan(
        context.TODO(),
        subscriptionID,
        dodopayments.SubscriptionPreviewChangePlanParams{
            UpdateSubscriptionPlanReq: dodopayments.UpdateSubscriptionPlanReqParam{
                ProductID:            dodopayments.F(newProductID),
                Quantity:             dodopayments.F(int64(1)),
                ProrationBillingMode: dodopayments.F(dodopayments.UpdateSubscriptionPlanReqProrationBillingModeDifferenceImmediately),
            },
        },
    )
    if err != nil {
        return nil, err
    }
    
    return map[string]interface{}{
        "immediate_charge": preview.ImmediateCharge.Summary,
        "new_plan":         preview.NewPlan,
        "effective_at":     preview.ImmediateCharge.EffectiveAt,
    }, nil
}

تنفيذ الترقية

TypeScript
Python
Go

async function upgradeSubscription(
  subscriptionId: string,
  newProductId: string,
  prorationMode: 'prorated_immediately' | 'difference_immediately' | 'full_immediately' | 'do_not_bill' = 'difference_immediately'
) {
  // change-plan returns 200 with a ChangePlanResponse body (payment_id, payment_link,
  // client_secret, expires_on). All four are null when the change settles off-session.
  await client.subscriptions.changePlan(subscriptionId, {
    product_id: newProductId,
    quantity: 1,
    proration_billing_mode: prorationMode
  });

  // Re-read the subscription to observe the applied state.
  return await client.subscriptions.retrieve(subscriptionId);
}

// Upgrade from Basic ($30) to Pro ($80)
// With difference_immediately: charges $50 instantly
const upgrade = await upgradeSubscription('sub_123', 'pdt_pro_plan');
console.log('Upgrade status:', upgrade.status);

def upgrade_subscription(
    subscription_id: str,
    new_product_id: str,
    proration_mode: str = "difference_immediately"
):
    # change_plan returns 200 with a ChangePlanResponse body (payment_id, payment_link,
    # client_secret, expires_on). All four are None when the change settles off-session.
    client.subscriptions.change_plan(
        subscription_id=subscription_id,
        product_id=new_product_id,
        quantity=1,
        proration_billing_mode=proration_mode
    )

    # Re-read the subscription to observe the applied state.
    return client.subscriptions.retrieve(subscription_id)

# Upgrade from Basic ($30) to Pro ($80)
# With difference_immediately: charges $50 instantly
upgrade = upgrade_subscription("sub_123", "pdt_pro_plan")
print(f"Upgrade status: {upgrade.status}")

func upgradeSubscription(
    subscriptionID string,
    newProductID string,
    prorationMode dodopayments.UpdateSubscriptionPlanReqProrationBillingMode,
) error {
    client := dodopayments.NewClient(
        option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
    )
    
    // ChangePlan returns a SubscriptionChangePlanResponse alongside the error.
    _, err := client.Subscriptions.ChangePlan(
        context.TODO(),
        subscriptionID,
        dodopayments.SubscriptionChangePlanParams{
            UpdateSubscriptionPlanReq: dodopayments.UpdateSubscriptionPlanReqParam{
                ProductID:            dodopayments.F(newProductID),
                Quantity:             dodopayments.F(int64(1)),
                ProrationBillingMode: dodopayments.F(prorationMode),
            },
        },
    )
    
    return err
}

func main() {
    // Upgrade from Basic ($30) to Pro ($80)
    // With DifferenceImmediately: charges $50 instantly
    err := upgradeSubscription(
        "sub_123",
        "pdt_pro_plan",
        dodopayments.UpdateSubscriptionPlanReqProrationBillingModeDifferenceImmediately,
    )
    if err != nil {
        panic(err)
    }
    fmt.Println("Upgrade succeeded")
}

أوضاع التوزيع النسبي

اختر طريقة تحصيل الرسوم من العملاء عند الترقية:

`difference_immediately`

يُحصّل فرق السعر فورًا ($30→$80 = $50). الأنسب للترقيات البسيطة.

`prorated_immediately`

يضيف رصيدًا مقابل الوقت غير المستخدم في الخطة القديمة، ثم يُحصّل دورة كاملة من الخطة الجديدة. الأنسب لمنح رصيد مقابل الوقت غير المستخدم.

`full_immediately`

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

`do_not_bill`

يطبّق تغيير الخطة دون تحصيل فوري؛ وتُحتسب رسوم الخطة الجديدة عند التجديد التالي مع الحفاظ على تاريخ الفوترة الأصلي. الأنسب للترقيات المجانية وترحيل العملاء مجانًا.

استخدم difference_immediately لتدفقات الترقية المباشرة — إذ تكون الرسوم هي فرق السعر فقط. استخدم prorated_immediately عندما تريد منح العميل رصيدًا مقابل الوقت غير المستخدم في الخطة الحالية وتحصيل رسوم دورة كاملة من الخطة الجديدة.

Cross-Sells

أضف منتجات مكملة للعملاء الحاليين دون مطالبتهم بإعادة إدخال تفاصيل الدفع.

التنفيذ

TypeScript
Python
Go

async function createCrossSell(
  customerId: string,
  paymentMethodId: string,
  productId: string,
  quantity: number = 1
) {
  // Create a one-time payment using saved payment method
  // Note: POST /payments is deprecated — prefer checkout sessions for new
  // integrations. `payment_method_id` is passed the same way.
  const payment = await client.payments.create({
    product_cart: [
      {
        product_id: productId,
        quantity: quantity
      }
    ],
    customer: { customer_id: customerId },
    billing: { country: 'US', city: 'San Francisco', state: 'CA', street: '1 Market St', zipcode: '94105' },
    payment_method_id: paymentMethodId,
    return_url: 'https://yourapp.com/purchase-complete',
    metadata: {
      purchase_type: 'cross_sell',
      source: 'product_recommendation'
    }
  });

  return payment;
}

// Example: Customer bought a course, offer related ebook
async function offerRelatedProduct(customerId: string, relatedProductId: string) {
  const methods = await client.customers.retrievePaymentMethods(customerId);
  
  if (methods.items.length === 0) {
    // Fall back to standard checkout
    return client.checkoutSessions.create({
      product_cart: [{ product_id: relatedProductId, quantity: 1 }],
      customer: { customer_id: customerId },
      return_url: 'https://yourapp.com/purchase-complete'
    });
  }

  // One-click purchase
  return createCrossSell(customerId, methods.items[0].payment_method_id, relatedProductId);
}

def create_cross_sell(
    customer_id: str,
    payment_method_id: str,
    product_id: str,
    quantity: int = 1
):
    """Create a one-time payment using saved payment method."""

    # Note: POST /payments is deprecated — prefer checkout sessions for new
    # integrations. payment_method_id is passed the same way.
    payment = client.payments.create(
        product_cart=[
            {
                "product_id": product_id,
                "quantity": quantity
            }
        ],
        customer={"customer_id": customer_id},
        billing={"country": "US", "city": "San Francisco", "state": "CA", "street": "1 Market St", "zipcode": "94105"},
        payment_method_id=payment_method_id,
        return_url="https://yourapp.com/purchase-complete",
        metadata={
            "purchase_type": "cross_sell",
            "source": "product_recommendation"
        }
    )
    
    return payment

def offer_related_product(customer_id: str, related_product_id: str):
    """Offer related product with one-click purchase if possible."""
    
    methods = client.customers.retrieve_payment_methods(customer_id)
    
    if not methods.items:
        # Fall back to standard checkout
        return client.checkout_sessions.create(
            product_cart=[{"product_id": related_product_id, "quantity": 1}],
            customer={"customer_id": customer_id},
            return_url="https://yourapp.com/purchase-complete"
        )
    
    # One-click purchase
    return create_cross_sell(customer_id, methods.items[0].payment_method_id, related_product_id)

func createCrossSell(
    customerID string,
    paymentMethodID string,
    productID string,
    quantity int64,
) (*dodopayments.PaymentNewResponse, error) {
    client := dodopayments.NewClient(
        option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
    )
    
    // Note: POST /payments is deprecated — prefer checkout sessions for new
    // integrations. PaymentMethodID is passed the same way.
    payment, err := client.Payments.New(context.TODO(), dodopayments.PaymentNewParams{
        ProductCart: dodopayments.F([]dodopayments.OneTimeProductCartItemParam{
            {
                ProductID: dodopayments.F(productID),
                Quantity:  dodopayments.F(quantity),
            },
        }),
        Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](
            dodopayments.AttachExistingCustomerParam{CustomerID: dodopayments.F(customerID)},
        ),
        Billing: dodopayments.F(dodopayments.BillingAddressParam{
            Country: dodopayments.F(dodopayments.CountryCodeUs),
            City:    dodopayments.F("San Francisco"),
            State:   dodopayments.F("CA"),
            Street:  dodopayments.F("1 Market St"),
            Zipcode: dodopayments.F("94105"),
        }),
        PaymentMethodID: dodopayments.F(paymentMethodID),
        ReturnURL:       dodopayments.F("https://yourapp.com/purchase-complete"),
        Metadata: dodopayments.F(map[string]string{
            "purchase_type": "cross_sell",
            "source":        "product_recommendation",
        }),
    })
    
    return payment, err
}

func offerRelatedProduct(customerID string, relatedProductID string) (interface{}, error) {
    client := dodopayments.NewClient(
        option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
    )
    
    resp, err := client.Customers.GetPaymentMethods(context.TODO(), customerID)
    if err != nil {
        return nil, err
    }
    
    if len(resp.Items) == 0 {
        // Fall back to standard checkout
        return client.CheckoutSessions.New(context.TODO(), dodopayments.CheckoutSessionNewParams{
            CheckoutSessionRequest: dodopayments.CheckoutSessionRequestParam{
                ProductCart: dodopayments.F([]dodopayments.ProductItemReqParam{
                    {ProductID: dodopayments.F(relatedProductID), Quantity: dodopayments.F(int64(1))},
                }),
                Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](
                    dodopayments.AttachExistingCustomerParam{CustomerID: dodopayments.F(customerID)},
                ),
                ReturnURL: dodopayments.F("https://yourapp.com/purchase-complete"),
            },
        })
    }
    
    // One-click purchase
    return createCrossSell(customerID, resp.Items[0].PaymentMethodID, relatedProductID, 1)
}

تخفيضات الاشتراكات

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

كيفية عمل التخفيضات

يطلب العميل التخفيض (Pro → Basic)
يحسب النظام القيمة المتبقية في الخطة الحالية
تُضاف القيمة كرصيد إلى الاشتراك للتجديدات المستقبلية
ينتقل العميل إلى الخطة الجديدة فورًا

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

TypeScript
Python
Go

async function downgradeSubscription(
  subscriptionId: string,
  newProductId: string
) {
  // Preview the downgrade first
  const preview = await client.subscriptions.previewChangePlan(subscriptionId, {
    product_id: newProductId,
    quantity: 1,
    proration_billing_mode: 'difference_immediately'
  });

  // customer_credits is positive when credit is added to the balance, negative when credit is used
  console.log('Customer credit change:', preview.immediate_charge.summary.customer_credits);

  // Execute the downgrade. change-plan returns 200 with a ChangePlanResponse body.
  await client.subscriptions.changePlan(subscriptionId, {
    product_id: newProductId,
    quantity: 1,
    proration_billing_mode: 'difference_immediately'
  });

  // Credits are automatically applied to future renewals
  return await client.subscriptions.retrieve(subscriptionId);
}

// Downgrade from Pro ($80) to Basic ($30)
// $50 credit added to subscription, auto-applied on next renewal
const downgrade = await downgradeSubscription('sub_123', 'pdt_basic_plan');

def downgrade_subscription(subscription_id: str, new_product_id: str):
    # Preview the downgrade first
    preview = client.subscriptions.preview_change_plan(
        subscription_id=subscription_id,
        product_id=new_product_id,
        quantity=1,
        proration_billing_mode="difference_immediately"
    )
    
    # customer_credits is positive when credit is added to the balance, negative when credit is used
    print(f"Customer credit change: {preview.immediate_charge.summary.customer_credits}")
    
    # Execute the downgrade. change_plan returns 200 with a ChangePlanResponse body.
    client.subscriptions.change_plan(
        subscription_id=subscription_id,
        product_id=new_product_id,
        quantity=1,
        proration_billing_mode="difference_immediately"
    )

    # Credits are automatically applied to future renewals
    return client.subscriptions.retrieve(subscription_id)

# Downgrade from Pro ($80) to Basic ($30)
# $50 credit added to subscription, auto-applied on next renewal
downgrade = downgrade_subscription("sub_123", "pdt_basic_plan")

func downgradeSubscription(subscriptionID string, newProductID string) error {
    client := dodopayments.NewClient(
        option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
    )
    
    // Preview the downgrade first
    preview, err := client.Subscriptions.PreviewChangePlan(
        context.TODO(),
        subscriptionID,
        dodopayments.SubscriptionPreviewChangePlanParams{
            UpdateSubscriptionPlanReq: dodopayments.UpdateSubscriptionPlanReqParam{
                ProductID:            dodopayments.F(newProductID),
                Quantity:             dodopayments.F(int64(1)),
                ProrationBillingMode: dodopayments.F(dodopayments.UpdateSubscriptionPlanReqProrationBillingModeDifferenceImmediately),
            },
        },
    )
    if err != nil {
        return err
    }
    
    fmt.Printf("Customer credits to be applied: %v\n", preview.ImmediateCharge.Summary.CustomerCredits)
    
    // Execute the downgrade (returns a SubscriptionChangePlanResponse alongside the error)
    _, err = client.Subscriptions.ChangePlan(
        context.TODO(),
        subscriptionID,
        dodopayments.SubscriptionChangePlanParams{
            UpdateSubscriptionPlanReq: dodopayments.UpdateSubscriptionPlanReqParam{
                ProductID:            dodopayments.F(newProductID),
                Quantity:             dodopayments.F(int64(1)),
                ProrationBillingMode: dodopayments.F(dodopayments.UpdateSubscriptionPlanReqProrationBillingModeDifferenceImmediately),
            },
        },
    )
    return err
}

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

مثال كامل: سير عمل العرض الإضافي بعد الشراء

إليك تنفيذًا كاملًا يوضح كيفية تقديم عرض إضافي بعد نجاح عملية شراء:

TypeScript
Python

import DodoPayments from 'dodopayments';
import express from 'express';

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

const app = express();

// Store for tracking upsell eligibility (use your database in production)
const eligibleUpsells = new Map<string, { customerId: string; productId: string }>();

// Webhook handler for initial purchase success
app.post('/webhooks/dodo', express.raw({ type: 'application/json' }), async (req, res) => {
  const event = JSON.parse(req.body.toString());
  
  switch (event.type) {
    case 'payment.succeeded':
      // Check if customer is eligible for upsell
      const customerId = event.data.customer.customer_id;
      const productId = event.data.product_cart?.[0]?.product_id;
      
      // Define upsell rules (e.g., bought Basic, offer Pro)
      const upsellProduct = getUpsellProduct(productId);
      
      if (upsellProduct) {
        eligibleUpsells.set(customerId, {
          customerId,
          productId: upsellProduct
        });
      }
      break;
      
    case 'payment.failed':
      console.log('Payment failed:', event.data.payment_id);
      // Handle failed upsell payment
      break;
  }
  
  res.json({ received: true });
});

// API endpoint to check upsell eligibility
app.get('/api/upsell/:customerId', async (req, res) => {
  const { customerId } = req.params;
  const upsell = eligibleUpsells.get(customerId);
  
  if (!upsell) {
    return res.json({ eligible: false });
  }
  
  // Get payment methods
  const methods = await client.customers.retrievePaymentMethods(customerId);
  
  if (methods.items.length === 0) {
    return res.json({ eligible: false, reason: 'no_payment_method' });
  }
  
  // Get product details for display
  const product = await client.products.retrieve(upsell.productId);
  
  res.json({
    eligible: true,
    product: {
      id: product.product_id,
      name: product.name,
      price: product.price,
      currency: product.price.currency
    },
    paymentMethodId: methods.items[0].payment_method_id
  });
});

// API endpoint to accept upsell
app.post('/api/upsell/:customerId/accept', async (req, res) => {
  const { customerId } = req.params;
  const upsell = eligibleUpsells.get(customerId);
  
  if (!upsell) {
    return res.status(400).json({ error: 'No upsell available' });
  }
  
  try {
    const methods = await client.customers.retrievePaymentMethods(customerId);
    
    // Create one-click purchase
    const session = await client.checkoutSessions.create({
      product_cart: [{ product_id: upsell.productId, quantity: 1 }],
      customer: { customer_id: customerId },
      payment_method_id: methods.items[0].payment_method_id,
      confirm: true,
      return_url: `${process.env.APP_URL}/upsell-success`,
      feature_flags: { redirect_immediately: true },
      metadata: { upsell: 'true', source: 'post_purchase' }
    });
    
    // Clear the upsell offer
    eligibleUpsells.delete(customerId);
    
    res.json({ success: true, sessionId: session.session_id });
  } catch (error) {
    console.error('Upsell failed:', error);
    res.status(500).json({ error: 'Upsell processing failed' });
  }
});

// Helper function to determine upsell product
function getUpsellProduct(purchasedProductId: string): string | null {
  const upsellMap: Record<string, string> = {
    'pdt_basic_plan': 'pdt_pro_plan',
    'pdt_starter_course': 'pdt_complete_bundle',
    'pdt_single_license': 'pdt_team_license'
  };
  
  return upsellMap[purchasedProductId] || null;
}

app.listen(3000);

import os
from flask import Flask, request, jsonify
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="live_mode",
)

app = Flask(__name__)

# Store for tracking upsell eligibility (use your database in production)
eligible_upsells = {}

@app.route('/webhooks/dodo', methods=['POST'])
def webhook_handler():
    event = request.json
    
    if event['type'] == 'payment.succeeded':
        # Check if customer is eligible for upsell
        customer_id = event['data']['customer']['customer_id']
        product_id = (event['data'].get('product_cart') or [{}])[0].get('product_id')
        
        # Define upsell rules
        upsell_product = get_upsell_product(product_id)
        
        if upsell_product:
            eligible_upsells[customer_id] = {
                'customer_id': customer_id,
                'product_id': upsell_product
            }
    
    elif event['type'] == 'payment.failed':
        print(f"Payment failed: {event['data']['payment_id']}")
    
    return jsonify({'received': True})

@app.route('/api/upsell/<customer_id>', methods=['GET'])
def check_upsell(customer_id):
    upsell = eligible_upsells.get(customer_id)
    
    if not upsell:
        return jsonify({'eligible': False})
    
    # Get payment methods
    methods = client.customers.retrieve_payment_methods(customer_id)
    
    if not methods.items:
        return jsonify({'eligible': False, 'reason': 'no_payment_method'})
    
    # Get product details for display
    product = client.products.retrieve(upsell['product_id'])
    
    return jsonify({
        'eligible': True,
        'product': {
            'id': product.product_id,
            'name': product.name,
            'price': product.price,
            'currency': product.price.currency
        },
        'payment_method_id': methods.items[0].payment_method_id
    })

@app.route('/api/upsell/<customer_id>/accept', methods=['POST'])
def accept_upsell(customer_id):
    upsell = eligible_upsells.get(customer_id)
    
    if not upsell:
        return jsonify({'error': 'No upsell available'}), 400
    
    try:
        methods = client.customers.retrieve_payment_methods(customer_id)
        
        # Create one-click purchase
        session = client.checkout_sessions.create(
            product_cart=[{'product_id': upsell['product_id'], 'quantity': 1}],
            customer={'customer_id': customer_id},
            payment_method_id=methods.items[0].payment_method_id,
            confirm=True,
            return_url=f"{os.environ['APP_URL']}/upsell-success",
            feature_flags={'redirect_immediately': True},
            metadata={'upsell': 'true', 'source': 'post_purchase'}
        )
        
        # Clear the upsell offer
        del eligible_upsells[customer_id]
        
        return jsonify({'success': True, 'session_id': session.session_id})
    
    except Exception as error:
        print(f"Upsell failed: {error}")
        return jsonify({'error': 'Upsell processing failed'}), 500

def get_upsell_product(purchased_product_id: str) -> str:
    """Determine upsell product based on purchased product."""
    upsell_map = {
        'pdt_basic_plan': 'pdt_pro_plan',
        'pdt_starter_course': 'pdt_complete_bundle',
        'pdt_single_license': 'pdt_team_license'
    }
    return upsell_map.get(purchased_product_id)

if __name__ == '__main__':
    app.run(port=3000)

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

اختر التوقيت المناسب: قدّم العروض الإضافية فور نجاح عملية الشراء، عندما يكون العملاء في حالة استعداد للشراء. وتشمل الأوقات الفعّالة الأخرى: بعد تحقيق مراحل مهمة في استخدام الميزات، وعند الاقتراب من حدود الخطة، وعند إكمال الإعداد الأولي.
تحقّق من وسائل الدفع: قبل محاولة إجراء عملية خصم بنقرة واحدة، تحقّق من توافق وسيلة الدفع مع عملة المنتج، ومن عدم انتهاء صلاحيتها، ومن انتمائها إلى العميل.
تعامل مع حالات الفشل بسلاسة: عند فشل عمليات الخصم بنقرة واحدة، انتقل إلى تدفق الدفع القياسي، وأخطر العميل برسالة واضحة، واعرض عليه تحديث وسيلة الدفع.
وضّح القيمة بجلاء: اعرض ما سيحصل عليه العملاء مقارنة بخطتهم الحالية، وسلّط الضوء على فرق السعر (وليس السعر الإجمالي)، واستخدم الدليل الاجتماعي.
احترم اختيار العميل: وفّر دائمًا طريقة سهلة للرفض، ولا تعرض العرض الإضافي نفسه بشكل متكرر بعد رفضه، وتتبّع العروض الإضافية التي تؤدي إلى التحويل لتحسين العروض.

Webhooks التي يجب مراقبتها

تتبّع أحداث Webhooks التالية لتدفقات العروض الإضافية وتخفيضات الخطة:

الحدث	المشغّل	الإجراء
`payment.succeeded`	اكتمال دفع العرض الإضافي/البيع المتقاطع	تسليم المنتج، وتحديث الوصول
`payment.failed`	فشل الخصم بنقرة واحدة	عرض الخطأ، وتوفير خيار إعادة المحاولة أو التدفق البديل
`subscription.plan_changed`	اكتمال الترقية/تخفيض الخطة	تحديث الميزات، وإرسال التأكيد
`subscription.active`	إعادة تفعيل الاشتراك بعد تغيير الخطة	منح الوصول إلى المستوى الجديد

Webhook Integration Guide

تعرّف على كيفية إعداد نقاط نهاية Webhooks والتحقق منها.

موارد ذات صلة

Subscription Upgrade Guide

دليل تفصيلي حول تغييرات الخطط، وأوضاع التوزيع النسبي، والتعامل مع حالات الفشل.

Checkout Sessions

مرجع كامل لإنشاء جلسات الدفع مع جميع الخيارات.

Customer Payment Methods API

مرجع API لسرد وسائل دفع العملاء.

Add-ons

عزّز الاشتراكات باستخدام إضافات مرنة لتحقيق إيرادات إضافية.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Post-Purchase Upsells

Subscription Upgrades

Cross-Sells

Overview

Key Benefits

How It Works

Prerequisites

الحصول على طرق دفع العملاء

Upsell بنقرة واحدة بعد الشراء

التنفيذ

ترقية الاشتراكات

المعاينة قبل التنفيذ

تنفيذ الترقية

أوضاع التوزيع النسبي

`difference_immediately`

`prorated_immediately`

`full_immediately`

`do_not_bill`

Cross-Sells

التنفيذ

تخفيضات الاشتراكات

كيفية عمل التخفيضات

مثال كامل: سير عمل العرض الإضافي بعد الشراء

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

Webhooks التي يجب مراقبتها

Webhook Integration Guide

موارد ذات صلة

Subscription Upgrade Guide

Checkout Sessions

Customer Payment Methods API

Add-ons

Post-Purchase Upsells

Subscription Upgrades

Cross-Sells

​Overview

​Key Benefits

​How It Works

​Prerequisites

​الحصول على طرق دفع العملاء

​Upsell بنقرة واحدة بعد الشراء

​التنفيذ

​ترقية الاشتراكات

​المعاينة قبل التنفيذ

​تنفيذ الترقية

​أوضاع التوزيع النسبي

​difference_immediately

​prorated_immediately

​full_immediately

​do_not_bill

​Cross-Sells

​التنفيذ

​تخفيضات الاشتراكات

​كيفية عمل التخفيضات

​مثال كامل: سير عمل العرض الإضافي بعد الشراء

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

​Webhooks التي يجب مراقبتها

Webhook Integration Guide

​موارد ذات صلة

Subscription Upgrade Guide

Checkout Sessions

Customer Payment Methods API

Add-ons

Overview

Key Benefits

How It Works

Prerequisites

الحصول على طرق دفع العملاء

Upsell بنقرة واحدة بعد الشراء

التنفيذ

ترقية الاشتراكات

المعاينة قبل التنفيذ

تنفيذ الترقية

أوضاع التوزيع النسبي

`difference_immediately`

`prorated_immediately`

`full_immediately`

`do_not_bill`

Cross-Sells

التنفيذ

تخفيضات الاشتراكات

كيفية عمل التخفيضات

مثال كامل: سير عمل العرض الإضافي بعد الشراء

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

Webhooks التي يجب مراقبتها

موارد ذات صلة