Subscription Upgrade & Downgrade Guide

​

What is a subscription upgrade or downgrade?

• Align pricing with usage or features
• Move from monthly to annual (or vice versa)
• Adjust quantity for seat-based products

​

When to use plan changes

• Upgrade when a customer needs more features, usage, or seats
• Downgrade when usage decreases
• Migrate users to a new product or price without cancelling their subscription

​

Plan Change Flow

​

Prerequisites

• A Dodo Payments merchant account with active subscription products
• API credentials (API key and webhook secret key) from the dashboard
• An existing active subscription to modify
• Webhook endpoint configured to handle subscription events

​

Step-by-Step Implementation Guide

​

प्लान परिवर्तन पूर्वावलोकन

const preview = await client.subscriptions.previewChangePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

// Show customer the charge before confirming
console.log('Immediate charge:', preview.immediate_charge.summary);
console.log('New plan details:', preview.new_plan);

preview = client.subscriptions.preview_change_plan(
    subscription_id="sub_123",
    product_id="prod_pro",
    quantity=1,
    proration_billing_mode="prorated_immediately"
)

# Show customer the charge before confirming
print("Immediate charge:", preview.immediate_charge.summary)
print("New plan details:", preview.new_plan)

​

प्लान चेंज API

​

त्वरित प्रारंभ उदाहरण

import DodoPayments from 'dodopayments';

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

async function changePlan() {
  const result = await client.subscriptions.changePlan('sub_123', {
    product_id: 'prod_new',
    quantity: 3,
    proration_billing_mode: 'prorated_immediately',
    on_payment_failure: 'prevent_change', // Optional: control behavior on payment failure
  });
  console.log(result.status, result.invoice_id, result.payment_id);
}

changePlan();

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",  # defaults to "live_mode"
)

result = client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="prod_new",
    quantity=3,
    proration_billing_mode="prorated_immediately",
    on_payment_failure="prevent_change",  # Optional: control behavior on payment failure
)
print(result.status, result.get("invoice_id"), result.get("payment_id"))

package main

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

func main() {
  client := dodopayments.NewClient(option.WithBearerToken("YOUR_TOKEN"))
  // ChangePlan returns no response body; a nil error means the change succeeded.
  err := client.Subscriptions.ChangePlan(context.TODO(), "sub_123", dodopayments.SubscriptionChangePlanParams{
    UpdateSubscriptionPlanReq: dodopayments.UpdateSubscriptionPlanReqParam{
      ProductID:            dodopayments.F("prod_new"),
      Quantity:             dodopayments.F(int64(3)),
      ProrationBillingMode: dodopayments.F(dodopayments.UpdateSubscriptionPlanReqProrationBillingModeProratedImmediately),
      OnPaymentFailure:     dodopayments.F(dodopayments.UpdateSubscriptionPlanReqOnPaymentFailurePreventChange), // Optional
    },
  })
  if err != nil { panic(err) }
  fmt.Println("Plan change applied")
}

curl -X POST "$DODO_API_BASE/subscriptions/sub_123/change-plan" \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_new",
    "quantity": 3,
    "proration_billing_mode": "prorated_immediately",
    "on_payment_failure": "prevent_change"
  }'

{
  "status": "processing",
  "subscription_id": "sub_123",
  "invoice_id": "inv_789",
  "payment_id": "pay_456",
  "proration_billing_mode": "prorated_immediately"
}

​

एडऑन्स का प्रबंधन

// Add addons to the new plan
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [
    { addon_id: 'addon_123', quantity: 2 }
  ]
});

// Remove all existing addons
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [] // Empty array removes all existing addons
});

​

छूट कोड लागू करना

// Apply stacked discount codes during plan change
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_codes: ['UPGRADE20']
});

# Apply stacked discount codes during plan change
client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="prod_pro",
    quantity=1,
    proration_billing_mode="prorated_immediately",
    discount_codes=["UPGRADE20"]
)

curl -X POST "$DODO_API_BASE/subscriptions/sub_123/change-plan" \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_pro",
    "quantity": 1,
    "proration_billing_mode": "prorated_immediately",
    "discount_codes": ["UPGRADE20"]
  }'

​

प्लान परिवर्तन पर छूट व्यवहार

​

प्ररोशन मोड्स

​

prorated_immediately

• वर्तमान चक्र में आंशिक अंतर के लिए चार्ज करता है
• यदि परीक्षण में है, तो तुरंत चार्ज करता है और अब नए प्लान पर स्विच करता है
• डाउनग्रेड: भविष्य के नवीनीकरणों पर लागू होने के लिए एक प्ररोक्षित क्रेडिट उत्पन्न कर सकता है

​

full_immediately

• नए प्लान की पूरी राशि को तुरंत चार्ज करता है
• पुराने प्लान के शेष समय की उपेक्षा करता है

​

difference_immediately

• अपग्रेड: पुराने और नए प्लान के बीच मूल्य अंतर को तुरंत चार्ज करें
• डाउनग्रेड: शेष मूल्य को सदस्यता के लिए आंतरिक क्रेडिट के रूप में जोड़ें और नवीनीकरणों पर ऑटो-लागू करें

​

do_not_bill

• कोई चार्ज या क्रेडिट की गणना नहीं की जाती
• ग्राहक बिना किसी बिलिंग समायोजन के तुरंत नए प्लान पर स्विच करता है
• बिलिंग चक्र अपरिवर्तित रहता है
• शिष्टाचार माइग्रेशन, मुफ्त प्लान स्विच, या लागत अंतर को अवशोषित करने के लिए सबसे अच्छा

​

उदाहरण परिदृश्य

• वर्तमान प्लान: बेसिक $30/माह
• अपग्रेड लक्ष्य: प्रो $80/माह
• डाउनग्रेड लक्ष्य (प्रो से): स्टार्टर $20/माह
• बिलिंग चक्र: 30 दिन जनवरी 1 को शुरू हुआ
• प्लान परिवर्तन जनवरी 16 को होता है (15 दिन बचे हुए, 15 दिन उपयोग किए गए)

Step 1: Calculate unused credit from current plan
  Unused days = 15 out of 30 days
  Credit = $30 × (15/30) = $15.00

Step 2: Calculate prorated cost of new plan
  Remaining days = 15 out of 30 days
  New plan cost = $80 × (15/30) = $40.00

Step 3: Calculate immediate charge
  Charge = New plan cost − Credit
  Charge = $40.00 − $15.00 = $25.00

→ Customer pays $25.00 now
→ Next renewal (Feb 1): $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
})

Step 1: Calculate unused credit from current plan
  Unused days = 15 out of 30 days
  Credit = $80 × (15/30) = $40.00

Step 2: Calculate prorated cost of new plan
  Remaining days = 15 out of 30 days
  New plan cost = $20 × (15/30) = $10.00

Step 3: Calculate credit balance
  Credit = $40.00 − $10.00 = $30.00

→ No charge — $30.00 credit added to subscription
→ Credit auto-applies to future renewals
→ Next renewal (Feb 1): $20.00 − $30.00 credit = $0.00
→ Following renewal (Mar 1): $20.00 − $10.00 remaining credit = $10.00

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_starter',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
})

Immediate charge = New plan price − Old plan price
                 = $80 − $30
                 = $50.00

→ Customer pays $50.00 now (regardless of cycle position)
→ Next renewal (Feb 1): $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
})

Credit = Old plan price − New plan price
       = $80 − $20
       = $60.00

→ No charge — $60.00 credit added to subscription
→ Credit auto-applies to future renewals
→ Next renewal: $20.00 − $20.00 (from credit) = $0.00
→ Following renewal: $20.00 − $20.00 (from credit) = $0.00
→ Third renewal: $20.00 − $20.00 (from remaining credit) = $0.00

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_starter',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
})

Immediate charge = Full new plan price = $80.00

→ Customer pays $80.00 now
→ No credit for unused time on old plan
→ Billing cycle resets to today (January 16)
→ Next renewal: February 16 at $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'full_immediately'
})

Current: Basic plan ($30/month), no add-ons
New: Pro plan ($80/month) + Extra Seats add-on ($10/seat × 3 seats = $30/month)
Change on day 16 of 30 (15 days remaining)

Step 1: Credit from current plan
  Credit = $30 × (15/30) = $15.00

Step 2: Prorated cost of new plan + add-ons
  New plan = $80 × (15/30) = $40.00
  Add-ons = $30 × (15/30) = $15.00
  Total new = $55.00

Step 3: Immediate charge
  Charge = $55.00 − $15.00 = $40.00

→ Customer pays $40.00 now
→ Next renewal: $80.00 + $30.00 = $110.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  addons: [
    { addon_id: 'addon_seats', quantity: 3 }
  ]
})

​

प्रत्येक मोड कैसे बिलिंग प्रोसेस करता है

​

भुगतान विफलताओं को संभालना

​

भुगतान विफलता मोड

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  on_payment_failure: 'prevent_change'
});

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  on_payment_failure: 'apply_change' // This is the default
});

​

कब प्रत्येक मोड का उपयोग करना चाहिए

​

वेबहूक हैंडलिंग

​

इवेंट प्रकार जिन्हें संभालना है

• subscription.active: सदस्यता सक्रिय की गई
• subscription.plan_changed: सदस्यता प्लान बदला गया (अपग्रेड/डाउनग्रेड/एडऑन परिवर्तन)
• subscription.on_hold: चार्ज विफल, सदस्यता रुकी
• subscription.renewed: नवीनीकरण सफल
• payment.succeeded: प्लान परिवर्तन या नवीनीकरण के लिए भुगतान सफल
• payment.failed: भुगतान विफल

​

संकेतों को सत्यापित करें और इरादों को संभालें

import { NextRequest, NextResponse } from 'next/server';

export async function POST(req) {
  const webhookId = req.headers.get('webhook-id');
  const webhookSignature = req.headers.get('webhook-signature');
  const webhookTimestamp = req.headers.get('webhook-timestamp');
  const secret = process.env.DODO_WEBHOOK_SECRET;

  const payload = await req.text();
  // verifySignature is a placeholder – in production, use a Standard Webhooks library
  const { valid, event } = await verifySignature(
    payload,
    { id: webhookId, signature: webhookSignature, timestamp: webhookTimestamp },
    secret
  );
  if (!valid) return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });

  switch (event.type) {
    case 'subscription.active':
      // mark subscription active in your DB
      break;
    case 'subscription.plan_changed':
      // refresh entitlements and reflect the new plan in your UI
      break;
    case 'subscription.on_hold':
      // notify user to update payment method
      break;
    case 'subscription.renewed':
      // extend access window
      break;
    case 'payment.succeeded':
      // reconcile payment for plan change
      break;
    case 'payment.failed':
      // log and alert
      break;
    default:
      // ignore unknown events
      break;
  }

  return NextResponse.json({ received: true });
}

import express from 'express';

const app = express();
app.post('/webhooks/dodo', express.raw({ type: 'application/json' }), async (req, res) => {
  const webhookId = req.header('webhook-id');
  const webhookSignature = req.header('webhook-signature');
  const webhookTimestamp = req.header('webhook-timestamp');
  const secret = process.env.DODO_WEBHOOK_SECRET;
  const payload = req.body.toString('utf8');

  const { valid, event } = await verifySignature(
    payload,
    { id: webhookId, signature: webhookSignature, timestamp: webhookTimestamp },
    secret
  );
  if (!valid) return res.status(400).send('Invalid signature');

  // handle events like above
  res.json({ received: true });
});

app.listen(3000);

​

सर्वोत्तम अभ्यास

​

प्लान परिवर्तन रणनीति

• पूरी तरह से परीक्षण करें: हमेशा उत्पादन से पहले परीक्षण मोड में प्लान परिवर्तनों का परीक्षण करें
• प्ररोशन को सावधानी से चुनें: उस प्ररोशन मोड को चुनें जो आपके व्यवसाय मॉडल के साथ मेल खाता है
• त्रुटियों को अनुग्रहपूर्वक संभालें: उचित त्रुटि प्रबंधन और पुनः प्रयास करने का तर्क लागू करें
• सफलता दर की निगरानी करें: प्लान परिवर्तन सफलता/विफलता दर को ट्रैक करें और समस्याओं की जांच करें

​

वेबहूक कार्यान्वयन

• संकेतों को सत्यापित करें: प्रमाणीकरण सुनिश्चित करने के लिए हमेशा वेबहूक संकेतों को सत्यापित करें
• आइडंपोटेंसी लागू करें: डुप्लिकेट वेबहूक घटनाओं को अनुग्रहपूर्वक संभालें
• असिंक्रोनस रूप से प्रक्रिया करें: भारी परिचालन के साथ वेबहूक प्रतिक्रिया को अवरोधित न करें
• सब कुछ लॉग करें: डीबगिंग और ऑडिट उद्देश्यों के लिए विस्तृत लॉग्स रखें

​

उपयोगकर्ता अनुभव

• स्पष्ट रूप से संवाद करें: ग्राहकों को बिलिंग परिवर्तनों और समय की जानकारी दें
• पुष्टीकरण प्रदान करें: सफल प्लान परिवर्तनों के लिए ईमेल पुष्टिकरण भेजें
• एज केस को संभालें: परीक्षण अवधि, प्ररोशन, और विफल भुगतान को ध्यान में रखें
• UI को तुरंत अपडेट करें: अपनी एप्लिकेशन इंटरफ़ेस में प्लान परिवर्तन को प्रतिबिंबित करें

​

सामान्य समस्याएं और समाधान

// Reactivate subscription from on_hold after failed plan change
async function reactivateAfterFailedPlanChange(subscriptionId) {
  // Update payment method - automatically creates charge for remaining dues
  const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
    type: 'new',
    return_url: 'https://example.com/return'
  });
  
  if (response.payment_id) {
    console.log('Charge created for remaining dues:', response.payment_id);
    console.log('Payment link:', response.payment_link);
    
    // Redirect customer to payment_link to complete payment
    // Monitor webhooks for:
    // 1. payment.succeeded - charge succeeded
    // 2. subscription.active - subscription reactivated
  }
  
  return response;
}

// Or use existing payment method if available
async function reactivateWithExistingPaymentMethod(subscriptionId, paymentMethodId) {
  const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
    type: 'existing',
    payment_method_id: paymentMethodId
  });
  
  // Monitor webhooks for payment.succeeded and subscription.active
  return response;
}

# Reactivate subscription from on_hold after failed plan change
def reactivate_after_failed_plan_change(subscription_id):
    # Update payment method - automatically creates charge for remaining dues
    response = client.subscriptions.update_payment_method(
        subscription_id=subscription_id,
        type="new",
        return_url="https://example.com/return"
    )
    
    if response.payment_id:
        print("Charge created for remaining dues:", response.payment_id)
        print("Payment link:", response.payment_link)
        
        # Redirect customer to payment_link to complete payment
        # Monitor webhooks for:
        # 1. payment.succeeded - charge succeeded
        # 2. subscription.active - subscription reactivated
    
    return response

# Or use existing payment method if available
def reactivate_with_existing_payment_method(subscription_id, payment_method_id):
    response = client.subscriptions.update_payment_method(
        subscription_id=subscription_id,
        type="existing",
        payment_method_id=payment_method_id
    )
    
    # Monitor webhooks for payment.succeeded and subscription.active
    return response

​

अपने कार्यान्वयन को परीक्षण करें

​

त्रुटि हैंडलिंग

​

HTTP स्थिति कोड

​

त्रुटि प्रतिक्रिया प्रारूप

{
  "error": {
    "code": "subscription_not_found",
    "message": "The subscription with ID 'sub_123' was not found",
    "details": {
      "subscription_id": "sub_123"
    }
  }
}

​

अगले कदम

• प्लान चेंज API की समीक्षा करें
• क्रेडिट-आधारित बिलिंग का अन्वेषण करें
• subscription.on_hold के लिए अलर्ट लागू करें
• हमारे वेबहूक इंटीग्रेशन गाइड देखें

​

त्रुटि प्रतिक्रिया प्रारूप

{
  "error": {
    "code": "subscription_not_found",
    "message": "The subscription with ID 'sub_123' was not found",
    "details": {
      "subscription_id": "sub_123"
    }
  }
}

​

अगले कदम

• प्लान API बदलें की समीक्षा करें
• क्रेडिट-बेस्ड बिलिंग का अनुसंधान करें
• subscription.on_hold के लिए अलर्ट लागू करें
• हमारे Webhook इंटीग्रेशन गाइड को देखें