Upsells & Downsells

Upsells dan downsells memungkinkan Anda menawarkan produk tambahan atau perubahan paket kepada pelanggan menggunakan metode pembayaran yang tersimpan. Ini memungkinkan pembelian sekali klik yang melewati pengumpulan pembayaran, secara dramatis meningkatkan rasio konversi.

Post-Purchase Upsells

Tawarkan produk pelengkap segera setelah checkout dengan pembelian sekali klik.

Subscription Upgrades

Pindahkan pelanggan ke tingkat yang lebih tinggi dengan proration otomatis dan penagihan instan.

Cross-Sells

Tambahkan produk terkait untuk pelanggan yang sudah ada tanpa memasukkan kembali detail pembayaran.

Overview

Upsells dan downsells adalah strategi optimalisasi pendapatan yang ampuh:

Upsells: Tawarkan produk bernilai tinggi atau peningkatan (misalnya, paket Pro daripada Basic)
Downsells: Tawarkan alternatif dengan harga lebih rendah saat pelanggan menolak atau menurunkan tingkat
Cross-sells: Sarankan produk pelengkap (misalnya, add-on, barang terkait)

Dodo Payments mendukung alur ini melalui parameter payment_method_id, yang memungkinkan Anda menagih metode pembayaran tersimpan pelanggan tanpa mengharuskan mereka memasukkan detail kartu lagi.

Key Benefits

Manfaat	Dampak
Pembelian sekali klik	Lewati formulir pembayaran untuk pelanggan yang kembali
Konversi lebih tinggi	Kurangi hambatan saat pelanggan mengambil keputusan
Pemrosesan instan	Tagihan diproses segera dengan `confirm: true`
Pengalaman dalam aplikasi	Pelanggan tetap berada di aplikasi Anda selama seluruh alur

How It Works

Prerequisites

Sebelum menerapkan upsells dan downsells, pastikan Anda memiliki:

Pelanggan dengan metode pembayaran tersimpan (disimpan secara otomatis setelah pembelian pertama mereka)
Produk upsell yang dikonfigurasi di dasbor (pembayaran satu kali, langganan, atau add-on)
Endpoint webhook yang dikonfigurasi untuk menangani event payment.succeeded, payment.failed, dan subscription.plan_changed

Mendapatkan Metode Pembayaran Pelanggan

Sebelum menawarkan upsell, ambil metode pembayaran pelanggan yang tersimpan:

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

Metode pembayaran secara otomatis disimpan saat pelanggan menyelesaikan checkout. Anda tidak perlu menyimpannya secara eksplisit.

Upsell Sekali Klik Setelah Pembelian

Tawarkan produk tambahan segera setelah pembelian berhasil. Pelanggan dapat menerimanya dengan satu klik karena metode pembayaran mereka sudah tersimpan.

Implementasi

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
}

Saat Anda meneruskan payment_method_id ke sesi checkout, Anda juga harus menetapkan confirm: true dan menyediakan customer_id yang sudah ada. Metode pembayaran tersebut harus dimiliki oleh pelanggan itu. POST /payments tidak memiliki field confirm.

Upgrade Langganan

Pindahkan pelanggan ke paket langganan tingkat lebih tinggi dengan penanganan proration otomatis.

Pratinjau Sebelum Menerapkan

Selalu pratinjau perubahan paket untuk menunjukkan secara tepat kepada pelanggan jumlah yang akan ditagihkan kepada mereka:

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
}

Jalankan Upgrade

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

Mode Proration

Pilih cara penagihan pelanggan saat melakukan upgrade:

`difference_immediately`

Menagihkan selisih harga secara instan ($30→$80 = $50). Cocok untuk upgrade sederhana.

`prorated_immediately`

Mengreditkan waktu yang tidak terpakai pada paket lama, lalu menagihkan satu siklus penuh paket baru. Cocok untuk memberikan kredit atas waktu yang tidak terpakai.

`full_immediately`

Menagihkan harga penuh paket baru dan mengabaikan waktu yang tersisa. Cocok untuk mengatur ulang siklus penagihan.

`do_not_bill`

Menerapkan perubahan paket tanpa tagihan langsung; paket baru ditagihkan pada perpanjangan berikutnya dan tanggal penagihan asli tetap dipertahankan. Cocok untuk upgrade sebagai bentuk apresiasi dan migrasi gratis.

Gunakan difference_immediately untuk alur upgrade sederhana—tagihannya adalah selisih harga biasa. Gunakan prorated_immediately jika Anda ingin pelanggan menerima kredit untuk waktu yang tidak terpakai pada paket saat ini dan ditagih untuk satu siklus penuh paket baru.

Cross-Sell

Tambahkan produk pelengkap untuk pelanggan yang sudah ada tanpa mengharuskan mereka memasukkan kembali detail pembayaran.

Implementasi

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

Downgrade Langganan

Saat pelanggan ingin berpindah ke paket tingkat lebih rendah, tangani transisi dengan baik menggunakan kredit otomatis.

Cara Kerja Downgrade

Pelanggan meminta downgrade (Pro → Basic)
Sistem menghitung nilai yang tersisa pada paket saat ini
Kredit ditambahkan ke langganan untuk perpanjangan mendatang
Pelanggan segera berpindah ke paket baru

immediate_charge.summary.customer_credits pada pratinjau menggunakan mata uang dompet kredit pelanggan, yang ditentukan oleh customer_credits_currency. Nilainya dapat berbeda dari currency pada ringkasan, misalnya ketika pelanggan membayar dalam INR untuk langganan 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
}

Kredit dari downgrade yang menggunakan difference_immediately berlaku dalam cakupan langganan dan secara otomatis diterapkan pada perpanjangan mendatang. Kredit ini berbeda dari entitlement Penagihan Berbasis Kredit.

Contoh Lengkap: Alur Upsell Pascapembelian

Berikut implementasi lengkap yang menunjukkan cara menawarkan upsell setelah pembelian berhasil:

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)

Praktik Terbaik

Tentukan waktu secara strategis: Tawarkan upsell segera setelah pembelian berhasil, saat pelanggan sedang siap melakukan pembelian. Momen efektif lainnya: setelah pencapaian penggunaan fitur, saat mendekati batas paket, dan selama penyelesaian onboarding.
Validasi metode pembayaran: Sebelum mencoba penagihan sekali klik, pastikan metode pembayaran kompatibel dengan mata uang produk, belum kedaluwarsa, dan milik pelanggan.
Tangani kegagalan dengan baik: Jika penagihan sekali klik gagal, alihkan ke alur checkout standar, beri tahu pelanggan dengan pesan yang jelas, dan tawarkan opsi untuk memperbarui metode pembayaran.
Tunjukkan nilai yang jelas: Tampilkan apa yang akan didapatkan pelanggan dibandingkan dengan paket mereka saat ini, soroti perbedaan harga (bukan harga total), dan gunakan bukti sosial.
Hormati pilihan pelanggan: Selalu sediakan cara mudah untuk menolak, jangan tampilkan upsell yang sama berulang kali setelah ditolak, dan lacak upsell mana yang menghasilkan konversi untuk mengoptimalkan penawaran.

Webhook yang Perlu Dipantau

Lacak event webhook berikut untuk alur upsell dan downgrade:

Event	Pemicu	Tindakan
`payment.succeeded`	Pembayaran upsell/cross-sell selesai	Kirimkan produk, perbarui akses
`payment.failed`	Penagihan sekali klik gagal	Tampilkan error, tawarkan percobaan ulang atau fallback
`subscription.plan_changed`	Upgrade/downgrade selesai	Perbarui fitur, kirim konfirmasi
`subscription.active`	Langganan diaktifkan kembali setelah perubahan paket	Berikan akses ke tingkat baru

Webhook Integration Guide

Pelajari cara menyiapkan dan memverifikasi endpoint webhook.

Sumber Daya Terkait

Subscription Upgrade Guide

Panduan terperinci tentang perubahan paket, mode proration, dan penanganan kegagalan.

Checkout Sessions

Referensi lengkap untuk membuat sesi checkout dengan semua opsi.

Customer Payment Methods API

Referensi API untuk mencantumkan metode pembayaran pelanggan.

Add-ons

Tingkatkan langganan dengan add-on fleksibel untuk pendapatan tambahan.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Post-Purchase Upsells

Subscription Upgrades

Cross-Sells

Overview

Key Benefits

How It Works

Prerequisites

Mendapatkan Metode Pembayaran Pelanggan

Upsell Sekali Klik Setelah Pembelian

Implementasi

Upgrade Langganan

Pratinjau Sebelum Menerapkan

Jalankan Upgrade

Mode Proration

`difference_immediately`

`prorated_immediately`

`full_immediately`

`do_not_bill`

Cross-Sell

Implementasi

Downgrade Langganan

Cara Kerja Downgrade

Contoh Lengkap: Alur Upsell Pascapembelian

Praktik Terbaik

Webhook yang Perlu Dipantau

Webhook Integration Guide

Sumber Daya Terkait

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

​Mendapatkan Metode Pembayaran Pelanggan

​Upsell Sekali Klik Setelah Pembelian

​Implementasi

​Upgrade Langganan

​Pratinjau Sebelum Menerapkan

​Jalankan Upgrade

​Mode Proration

​difference_immediately

​prorated_immediately

​full_immediately

​do_not_bill

​Cross-Sell

​Implementasi

​Downgrade Langganan

​Cara Kerja Downgrade

​Contoh Lengkap: Alur Upsell Pascapembelian

​Praktik Terbaik

​Webhook yang Perlu Dipantau

Webhook Integration Guide

​Sumber Daya Terkait

Subscription Upgrade Guide

Checkout Sessions

Customer Payment Methods API

Add-ons

Overview

Key Benefits

How It Works

Prerequisites

Mendapatkan Metode Pembayaran Pelanggan

Upsell Sekali Klik Setelah Pembelian

Implementasi

Upgrade Langganan

Pratinjau Sebelum Menerapkan

Jalankan Upgrade

Mode Proration

`difference_immediately`

`prorated_immediately`

`full_immediately`

`do_not_bill`

Cross-Sell

Implementasi

Downgrade Langganan

Cara Kerja Downgrade

Contoh Lengkap: Alur Upsell Pascapembelian

Praktik Terbaik

Webhook yang Perlu Dipantau

Sumber Daya Terkait