Upsells y Downsells

Los upsells y downsells te permiten ofrecer productos adicionales o cambios de plan a los clientes que usan sus métodos de pago guardados. Esto habilita compras con un solo clic que omiten la recolección del pago, mejorando drásticamente las tasas de conversión.

Post-Purchase Upsells

Ofrece productos complementarios inmediatamente después del checkout con compras con un solo clic.

Subscription Upgrades

Mueve a los clientes a niveles superiores con prorrateo automático y facturación instantánea.

Cross-Sells

Agrega productos relacionados a clientes existentes sin volver a ingresar los datos de pago.

Descripción General

Los upsells y downsells son poderosas estrategias de optimización de ingresos:

Upsells: Ofrecer un producto o actualización de mayor valor (por ejemplo, plan Pro en lugar de Básico)
Downsells: Ofrecer una alternativa de menor precio cuando un cliente rechaza o degrada
Ventas Cruzadas: Sugerir productos complementarios (por ejemplo, complementos, artículos relacionados)

Dodo Payments habilita estos flujos a través del parámetro payment_method_id, que te permite cobrar el método de pago guardado de un cliente sin pedirle que vuelva a ingresar los datos de la tarjeta.

Beneficios Clave

Beneficio	Impacto
Compras con un clic	Omitir el formulario de pago para clientes recurrentes
Mayor conversión	Reducir la fricción en el momento de la decisión
Procesamiento instantáneo	Los cargos se procesan inmediatamente con `confirm: true`
Experiencia dentro de la aplicación	Los clientes permanecen en tu aplicación durante todo el flujo

Cómo Funciona

Requisitos Previos

Antes de implementar upsells y downsells, asegúrate de tener:

Clientes con métodos de pago guardados (se guardan automáticamente después de su primera compra)
Productos de venta adicional configurados en el dashboard (pagos únicos, suscripciones o complementos)
Un endpoint de webhook configurado para gestionar los eventos payment.succeeded, payment.failed y subscription.plan_changed

Cómo obtener los métodos de pago del cliente

Antes de ofrecer una venta adicional, obtén los métodos de pago guardados del cliente:

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

Los métodos de pago se guardan automáticamente cuando los clientes completan el checkout. No necesitas guardarlos explícitamente.

Ventas adicionales con un clic después de la compra

Ofrece productos adicionales inmediatamente después de una compra exitosa. El cliente puede aceptarlos con un solo clic, ya que su método de pago ya está guardado.

Implementación

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
}

Cuando pasas payment_method_id a una sesión de checkout, también debes establecer confirm: true y proporcionar un customer_id existente. El método de pago debe pertenecer a ese cliente. POST /payments no tiene el campo confirm.

Mejoras de suscripción

Cambia a los clientes a planes de suscripción de nivel superior con una gestión automática de la prorrata.

Vista previa antes de confirmar

Muestra siempre una vista previa de los cambios del plan para indicar a los clientes exactamente cuánto se les cobrará:

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
}

Ejecutar la mejora

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

Modos de prorrata

Elige cómo se facturará a los clientes al mejorar de plan:

`difference_immediately`

Cobra la diferencia de precio al instante ($30→$80 = $50). Ideal para mejoras sencillas.

`prorated_immediately`

Abona el tiempo no utilizado del plan anterior y luego cobra un ciclo completo del nuevo plan. Ideal para compensar el tiempo no utilizado.

`full_immediately`

Cobra el precio completo del nuevo plan e ignora el tiempo restante. Ideal para reiniciar el ciclo de facturación.

`do_not_bill`

Aplica el cambio de plan sin ningún cargo inmediato; el nuevo plan se factura en la siguiente renovación y se conserva la fecha de facturación original. Ideal para mejoras de cortesía y migraciones gratuitas.

Usa difference_immediately para flujos de mejora sencillos: el cargo es la diferencia de precio exacta. Usa prorated_immediately cuando quieras compensar al cliente por el tiempo no utilizado del plan actual y cobrarle un ciclo completo del nuevo plan.

Ventas cruzadas

Añade productos complementarios para clientes existentes sin pedirles que vuelvan a introducir sus datos de pago.

Implementación

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

Reducciones de suscripción

Cuando los clientes quieran cambiar a un plan de nivel inferior, gestiona la transición correctamente con créditos automáticos.

Cómo funcionan las reducciones

El cliente solicita una reducción (Pro → Basic)
El sistema calcula el valor restante del plan actual
Se añade un crédito a la suscripción para futuras renovaciones
El cliente cambia inmediatamente al nuevo plan

El immediate_charge.summary.customer_credits de la vista previa está en la moneda de la billetera de crédito del cliente, indicada por customer_credits_currency. Puede diferir de currency del resumen, por ejemplo, cuando el cliente paga en INR una suscripción en 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
}

Los créditos procedentes de downgrades que utilizan difference_immediately están asociados al ámbito de la suscripción y se aplican automáticamente a futuras renovaciones. Son distintos de las ventajas de Credit-Based Billing.

Ejemplo completo: flujo de upsell posterior a la compra

Esta es una implementación completa que muestra cómo ofrecer un upsell después de una compra exitosa:

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)

Prácticas recomendadas

Elige el momento estratégicamente: ofrece upsells inmediatamente después de una compra exitosa, cuando los clientes tienen una actitud favorable a comprar. Otros momentos eficaces: después de alcanzar hitos de uso de funcionalidades, al acercarse a los límites del plan y al completar el onboarding.
Valida los métodos de pago: antes de intentar un cobro con un clic, verifica que el método de pago sea compatible con la moneda del producto, no haya caducado y pertenezca al cliente.
Gestiona los fallos correctamente: cuando fallen los cobros con un clic, recurre al flujo de checkout estándar, notifica al cliente con un mensaje claro y ofrece actualizar el método de pago.
Comunica claramente el valor: muestra lo que obtendrán los clientes en comparación con su plan actual, destaca la diferencia de precio (no el precio total) y utiliza prueba social.
Respeta la elección del cliente: proporciona siempre una forma sencilla de rechazar la oferta, no muestres el mismo upsell repetidamente después de un rechazo y registra qué upsells generan conversiones para optimizar las ofertas.

Webhooks que debes supervisar

Registra estos eventos de webhook para los flujos de upsell y downgrade:

Evento	Activador	Acción
`payment.succeeded`	Pago de upsell/cross-sell completado	Entregar el producto, actualizar el acceso
`payment.failed`	Fallo del cobro con un clic	Mostrar el error, ofrecer reintentar o recurrir a una alternativa
`subscription.plan_changed`	Upgrade/downgrade completado	Actualizar las funcionalidades, enviar confirmación
`subscription.active`	Suscripción reactivada después de un cambio de plan	Conceder acceso al nuevo nivel

Webhook Integration Guide

Aprende a configurar y verificar endpoints de webhook.

Recursos relacionados

Subscription Upgrade Guide

Guía detallada sobre cambios de plan, modos de prorrateo y gestión de fallos.

Checkout Sessions

Referencia completa para crear sesiones de checkout con todas las opciones.

Customer Payment Methods API

Referencia de API para enumerar los métodos de pago del cliente.

Add-ons

Mejora las suscripciones con complementos flexibles para generar ingresos adicionales.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Post-Purchase Upsells

Subscription Upgrades

Cross-Sells

Descripción General

Beneficios Clave

Cómo Funciona

Requisitos Previos

Cómo obtener los métodos de pago del cliente

Ventas adicionales con un clic después de la compra

Implementación

Mejoras de suscripción

Vista previa antes de confirmar

Ejecutar la mejora

Modos de prorrata

`difference_immediately`

`prorated_immediately`

`full_immediately`

`do_not_bill`

Ventas cruzadas

Implementación

Reducciones de suscripción

Cómo funcionan las reducciones

Ejemplo completo: flujo de upsell posterior a la compra

Prácticas recomendadas

Webhooks que debes supervisar

Webhook Integration Guide

Recursos relacionados

Subscription Upgrade Guide

Checkout Sessions

Customer Payment Methods API

Add-ons

Post-Purchase Upsells

Subscription Upgrades

Cross-Sells

​Descripción General

​Beneficios Clave

​Cómo Funciona

​Requisitos Previos

​Cómo obtener los métodos de pago del cliente

​Ventas adicionales con un clic después de la compra

​Implementación

​Mejoras de suscripción

​Vista previa antes de confirmar

​Ejecutar la mejora

​Modos de prorrata

​difference_immediately

​prorated_immediately

​full_immediately

​do_not_bill

​Ventas cruzadas

​Implementación

​Reducciones de suscripción

​Cómo funcionan las reducciones

​Ejemplo completo: flujo de upsell posterior a la compra

​Prácticas recomendadas

​Webhooks que debes supervisar

Webhook Integration Guide

​Recursos relacionados

Subscription Upgrade Guide

Checkout Sessions

Customer Payment Methods API

Add-ons

Descripción General

Beneficios Clave

Cómo Funciona

Requisitos Previos

Cómo obtener los métodos de pago del cliente

Ventas adicionales con un clic después de la compra

Implementación

Mejoras de suscripción

Vista previa antes de confirmar

Ejecutar la mejora

Modos de prorrata

`difference_immediately`

`prorated_immediately`

`full_immediately`

`do_not_bill`

Ventas cruzadas

Implementación

Reducciones de suscripción

Cómo funcionan las reducciones

Ejemplo completo: flujo de upsell posterior a la compra

Prácticas recomendadas

Webhooks que debes supervisar

Recursos relacionados