Upsells & Downsells

Les upsells et downsells vous permettent d’offrir des produits supplémentaires ou des modifications de plan aux clients en utilisant leurs moyens de paiement enregistrés. Cela rend possible des achats en un clic sans collecte de paiement, ce qui améliore considérablement les taux de conversion.

Post-Purchase Upsells

Proposez des produits complémentaires immédiatement après le paiement grâce à un achat en un clic.

Subscription Upgrades

Faites passer les clients à des paliers supérieurs avec attribution automatique et facturation instantanée.

Cross-Sells

Ajoutez des produits connexes aux clients existants sans leur faire ressaisir leurs informations de paiement.

Vue d’ensemble

Les upsells et downsells sont des stratégies puissantes d’optimisation des revenus :

Upsells : Proposez un produit de plus grande valeur ou une montée en gamme (par exemple : plan Pro au lieu de Basic)
Downsells : Proposez une alternative moins chère lorsqu’un client décline ou rétrograde
Cross-sells : Suggérez des produits complémentaires (par exemple : extensions, articles associés)

Dodo Payments rend ces flux possibles grâce au paramètre payment_method_id, qui vous permet de facturer le moyen de paiement enregistré d’un client sans lui demander de ressaisir les données de carte.

Avantages clés

Avantage	Impact
Achats en un clic	Omettez entièrement le formulaire de paiement pour les clients récurrents
Taux de conversion plus élevé	Réduisez les frictions au moment de la décision
Traitement instantané	Les charges sont traitées immédiatement avec `confirm: true`
Expérience fluide	Les clients restent dans votre application pendant tout le flux

Fonctionnement

Prérequis

Avant d’implémenter des upsells et downsells, assurez-vous d’avoir :

Customer with Saved Payment Method

Les clients doivent avoir réalisé au moins un achat. Les moyens de paiement sont automatiquement enregistrés lorsque les clients finalisent leur commande.

Products Configured

Créez vos produits d’upsell dans le tableau de bord Dodo Payments. Il peut s’agir de paiements uniques, d’abonnements ou d’extensions.

Webhook Endpoint

Configurez des webhooks pour gérer les événements payment.succeeded, payment.failed et subscription.plan_changed.

Récupérer les moyens de paiement des clients

Avant de proposer un upsell, récupérez les moyens de paiement enregistrés du client :

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 array of saved payment methods
  // Each has: payment_method_id, type, card (last4, brand, exp_month, exp_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[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 list of saved payment methods
    # Each has: payment_method_id, type, card (last4, brand, exp_month, exp_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[0].payment_method_id if methods else None

package main

import (
    "context"
    "fmt"
    "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)
    }
}

Les moyens de paiement sont automatiquement enregistrés lorsque les clients finalisent leur commande. Vous n’avez pas besoin de les sauvegarder explicitement.

Upsells post-achat en un clic

Proposez des produits supplémentaires immédiatement après un achat réussi. Le client peut accepter d’un simple clic puisqu’il a déjà enregistré son moyen de paiement.

Mise en œuvre

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.length === 0) {
    console.log('No saved payment methods available');
    return null;
  }

  // Create the upsell with one-click checkout
  const upsell = await createOneClickUpsell(
    customerId,
    methods[0].payment_method_id,
    'prod_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:
        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[0].payment_method_id,
        upsell_product_id="prod_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,
        "prod_premium_addon",
    )
    if err != nil {
        return nil, err
    }
    
    fmt.Printf("Upsell processed: %s\n", upsell.SessionID)
    return upsell, nil
}

Lorsque vous utilisez payment_method_id, vous devez définir confirm: true et fournir un customer_id existant. Le moyen de paiement doit appartenir à ce client.

Montées d’abonnement

Faites passer les clients vers des plans d’abonnement supérieurs avec gestion automatique de la proratisation.

Prévisualiser avant de valider

Toujours prévisualiser les changements de plan pour montrer aux clients ce qu’ils vont exactement payer :

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,
    effectiveDate: preview.effective_date
  };
}

// Show customer the charge before confirming
const preview = await previewUpgrade('sub_123', 'prod_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_date": preview.effective_date
    }

# Show customer the charge before confirming
preview = preview_upgrade("sub_123", "prod_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
}

Exécuter la montée de gamme

TypeScript
Python
Go

async function upgradeSubscription(
  subscriptionId: string,
  newProductId: string,
  prorationMode: 'prorated_immediately' | 'difference_immediately' | 'full_immediately' = 'difference_immediately'
) {
  const result = await client.subscriptions.changePlan(subscriptionId, {
    product_id: newProductId,
    quantity: 1,
    proration_billing_mode: prorationMode
  });

  return {
    status: result.status,
    subscriptionId: result.subscription_id,
    paymentId: result.payment_id,
    invoiceId: result.invoice_id
  };
}

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

def upgrade_subscription(
    subscription_id: str,
    new_product_id: str,
    proration_mode: str = "difference_immediately"
):
    result = client.subscriptions.change_plan(
        subscription_id=subscription_id,
        product_id=new_product_id,
        quantity=1,
        proration_billing_mode=proration_mode
    )
    
    return {
        "status": result.status,
        "subscription_id": result.subscription_id,
        "payment_id": result.payment_id,
        "invoice_id": result.invoice_id
    }

# Upgrade from Basic ($30) to Pro ($80)
# With difference_immediately: charges $50 instantly
upgrade = upgrade_subscription("sub_123", "prod_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 no response body; a nil error means the change succeeded.
    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
}

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

Modes de proratisation

Choisissez comment facturer les clients lors d’une montée en gamme :

Mode	Comportement	Idéal pour
`difference_immediately`	Facture immédiatement la différence de prix (30 $→80$ = 50$)	Montées simples
`prorated_immediately`	Facture en fonction du temps restant dans le cycle de facturation	Facturation équitable basée sur le temps
`full_immediately`	Facture le nouveau plan en entier, ignore le temps restant	Réinitialisation du cycle de facturation

Utilisez difference_immediately pour les flux de montée simples. Utilisez prorated_immediately lorsque vous souhaitez tenir compte du temps inutilisé sur le plan actuel.

Cross-sells

Ajoutez des produits complémentaires pour les clients existants sans leur demander de ressaisir leurs informations de paiement.

Mise en œuvre

TypeScript
Python
Go

async function createCrossSell(
  customerId: string,
  paymentMethodId: string,
  productId: string,
  quantity: number = 1
) {
  // Create a one-time payment using saved payment method
  const payment = await client.payments.create({
    product_cart: [
      {
        product_id: productId,
        quantity: quantity
      }
    ],
    customer_id: customerId,
    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.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[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."""
    
    payment = client.payments.create(
        product_cart=[
            {
                "product_id": product_id,
                "quantity": quantity
            }
        ],
        customer_id=customer_id,
        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:
        # 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[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")),
    )
    
    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)
}

Rétrogradations d’abonnement

Lorsqu’un client souhaite passer à un plan inférieur, gérez la transition avec des crédits automatiques.

Comment fonctionnent les rétrogradations

Le client demande une rétrogradation (Pro → Basic)
Le système calcule la valeur restante du plan actuel
Un crédit est ajouté à l’abonnement pour les prochains renouvellements
Le client passe immédiatement au nouveau plan

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

  console.log('Credit to be applied:', preview.credit_amount);

  // Execute the downgrade
  const result = await client.subscriptions.changePlan(subscriptionId, {
    product_id: newProductId,
    quantity: 1,
    proration_billing_mode: 'difference_immediately'
  });

  // Credits are automatically applied to future renewals
  return result;
}

// Downgrade from Pro ($80) to Basic ($30)
// $50 credit added to subscription, auto-applied on next renewal
const downgrade = await downgradeSubscription('sub_123', 'prod_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"
    )
    
    print(f"Credit to be applied: {preview.credit_amount}")
    
    # Execute the downgrade
    result = 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 result

# Downgrade from Pro ($80) to Basic ($30)
# $50 credit added to subscription, auto-applied on next renewal
downgrade = downgrade_subscription("sub_123", "prod_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 no response body; nil error means success)
    return 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),
            },
        },
    )
}

Les crédits provenant des rétrogradations utilisant difference_immediately sont liés à l’abonnement et appliqués automatiquement aux renouvellements futurs. Ils sont distincts des droits de Credit-Based Billing.

Exemple complet : flux d’upsell post-achat

Voici une mise en œuvre complète montrant comment proposer un upsell après un achat réussi :

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_id;
      const productId = event.data.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.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.currency
    },
    paymentMethodId: methods[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[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> = {
    'prod_basic_plan': 'prod_pro_plan',
    'prod_starter_course': 'prod_complete_bundle',
    'prod_single_license': 'prod_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_id']
        product_id = event['data']['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:
        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.currency
        },
        'payment_method_id': methods[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[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 = {
        'prod_basic_plan': 'prod_pro_plan',
        'prod_starter_course': 'prod_complete_bundle',
        'prod_single_license': 'prod_team_license'
    }
    return upsell_map.get(purchased_product_id)

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

Bonnes pratiques

Time Your Upsells Strategically

Le meilleur moment pour proposer un upsell est juste après un achat réussi, lorsque les clients sont dans un état d’esprit propice à l’achat. Autres moments efficaces :

Après des jalons d’utilisation des fonctionnalités
Lorsqu’ils approchent des limites du plan
À la fin de l’onboarding

Validate Payment Method Eligibility

Avant d’essayer une charge en un clic, vérifiez le moyen de paiement :

Est compatible avec la devise du produit
N’est pas expiré
Appartient au client

L’API validera ces éléments, mais les vérifier proactivement améliore l’expérience.

Handle Failures Gracefully

Lorsque les charges en un clic échouent :

Revenir au parcours de paiement classique
Informer le client avec un message clair
Proposer de mettre à jour le moyen de paiement
Ne pas retenter plusieurs fois les charges échouées

Provide Clear Value Proposition

Les upsells convertissent mieux lorsque les clients comprennent la valeur :

Montrez ce qu’ils obtiennent par rapport au plan actuel
Mettez en avant la différence de prix, pas le prix total
Utilisez la preuve sociale (ex. : « Montée en gamme la plus populaire »)

Respect Customer Choice

Proposez toujours une manière simple de décliner
Ne pas afficher le même upsell plusieurs fois après un refus
Suivez et analysez quels upsells convertissent pour optimiser les offres

Webhooks à surveiller

Suivez ces événements webhook pour les flux d’upsell et de rétrogradation :

Événement	Déclencheur	Action
`payment.succeeded`	Paiement d’upsell/cross-sell terminé	Livrer le produit, mettre à jour l’accès
`payment.failed`	Charge en un clic échouée	Afficher l’erreur, proposer une nouvelle tentative ou une solution de secours
`subscription.plan_changed`	Montée/rétrogradation terminée	Mettre à jour les fonctionnalités, envoyer une confirmation
`subscription.active`	Réactivation d’abonnement après changement de plan	Accorder l’accès au nouveau palier

Webhook Integration Guide

Apprenez à configurer et vérifier les points de terminaison webhook.

Ressources associées

Subscription Upgrade Guide

Guide détaillé sur les changements de plan, les modes de proratisation et la gestion des échecs.

Checkout Sessions

Référence complète pour créer des sessions de paiement avec toutes les options.

Customer Payment Methods API

Référence API pour lister les moyens de paiement des clients.

Add-ons

Améliorez les abonnements avec des extensions flexibles pour générer des revenus supplémentaires.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Post-Purchase Upsells

Subscription Upgrades

Cross-Sells

Vue d’ensemble

Avantages clés

Fonctionnement

Prérequis

Récupérer les moyens de paiement des clients

Upsells post-achat en un clic

Mise en œuvre

Montées d’abonnement

Prévisualiser avant de valider

Exécuter la montée de gamme

Modes de proratisation

Cross-sells

Mise en œuvre

Rétrogradations d’abonnement

Comment fonctionnent les rétrogradations

Exemple complet : flux d’upsell post-achat

Bonnes pratiques

Webhooks à surveiller

Webhook Integration Guide

Ressources associées

Subscription Upgrade Guide

Checkout Sessions

Customer Payment Methods API

Add-ons

Post-Purchase Upsells

Subscription Upgrades

Cross-Sells

​Vue d’ensemble

​Avantages clés

​Fonctionnement

​Prérequis

​Récupérer les moyens de paiement des clients

​Upsells post-achat en un clic

​Mise en œuvre

​Montées d’abonnement

​Prévisualiser avant de valider

​Exécuter la montée de gamme

​Modes de proratisation

​Cross-sells

​Mise en œuvre

​Rétrogradations d’abonnement

​Comment fonctionnent les rétrogradations

​Exemple complet : flux d’upsell post-achat

​Bonnes pratiques

​Webhooks à surveiller

Webhook Integration Guide

​Ressources associées

Subscription Upgrade Guide

Checkout Sessions

Customer Payment Methods API

Add-ons

Vue d’ensemble

Avantages clés

Fonctionnement

Prérequis

Récupérer les moyens de paiement des clients

Upsells post-achat en un clic

Mise en œuvre

Montées d’abonnement

Prévisualiser avant de valider

Exécuter la montée de gamme

Modes de proratisation

Cross-sells

Mise en œuvre

Rétrogradations d’abonnement

Comment fonctionnent les rétrogradations

Exemple complet : flux d’upsell post-achat

Bonnes pratiques

Webhooks à surveiller

Ressources associées