Upsells & Downsells

Upsells và downsells giúp bạn đề xuất thêm sản phẩm hoặc thay đổi gói cho khách hàng thông qua các phương thức thanh toán đã lưu của họ. Điều này cho phép mua hàng chỉ bằng một cú nhấp chuột mà không cần thu thập thanh toán, cải thiện đáng kể tỷ lệ chuyển đổi.

Post-Purchase Upsells

Cung cấp các sản phẩm bổ sung ngay sau khi thanh toán với tính năng mua hàng chỉ bằng một cú nhấp chuột.

Subscription Upgrades

Chuyển khách hàng sang các cấp cao hơn với việc tự động tính tỷ lệ và thanh toán ngay lập tức.

Cross-Sells

Thêm các sản phẩm liên quan cho khách hàng hiện có mà không cần nhập lại thông tin thanh toán.

Tổng quan

Upsells và downsells là những chiến lược tối ưu hóa doanh thu mạnh mẽ:

Upsells: Đề xuất sản phẩm giá trị cao hơn hoặc nâng cấp (ví dụ: gói Pro thay vì Basic)
Downsells: Đưa ra lựa chọn giá thấp hơn khi khách hàng từ chối hoặc hạ cấp
Cross-sells: Gợi ý các sản phẩm bổ sung (ví dụ: add-on, mặt hàng liên quan)

Dodo Payments hỗ trợ các luồng này thông qua tham số payment_method_id, cho phép bạn tính phí lên phương thức thanh toán đã lưu của khách hàng mà không yêu cầu họ nhập lại chi tiết thẻ.

Lợi ích chính

Lợi ích	Tác động
Mua hàng một lần nhấp	Bỏ qua biểu mẫu thanh toán đối với khách hàng quay lại
Tỷ lệ chuyển đổi cao hơn	Giảm trở ngại tại thời điểm ra quyết định
Xử lý tức thì	Các khoản phí được xử lý ngay lập tức với `confirm: true`
Trải nghiệm trong ứng dụng	Khách hàng ở lại trong ứng dụng của bạn trong suốt quy trình

Cách hoạt động

Yêu cầu trước

Trước khi triển khai upsells và downsells, hãy đảm bảo bạn có:

Khách hàng có phương thức thanh toán đã lưu (tự động được lưu sau lần mua hàng đầu tiên)
Các sản phẩm upsell được cấu hình trong dashboard (thanh toán một lần, gói đăng ký hoặc tiện ích bổ sung)
Endpoint webhook được cấu hình để xử lý các sự kiện payment.succeeded, payment.failed và subscription.plan_changed

Lấy phương thức thanh toán của khách hàng

Trước khi cung cấp upsell, hãy lấy các phương thức thanh toán đã lưu của khách hàng:

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

Phương thức thanh toán được tự động lưu khi khách hàng hoàn tất checkout. Bạn không cần lưu chúng một cách rõ ràng.

Upsell một lần nhấp sau khi mua hàng

Cung cấp các sản phẩm bổ sung ngay sau khi giao dịch mua hàng thành công. Khách hàng có thể chấp nhận chỉ bằng một lần nhấp vì phương thức thanh toán của họ đã được lưu.

Triển khai

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
}

Khi truyền payment_method_id vào một checkout session, bạn cũng phải đặt confirm: true và cung cấp một customer_id hiện có. Phương thức thanh toán phải thuộc về khách hàng đó. POST /payments không có trường confirm.

Nâng cấp gói đăng ký

Chuyển khách hàng sang các gói đăng ký cấp cao hơn với việc xử lý phân bổ theo tỷ lệ tự động.

Xem trước trước khi xác nhận

Luôn xem trước các thay đổi gói để hiển thị chính xác khoản phí khách hàng sẽ phải trả:

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
}

Thực hiện nâng cấp

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

Chế độ phân bổ theo tỷ lệ

Chọn cách tính phí cho khách hàng khi nâng cấp:

`difference_immediately`

Tính phí phần chênh lệch ngay lập tức ($30→$80 = $50). Phù hợp nhất cho các quy trình nâng cấp đơn giản.

`prorated_immediately`

Cộng phần thời gian chưa sử dụng của gói cũ dưới dạng tín dụng, sau đó tính phí trọn một chu kỳ của gói mới. Phù hợp nhất khi cần hoàn lại giá trị thời gian chưa sử dụng.

`full_immediately`

Tính toàn bộ giá gói mới và bỏ qua thời gian còn lại. Phù hợp nhất khi đặt lại chu kỳ thanh toán.

`do_not_bill`

Áp dụng thay đổi gói mà không tính phí ngay; gói mới sẽ được tính phí vào lần gia hạn tiếp theo và ngày thanh toán ban đầu được giữ nguyên. Phù hợp nhất cho các lần nâng cấp ưu đãi và chuyển đổi miễn phí.

Sử dụng difference_immediately cho các quy trình nâng cấp đơn giản — khoản phí là phần chênh lệch giá trực tiếp. Sử dụng prorated_immediately khi bạn muốn cộng tín dụng cho khách hàng đối với thời gian chưa sử dụng của gói hiện tại và tính phí trọn một chu kỳ của gói mới.

Bán chéo

Thêm các sản phẩm bổ trợ cho khách hàng hiện tại mà không yêu cầu họ nhập lại thông tin thanh toán.

Triển khai

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

Hạ cấp gói đăng ký

Khi khách hàng muốn chuyển sang gói cấp thấp hơn, hãy xử lý quá trình chuyển đổi một cách linh hoạt với tín dụng tự động.

Cách thức hạ cấp

Khách hàng yêu cầu hạ cấp (Pro → Basic)
Hệ thống tính toán giá trị còn lại của gói hiện tại
Tín dụng được cộng vào gói đăng ký để sử dụng cho các lần gia hạn trong tương lai
Khách hàng chuyển sang gói mới ngay lập tức

immediate_charge.summary.customer_credits của bản xem trước nằm trong loại tiền tệ của ví tín dụng của khách hàng, được xác định bởi customer_credits_currency. Giá trị này có thể khác với currency trong phần tóm tắt, chẳng hạn khi khách hàng thanh toán bằng INR cho gói đăng ký tính bằng 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
}

Các khoản tín dụng từ việc hạ cấp sử dụng difference_immediately được áp dụng trong phạm vi gói đăng ký và tự động dùng cho các lần gia hạn tiếp theo. Chúng khác với các quyền lợi của Credit-Based Billing.

Ví dụ hoàn chỉnh: Quy trình bán thêm sau khi mua

Dưới đây là một triển khai hoàn chỉnh cho thấy cách cung cấp ưu đãi bán thêm sau khi giao dịch mua thành công:

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)

Thực tiễn tốt nhất

Chọn thời điểm phù hợp: Cung cấp ưu đãi bán thêm ngay sau khi giao dịch mua thành công, khi khách hàng đang có tâm lý mua sắm. Các thời điểm hiệu quả khác: sau khi đạt các cột mốc sử dụng tính năng, khi sắp đạt giới hạn gói, trong quá trình hoàn tất onboarding.
Xác thực phương thức thanh toán: Trước khi thực hiện khoản thu bằng một lần nhấp, hãy xác minh rằng phương thức thanh toán tương thích với loại tiền tệ của sản phẩm, chưa hết hạn và thuộc về khách hàng.
Xử lý lỗi một cách phù hợp: Khi khoản thu bằng một lần nhấp thất bại, hãy chuyển về quy trình checkout tiêu chuẩn, thông báo rõ ràng cho khách hàng và đề nghị cập nhật phương thức thanh toán.
Nêu rõ giá trị: Cho khách hàng thấy họ nhận được gì so với gói hiện tại, làm nổi bật phần chênh lệch giá (không phải tổng giá) và sử dụng bằng chứng xã hội.
Tôn trọng lựa chọn của khách hàng: Luôn cung cấp cách dễ dàng để từ chối, không hiển thị lại cùng một ưu đãi bán thêm nhiều lần sau khi khách hàng từ chối và theo dõi những ưu đãi bán thêm nào chuyển đổi để tối ưu hóa các ưu đãi.

Webhook cần theo dõi

Theo dõi các sự kiện webhook này cho quy trình bán thêm và hạ cấp:

Sự kiện	Kích hoạt	Hành động
`payment.succeeded`	Thanh toán bán thêm/bán chéo hoàn tất	Giao sản phẩm, cập nhật quyền truy cập
`payment.failed`	Khoản thu bằng một lần nhấp thất bại	Hiển thị lỗi, đề nghị thử lại hoặc chuyển sang phương án dự phòng
`subscription.plan_changed`	Nâng cấp/hạ cấp hoàn tất	Cập nhật tính năng, gửi xác nhận
`subscription.active`	Gói đăng ký được kích hoạt lại sau khi thay đổi gói	Cấp quyền truy cập vào cấp gói mới

Webhook Integration Guide

Tìm hiểu cách thiết lập và xác minh các endpoint webhook.

Tài nguyên liên quan

Subscription Upgrade Guide

Hướng dẫn chi tiết về việc thay đổi gói, các chế độ phân bổ theo tỷ lệ và cách xử lý lỗi.

Checkout Sessions

Tài liệu tham khảo đầy đủ về cách tạo các phiên checkout với tất cả tùy chọn.

Customer Payment Methods API

Tài liệu tham khảo API để liệt kê các phương thức thanh toán của khách hàng.

Add-ons

Nâng cao các gói đăng ký bằng các tiện ích bổ sung linh hoạt để tăng doanh thu.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Post-Purchase Upsells

Subscription Upgrades

Cross-Sells

Tổng quan

Lợi ích chính

Cách hoạt động

Yêu cầu trước

Lấy phương thức thanh toán của khách hàng

Upsell một lần nhấp sau khi mua hàng

Triển khai

Nâng cấp gói đăng ký

Xem trước trước khi xác nhận

Thực hiện nâng cấp

Chế độ phân bổ theo tỷ lệ

`difference_immediately`

`prorated_immediately`

`full_immediately`

`do_not_bill`

Bán chéo

Triển khai

Hạ cấp gói đăng ký

Cách thức hạ cấp

Ví dụ hoàn chỉnh: Quy trình bán thêm sau khi mua

Thực tiễn tốt nhất

Webhook cần theo dõi

Webhook Integration Guide

Tài nguyên liên quan

Subscription Upgrade Guide

Checkout Sessions

Customer Payment Methods API

Add-ons

Post-Purchase Upsells

Subscription Upgrades

Cross-Sells

​Tổng quan

​Lợi ích chính

​Cách hoạt động

​Yêu cầu trước

​Lấy phương thức thanh toán của khách hàng

​Upsell một lần nhấp sau khi mua hàng

​Triển khai

​Nâng cấp gói đăng ký

​Xem trước trước khi xác nhận

​Thực hiện nâng cấp

​Chế độ phân bổ theo tỷ lệ

​difference_immediately

​prorated_immediately

​full_immediately

​do_not_bill

​Bán chéo

​Triển khai

​Hạ cấp gói đăng ký

​Cách thức hạ cấp

​Ví dụ hoàn chỉnh: Quy trình bán thêm sau khi mua

​Thực tiễn tốt nhất

​Webhook cần theo dõi

Webhook Integration Guide

​Tài nguyên liên quan

Subscription Upgrade Guide

Checkout Sessions

Customer Payment Methods API

Add-ons

Tổng quan

Lợi ích chính

Cách hoạt động

Yêu cầu trước

Lấy phương thức thanh toán của khách hàng

Upsell một lần nhấp sau khi mua hàng

Triển khai

Nâng cấp gói đăng ký

Xem trước trước khi xác nhận

Thực hiện nâng cấp

Chế độ phân bổ theo tỷ lệ

`difference_immediately`

`prorated_immediately`

`full_immediately`

`do_not_bill`

Bán chéo

Triển khai

Hạ cấp gói đăng ký

Cách thức hạ cấp

Ví dụ hoàn chỉnh: Quy trình bán thêm sau khi mua

Thực tiễn tốt nhất

Webhook cần theo dõi

Tài nguyên liên quan