Subscription Upgrade & Downgrade Guide

​

Subscription Upgrade या Downgrade क्या है?

​

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

​

Plan Changes का Preview लें

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

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

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

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

​

Change Plan API

​

Quick Start Examples

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() {
  // change-plan returns 200 with a ChangePlanResponse body (payment_id, payment_link,
  // client_secret, expires_on) — all null for an ordinary off-session change.
  await client.subscriptions.changePlan('sub_123', {
    product_id: 'pdt_new',
    quantity: 3,
    proration_billing_mode: 'prorated_immediately',
    on_payment_failure: 'prevent_change', // Optional: control behavior on payment failure
  });
  console.log('Plan change accepted; awaiting webhooks');
}

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

# change_plan returns 200 with a ChangePlanResponse body (payment_id, payment_link,
# client_secret, expires_on) — all None for an ordinary off-session change.
client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="pdt_new",
    quantity=3,
    proration_billing_mode="prorated_immediately",
    on_payment_failure="prevent_change",  # Optional: control behavior on payment failure
)
print("Plan change accepted; awaiting webhooks")

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 a SubscriptionChangePlanResponse alongside the error.
  _, err := client.Subscriptions.ChangePlan(context.TODO(), "sub_123", dodopayments.SubscriptionChangePlanParams{
    UpdateSubscriptionPlanReq: dodopayments.UpdateSubscriptionPlanReqParam{
      ProductID:            dodopayments.F("pdt_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": "pdt_new",
    "quantity": 3,
    "proration_billing_mode": "prorated_immediately",
    "on_payment_failure": "prevent_change"
  }'

​

Checkout Link के माध्यम से Payment Collect करना

​

Requirements

• Business में allow_plan_change_via_payment_link capability enabled हो (Settings → Subscriptions → Collect Plan Change Payments by Payment Link)।
• effective_at, immediately हो (default)। Scheduled change (next_billing_date) को checkout page की आवश्यकता कभी नहीं होती।
• Effective on_payment_failure, prevent_change पर resolve हो। इसे explicitly भेजना आवश्यक नहीं — यदि business-level default पहले से prevent_change है, तो field छोड़ने पर यह शर्त पूरी हो जाती है। Explicit apply_change, 422 के साथ fail होता है।

const response = await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  effective_at: 'immediately',
  on_payment_failure: 'prevent_change',
  collect_via_payment_link: true,
});

// Hand response.payment_link to your frontend and send the customer there
console.log(response.payment_link);

response = client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="pdt_pro",
    quantity=1,
    proration_billing_mode="prorated_immediately",
    effective_at="immediately",
    on_payment_failure="prevent_change",
    collect_via_payment_link=True,
)

# Hand response.payment_link to your frontend and send the customer there
print(response.payment_link)

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": "pdt_pro",
    "quantity": 1,
    "proration_billing_mode": "prorated_immediately",
    "effective_at": "immediately",
    "on_payment_failure": "prevent_change",
    "collect_via_payment_link": true
  }'

{
  "payment_id": "<payment_id>",
  "payment_link": "https://checkout.dodopayments.com/...",
  "client_secret": "<client_secret>",
  "expires_on": "<expires_on>"
}

​

जब Link Unpaid हो तो क्या होता है

• Subscription अपने वर्तमान plan पर रहती है — product_id, recurring_pre_tax_amount और next_billing_date सभी link के paid होने तक अपरिवर्तित रहते हैं।
• Link pending रहने के दौरान आगे की change-plan request, 409 PendingPlanChangeExists के साथ reject होती है। आवश्यकता होने पर scheduled change को DELETE /subscriptions/{subscription_id}/change-plan/scheduled से cancel करें, लेकिन वह endpoint pending payment-link change को cancel नहीं करता — केवल सफल payment या expiry ही ऐसा करता है।
• Decline के बाद customer उसी checkout session पर card retry कर सकता है; नई change-plan call retry path नहीं है।
• यदि link कभी paid नहीं होता, तो expires_on के बाद वह काम करना बंद कर देता है — subscription शीघ्र ही नए plan-change request को स्वीकार करने के लिए स्वतः free हो जाती है।
• यदि कोई scheduled change पहले से मौजूद था और आप उसे cancel_scheduled_change_plan: true से replace करते हैं, तो link unpaid रहने तक original schedule बना रहता है और link paid होने पर ही cancel होता है — उसी transaction में जिसमें नया plan लागू होता है।

​

Addons Manage करना

// Add addons to the new plan
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_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: 'pdt_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [] // Empty array removes all existing addons
});

​

Discount Codes लागू करना

// Apply stacked discount codes during plan change
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_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="pdt_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": "pdt_pro",
    "quantity": 1,
    "proration_billing_mode": "prorated_immediately",
    "discount_codes": ["UPGRADE20"]
  }'

​

Plan Change पर Discount Behavior

​

Proration Modes

​

prorated_immediately

• वर्तमान cycle — base plan, quantity और add-ons — के अप्रयुक्त हिस्से का समय शेष रहने के आधार पर prorated credit देता है
• फिर नए plan, quantity और add-ons पर पूरे cycle का charge लेता है। Charge स्वयं कभी prorated नहीं होता
• Net immediate charge = (पूरा नया cycle) − (शेष अंश × पूरा पुराना cycle)
• यदि credit नए cycle charge से अधिक हो (जो downgrades में सामान्य है), तो अंतर subscription-scoped credit के रूप में future renewals के लिए रखा जाता है
• यदि trial में है, तो तुरंत charge करता है और अभी नए plan पर switch करता है

​

full_immediately

• नए plan की पूरी amount तुरंत charge करता है
• पुराने plan का शेष समय अनदेखा करता है — वर्तमान cycle के लिए कोई credit नहीं

​

difference_immediately

• Upgrade: पुराने और नए plans के बीच price difference तुरंत charge करता है
• Downgrade: शेष value को subscription में internal credit के रूप में जोड़ता है और renewals पर स्वतः लागू करता है

​

do_not_bill

• कोई charges या credits calculate नहीं किए जाते
• Customer बिना किसी billing adjustment के तुरंत नए plan पर switch करता है
• Billing cycle अपरिवर्तित रहता है
• Courtesy migrations, free plan switches या cost differences को absorb करने के लिए उपयुक्त

​

Example Scenarios

• Current plan: Basic at $30/month
• Upgrade target: Pro at $80/month
• Downgrade target (from Pro): Starter at $20/month
• Billing cycle: 30 days, started on January 1
• Plan change happens on January 16 (15 days remaining, 15 days used)

Step 1: Credit the unused time on the current plan
  Unused days = 15 out of 30 days
  Credit = $30 × (15/30) = $15.00

Step 2: Charge a full cycle at the new plan
  New plan cost = $80.00 (never prorated)

Step 3: Calculate immediate charge
  Charge = Full new cycle − Credit
  Charge = $80.00 − $15.00 = $65.00

→ Customer pays $65.00 now
→ Customer starts a full month of Pro today
→ Billing cycle resets to today (January 16)
→ Next renewal (Feb 15): $80.00/month

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

Step 1: Credit the unused time on the current plan
  Unused days = 15 out of 30 days
  Credit = $80 × (15/30) = $40.00

Step 2: Charge a full cycle at the new plan
  New plan cost = $20.00 (never prorated)

Step 3: Net the two
  Net = $20.00 − $40.00 = −$20.00

→ No charge — $20.00 credit added to subscription
→ Billing cycle resets to today (January 16)
→ Credit auto-applies to future renewals
→ Next renewal (Feb 15): $20.00 − $20.00 (from credit) = $0.00 (credit exhausted)
→ Following renewal (Mar 15): $20.00

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_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)
→ Billing cycle resets to today (January 16)
→ Next renewal (Feb 15): $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_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: 'pdt_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: 'pdt_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 the unused time on the current plan
  Credit = $30 × (15/30) = $15.00

Step 2: Charge a full cycle at the new plan + add-ons
  New plan = $80.00
  Add-ons  = $30.00
  Total new = $110.00 (never prorated)

Step 3: Immediate charge
  Charge = $110.00 − $15.00 = $95.00

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

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

​

प्रत्येक Mode Billing को कैसे Process करता है

​

Payment Failures Handle करना

​

Payment Failure Modes

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

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

​

प्रत्येक Mode का उपयोग कब करें

​

Business & Collection Defaults

​

Resolution Order

per-request value (Change Plan API) → collection field (if set) → business field → system default

​

Webhooks Handle करना

​

Handle करने योग्य Event Types

• subscription.active: subscription activated
• subscription.plan_changed: subscription plan changed (upgrade/downgrade/addon changes)
• subscription.on_hold: charge failed, renewals stopped
• subscription.renewed: renewal succeeded
• payment.succeeded: plan change या renewal का payment सफल
• payment.failed: payment failed

​

Signatures Verify करें और Intents Handle करें

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_PAYMENTS_WEBHOOK_KEY;

  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_PAYMENTS_WEBHOOK_KEY;
  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);

​

Best Practices

​

Plan Change Strategy

• Thoroughly test करें: Production से पहले plan changes को हमेशा test mode में test करें
• Proration सावधानी से चुनें: अपने business model के अनुरूप proration mode चुनें
• Failures को gracefully handle करें: उचित error handling और retry logic लागू करें
• Success rates monitor करें: Plan change success/failure rates track करें और issues की जाँच करें

​

Webhook Implementation

• Signatures verify करें: Authenticity सुनिश्चित करने के लिए webhook signatures को हमेशा validate करें
• Idempotency लागू करें: Duplicate webhook events को gracefully handle करें
• Asynchronously process करें: Heavy operations से webhook responses को block न करें
• सब कुछ log करें: Debugging और audit purposes के लिए detailed logs बनाए रखें

​

User Experience

• स्पष्ट रूप से communicate करें: Customers को billing changes और timing के बारे में सूचित करें
• Confirmations दें: सफल plan changes के लिए email confirmations भेजें
• Edge cases handle करें: Trial periods, prorations और failed payments पर विचार करें
• UI तुरंत update करें: अपने application interface में plan changes reflect करें

​

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

// 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, {
    payment_method: { 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, {
    payment_method: { 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,
        payment_method={"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,
        payment_method={"type": "existing", "payment_method_id": payment_method_id},
    )
    
    # Monitor webhooks for payment.succeeded and subscription.active
    return response

​

अपने Implementation का Testing

​

Error Handling

​

HTTP Status Codes

​

Error Response Format

{
  "code": "INACTIVE_SUBSCRIPTION_PLAN_CHANGE_NOT_SUPPORTED",
  "message": "Changing plans is not supported for inactive subscriptions"
}

​

Next Steps

• Change Plan API review करें
• Credit-Based Billing explore करें
• subscription.on_hold के लिए alerts implement करें
• Webhook Integration Guide देखें