Subscription Upgrade & Downgrade Guide - Dodo Payments Documentation

Change Plan API

Full API docs for updating subscriptions.

Plan Change Preview

See charge amounts before changing plans.

Integration Guide

Step-by-step subscription setup.

What is a subscription upgrade or downgrade?

Changing plans lets you move a customer between subscription tiers or quantities. Use it to:

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

Plan changes can trigger an immediate charge depending on the proration mode you choose.

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

Before implementing subscription plan changes, ensure you have:

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

For detailed setup instructions, see our Integration Guide.

Step-by-Step Implementation Guide

Follow this comprehensive guide to implement subscription plan changes in your application:

Understand Plan Change Requirements

Before implementing, determine:

Which subscription products can be changed to which others
What proration mode fits your business model
How to handle failed plan changes gracefully
Which webhook events to track for state management

Test plan changes thoroughly in test mode before implementing in production.

Choose Your Proration Strategy

Select the billing approach that aligns with your business needs:

prorated_immediately
difference_immediately
full_immediately
do_not_bill

Best for: SaaS applications wanting to charge fairly for unused time

Calculates exact prorated amount based on remaining cycle time
Charges a prorated amount based on unused time remaining in the cycle
Provides transparent billing to customers

Implement the Change Plan API

Use the Change Plan API to modify subscription details:

string

required

The ID of the active subscription to modify.

string

required

The new product ID to change the subscription to.

integer

required

Number of units for the new plan (for seat-based products).

string

required

How to handle immediate billing: prorated_immediately, full_immediately, difference_immediately, or do_not_bill.

array

Optional addons for the new plan. Leaving this empty removes any existing addons.

string

Controls behavior when the plan change payment fails:

prevent_change: Keep subscription on current plan until payment succeeds
apply_change (default): Apply plan change immediately regardless of payment outcome

If not specified, uses the business-level default setting.

boolean

Collect the plan-change amount with a payment link instead of charging the subscription’s saved payment method. The customer pays on a hosted checkout page.Requires the business’s allow_plan_change_via_payment_link capability (Settings → Subscriptions → Collect Plan Change Payments by Payment Link), effective_at: immediately, and on_payment_failure: prevent_change. See Collecting Payment via a Checkout Link.Ignored by the preview route.

array

Optional stacked discount codes to apply to the new plan (max 20, applied in array order). Behavior depends on what you pass:

Not provided / null — existing discounts with preserve_on_plan_change=true are preserved if applicable to the new product.
[] (empty array) — removes all existing discounts from the subscription.
["CODE_A", "CODE_B", ...] — replaces any existing discounts with this stacked set.

string

deprecated

Deprecated — prefer discount_codes for new integrations. This field still works for backward compatibility, but cannot be combined with discount_codes in the same request.

string

default:"immediately"

When to apply the plan change:

immediately (default): Apply the plan change right away
next_billing_date: Schedule the change for the next billing date. The customer retains their current plan until the billing period ends.

Use next_billing_date for downgrades so customers keep their current plan benefits until the end of the billing period.

Handle Webhook Events

Set up webhook handling to track plan change outcomes:

subscription.active: Plan change successful, subscription updated
subscription.plan_changed: Subscription plan changed (upgrade/downgrade/addon update)
subscription.on_hold: Plan change charge failed, renewals stopped
payment.succeeded: Immediate charge for plan change succeeded
payment.failed: Immediate charge failed

Always verify webhook signatures and implement idempotent event processing.

Update Your Application State

Based on webhook events, update your application:

Grant/revoke features based on new plan
Update customer dashboard with new plan details
Send confirmation emails about plan changes
Log billing changes for audit purposes

Test and Monitor

Thoroughly test your implementation:

Test all proration modes with different scenarios
Verify webhook handling works correctly
Monitor plan change success rates
Set up alerts for failed plan changes

Your subscription plan change implementation is now ready for production use.

Preview Plan Changes

Before committing to a plan change, use the Preview API to show customers exactly what they’ll be charged:

Node.js SDK
Python SDK

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);
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)
print("New plan details:", preview.new_plan)

Use the preview API to build confirmation dialogs that show customers the exact amount they’ll be charged before they confirm a plan change.

Change Plan API

Use the Change Plan API to modify product, quantity, and proration behavior for an active subscription.

Quick start examples

Node.js SDK
Python SDK
Go SDK
HTTP

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 an empty body.
  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 an empty body.
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 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("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"
  }'

A successful plan change returns 200 OK immediately — before any charge has actually settled. What the body (ChangePlanResponse) contains depends on how the change was collected:

Case	`payment_id` / `payment_link` / `client_secret` / `expires_on`
Scheduled change (`effective_at: next_billing_date`)	All `null` — nothing is charged yet
`proration_billing_mode: do_not_bill`	All `null` — nothing to charge
Ordinary immediate charge (saved payment method)	All `null`
`collect_via_payment_link: true` (link issued)	All populated — checkout handles for the customer

In every case, this response is not a payment result — only that the request itself was accepted. It says nothing about whether an immediate charge actually succeeded.For an ordinary immediate charge, that outcome resolves off-session, right after the call.For a collect_via_payment_link request, it resolves later and asynchronously — the response only hands you a checkout link, the subscription stays on its current plan, and nothing is known about the outcome until the customer actually completes payment on that link.Either way, don’t infer the outcome from this response. Confirm it via webhook (payment.succeeded, payment.failed, subscription.plan_changed) or by re-reading the subscription with GET /subscriptions/{subscription_id} — see What Happens While the Link Is Unpaid for the payment-link case specifically.

If the immediate charge fails, the subscription may move to subscription.on_hold until payment succeeds.

Collecting Payment via a Checkout Link

By default, an immediate plan change charges the subscription’s saved payment method directly. Set collect_via_payment_link: true to send the customer to a hosted checkout page instead — useful when there’s no saved payment method you’re allowed to charge off-session, or when you want the customer to actively confirm the new price.

This is also what powers the Collect Plan Change Payments by Payment Link toggle in Settings → Subscriptions, which routes the built-in Customer Portal’s plan-change flow through checkout instead of the saved card.

Requirements

collect_via_payment_link: true only succeeds when all of the following hold — otherwise the request fails with 422:

The business has the allow_plan_change_via_payment_link capability enabled (Settings → Subscriptions → Collect Plan Change Payments by Payment Link).
effective_at is immediately (the default). A scheduled change (next_billing_date) never needs a checkout page, since nothing is charged until it applies.
The effective on_payment_failure resolves to prevent_change. You don’t have to send it explicitly — if your business-level default (see Business & Collection Defaults below) is already prevent_change, omitting the field satisfies this too. An explicit apply_change, or a resolved default of apply_change, fails with 422.

collect_via_payment_link isn’t limited to upgrades — it applies to any immediate change that results in a charge, downgrades included, as long as the requirements above are met.

If the change comes out to zero or a credit — proration_billing_mode: do_not_bill, or another mode that happens to net to nothing this cycle — there’s nothing to put on a checkout page. No payment link is issued, payment_link and friends come back null, and the change applies immediately, the same as it would without collect_via_payment_link. This isn’t a 422; the flag only takes effect when there’s a positive amount to collect. If you set collect_via_payment_link on plan changes generically rather than on clear-cut upgrades, call Preview Plan Change first and only request a link when the previewed amount is worth collecting.

Node.js SDK
Python SDK
HTTP

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

A successful request returns the checkout handles:

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

What Happens While the Link Is Unpaid

The subscription stays on its current plan — product_id, recurring_pre_tax_amount, and next_billing_date are all untouched until the link is paid.
A further change-plan request on the same subscription is rejected with 409 PendingPlanChangeExists while the link is pending. Cancel a scheduled change with DELETE /subscriptions/{subscription_id}/change-plan/scheduled if needed, but that endpoint doesn’t cancel a pending payment-link change — only a successful payment or expiry does.
The customer can retry a card on the same checkout session after a decline; a fresh change-plan call is not the retry path.
If the link is never paid, it stops working after expires_on — the subscription automatically becomes free to accept a new plan-change request shortly after.
If a scheduled change (next_billing_date) already existed and you replace it with cancel_scheduled_change_plan: true, the original schedule stays in place while the link is unpaid, and is only cancelled once the link is paid — in the same transaction that applies the new plan.

Once an immediate payment-link change is issued, every further plan-change request on that subscription — including the side-effect-free preview — is blocked until the link resolves. Don’t issue a link you don’t intend to have the customer pay right away.

Managing Addons

When changing subscription plans, you can also modify addons:

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

Addons are included in the proration calculation and will be charged according to the selected proration mode.

Applying Discount Codes

You can apply one or more stacked discount codes when changing subscription plans (max 20, applied in array order). This is useful for offering promotional pricing on upgrades or migrations.

Node.js SDK
Python SDK
HTTP

// 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"]
  }'

Discount behavior on plan change

`discount_codes` value	Behavior
Not provided / `null`	Existing discounts with `preserve_on_plan_change=true` are automatically preserved if applicable to the new product.
`[]` (empty array)	All existing discounts are removed from the subscription.
`["CODE_A", "CODE_B", ...]`	Replaces any existing discounts with this stacked set, validated and applied in array order.

The singular discount_code field on this endpoint is deprecated but still works for backward compatibility — existing integrations don’t need to change immediately. It cannot be combined with discount_codes in the same request. Migrate to the array form when convenient.

Use the Preview Plan Change API with discount_codes to show customers exactly how much they’ll save before confirming the plan change.

Proration modes

Choose how to bill the customer when changing plans:

`prorated_immediately`

Charges for the partial difference in the current cycle
If in trial, charges immediately and switches to the new plan now
Downgrade: may generate a prorated credit applied to future renewals

`full_immediately`

Charges the full amount of the new plan immediately
Ignores remaining time from the old plan

Credits created by downgrades using difference_immediately are subscription-scoped and distinct from Credit-Based Billing entitlements. They automatically apply to future renewals of the same subscription and are not transferable between subscriptions.

`difference_immediately`

Upgrade: immediately charge the price difference between old and new plans
Downgrade: add remaining value as internal credit to the subscription and auto-apply on renewals

`do_not_bill`

No charges or credits are calculated
Customer switches to the new plan immediately without any billing adjustment
Billing cycle remains unchanged
Best for courtesy migrations, free plan switches, or absorbing cost differences

Feature	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
Upgrade charge	Prorated difference for remaining days	Full price difference between plans	Full new plan price	No charge
Downgrade credit	Prorated credit for remaining days	Full price difference as credit	No credit	No credit
Billing cycle	Resets to today	Resets to today	Resets to today	Unchanged
Trial behavior	Ends trial, charges immediately	Ends trial, charges immediately	Ends trial, charges full amount	Ends trial, no charge
Best for	Fair time-based billing	Simple upgrade/downgrade math	Resetting billing cycles	Free migrations or courtesy switches
Complexity	Medium (day calculation)	Low (simple subtraction)	Low (full charge)	None

Example scenarios

Use these canonical numbers consistently:

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)

Upgrade: Basic ($30) → Pro ($80) with prorated_immediately

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

Downgrade: Pro ($80) → Starter ($20) with 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
→ 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 ($10.00 credit remaining)
→ Following renewal (Mar 15): $20.00 − $10.00 remaining credit = $10.00

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

Upgrade: Basic ($30) → Pro ($80) with difference_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'
})

Downgrade: Pro ($80) → Starter ($20) with 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'
})

Upgrade: Basic ($30) → Pro ($80) with full_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'
})

Mid-cycle upgrade with add-ons using prorated_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: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  addons: [
    { addon_id: 'addon_seats', quantity: 3 }
  ]
})

How each mode processes billing

Pick prorated_immediately for fair-time accounting; choose full_immediately to restart billing; use difference_immediately for simple upgrades and automatic credit on downgrades; or use do_not_bill to switch plans without any billing adjustment.

Handling Payment Failures

Control what happens when a plan change payment fails using the on_payment_failure parameter.

Payment Failure Modes

prevent_change (Recommended for critical upgrades)
apply_change (Default)

Behavior: Keep the subscription on its current plan until payment succeeds.

Plan change is marked as “pending”
Customer retains access to their current plan
Subscription moves to active state only after successful payment
Useful when you want to ensure payment before granting upgraded features

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

Behavior: Apply the plan change immediately regardless of payment outcome.

Plan change is applied even if payment fails
Customer gets immediate access to the new plan
Subscription may move to on_hold if payment fails
Good for non-critical upgrades or when you trust the customer

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

If not specified, the on_payment_failure parameter uses your business-level default setting configured in the dashboard.

When to Use Each Mode

Scenario	Recommended Mode	Reason
Upgrading to premium features	`prevent_change`	Ensure payment before granting access
Quantity increase (more seats)	`prevent_change`	Prevent usage without payment
Downgrading plans	`apply_change`	Customer is reducing spend
Trusted enterprise customers	`apply_change`	Lower risk of non-payment
Trial to paid conversion	`prevent_change`	Critical payment moment

Business & Collection Defaults

Instead of passing proration parameters on every plan change, you can set default upgrade & downgrade behavior once at the business level. These defaults apply to all customer-portal plan changes, and can be overridden per product collection. There are separate defaults for upgrades and downgrades:

Setting	Field (upgrade / downgrade)	Default (upgrade)	Default (downgrade)
When the new plan starts	`effective_at_on_upgrade` / `effective_at_on_downgrade`	`immediately`	`next_billing_date`
How the customer is charged	`proration_billing_mode_on_upgrade` / `proration_billing_mode_on_downgrade`	`difference_immediately`	`difference_immediately`
If the customer’s payment fails	`on_payment_failure`	`apply_change`	`apply_change`

Configure business defaults under Settings → Subscriptions, and collection overrides on each product collection. Each collection field is independent — leave it unset to inherit from the business default, or set a value to override it for that collection only.

Resolution order

For any given plan change, each setting resolves in this order:

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

A value passed explicitly to the Change Plan API always wins. The business and collection defaults only take effect when no explicit value is supplied — which is the case for all plan changes initiated from the customer portal.

A common setup: keep upgrades immediately + difference_immediately so customers pay the difference and get access right away, and keep downgrades on next_billing_date so customers keep their current plan until the cycle ends.

Handling webhooks

Track subscription state through webhooks to confirm plan changes and payments.

Event types to handle

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: payment for plan change or renewal succeeded
payment.failed: payment failed

We recommend driving business logic from subscription events and using payment events for confirmation and reconciliation.

Verify signatures and handle intents

Next.js Route Handler
Express.js

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

For detailed payload schemas, see the Subscription webhook payloads and Payment webhook payloads.

Best Practices

Follow these recommendations for reliable subscription plan changes:

Plan Change Strategy

Test thoroughly: Always test plan changes in test mode before production
Choose proration carefully: Select the proration mode that aligns with your business model
Handle failures gracefully: Implement proper error handling and retry logic
Monitor success rates: Track plan change success/failure rates and investigate issues

Webhook Implementation

Verify signatures: Always validate webhook signatures to ensure authenticity
Implement idempotency: Handle duplicate webhook events gracefully
Process asynchronously: Don’t block webhook responses with heavy operations
Log everything: Maintain detailed logs for debugging and audit purposes

User Experience

Communicate clearly: Inform customers about billing changes and timing
Provide confirmations: Send email confirmations for successful plan changes
Handle edge cases: Consider trial periods, prorations, and failed payments
Update UI immediately: Reflect plan changes in your application interface

Common Issues and Solutions

Resolve typical problems encountered during subscription plan changes:

Charge created but subscription not updated

Symptoms: API call succeeds but subscription remains on old planCommon causes:

Webhook processing failed or was delayed
Application state not updated after receiving webhooks
Database transaction issues during state update

Solutions:

Implement robust webhook handling with retry logic
Use idempotent operations for state updates
Add monitoring to detect and alert on missed webhook events
Verify webhook endpoint is accessible and responding correctly

Credits not applied after downgrade

Symptoms: Customer downgrades but doesn’t see credit balanceCommon causes:

Proration mode expectations: downgrades credit the full plan price difference with difference_immediately, while prorated_immediately creates a prorated credit based on remaining time in the cycle
Credits are subscription-specific and don’t transfer between subscriptions
Credit balance not visible in customer dashboard

Solutions:

Use difference_immediately for downgrades when you want automatic credits
Explain to customers that credits apply to future renewals of the same subscription
Implement customer portal to show credit balances
Check next invoice preview to see applied credits

Webhook signature verification fails

Symptoms: Webhook events rejected due to invalid signatureCommon causes:

Incorrect webhook secret key
Raw request body modified before signature verification
Wrong signature verification algorithm

Solutions:

Verify you’re using the correct DODO_WEBHOOK_SECRET from dashboard
Read raw request body before any JSON parsing middleware
Use the standard webhook verification library for your platform
Test webhook signature verification in development environment

Plan change fails with 422 error

Symptoms: API returns 422 Unprocessable Entity errorCommon causes:

Invalid subscription ID or product ID
Subscription not in active state
Missing required parameters
Product not available for plan changes

Solutions:

Verify subscription exists and is active
Check product ID is valid and available
Ensure all required parameters are provided
Review API documentation for parameter requirements

Immediate charge fails during plan change

Symptoms: Plan change initiated but immediate charge failsCommon causes:

Insufficient funds on customer’s payment method
Payment method expired or invalid
Bank declined the transaction
Fraud detection blocked the charge

Solutions:

Handle payment.failed webhook events appropriately
Notify customer to update payment method
Implement retry logic for temporary failures
Consider allowing plan changes with failed immediate charges

Subscription on hold after plan change

Symptoms: Plan change charge fails and subscription moves to on_hold stateWhat happens: When a plan change charge fails, the subscription is automatically placed in on_hold state. The subscription will not renew automatically until the payment method is updated.Solution: Update the payment method to reactivate the subscriptionTo reactivate a subscription from on_hold state after a failed plan change:

Update the payment method using the Update Payment Method API
Automatic charge creation: The API automatically creates a charge for remaining dues
Invoice generation: An invoice is generated for the charge
Payment processing: The payment is processed using the new payment method
Reactivation: Upon successful payment, the subscription is reactivated to active state

// 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

Webhook events to monitor:

subscription.on_hold: Subscription placed on hold (received when plan change charge fails)
payment.succeeded: Payment for remaining dues succeeded (after updating payment method)
subscription.active: Subscription reactivated after successful payment

Best practices:

Notify customers immediately when a plan change charge fails
Provide clear instructions on how to update their payment method
Monitor webhook events to track reactivation status
Consider implementing automatic retry logic for temporary payment failures

Update Payment Method API Reference

View the complete API documentation for updating payment methods and reactivating subscriptions.

Testing Your Implementation

Follow these steps to thoroughly test your subscription plan change implementation:

Set up test environment

Use test API keys and test products
Create test subscriptions with different plan types
Configure test webhook endpoint
Set up monitoring and logging

Test different proration modes

Test prorated_immediately with various billing cycle positions
Test difference_immediately for upgrades and downgrades
Test full_immediately to reset billing cycles
Test do_not_bill for no-charge/no-credit plan switches
Verify credit calculations are correct

Test webhook handling

Verify all relevant webhook events are received
Test webhook signature verification
Handle duplicate webhook events gracefully
Test webhook processing failure scenarios

Test error scenarios

Test with invalid subscription IDs
Test with expired payment methods
Test network failures and timeouts
Test with insufficient funds

Monitor in production

Set up alerts for failed plan changes
Monitor webhook processing times
Track plan change success rates
Review customer support tickets for plan change issues

Error Handling

Handle common API errors gracefully in your implementation:

HTTP Status Codes

200 OK

Plan change request processed successfully. The response body is empty, except for a successful collect_via_payment_link request, which returns checkout handles — see Collecting Payment via a Checkout Link. If on_payment_failure=prevent_change, the plan change stays pending until payment succeeds.

400 Bad Request

Invalid request parameters. Check that all required fields are provided and properly formatted.

401 Unauthorized

Invalid or missing API key. Verify your DODO_PAYMENTS_API_KEY is correct and has proper permissions.

404 Not Found

Subscription ID not found or doesn’t belong to your account.

409 Conflict

A pending plan change already exists for this subscription (PendingPlanChangeExists). For a scheduled change, cancel it with DELETE /subscriptions/{subscription_id}/change-plan/scheduled before submitting a new one. For a pending payment-link change, there’s no cancel endpoint — the subscription accepts a new plan-change request once the customer pays or the link expires.

422 Unprocessable Entity

The subscription is inactive or on-demand, or the request is not eligible for collect_via_payment_link — the business doesn’t have the capability enabled, effective_at isn’t immediately, or on_payment_failure isn’t prevent_change. See Requirements.

500 Internal Server Error

Server error occurred. Retry the request after a brief delay.

Error Response Format

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

Next steps

Review the Change Plan API
Explore Credit-Based Billing
Implement alerts for subscription.on_hold
Check out our Webhook Integration Guide

Change Plan API

Plan Change Preview

Integration Guide

​What is a subscription upgrade or downgrade?

​When to use plan changes

​Plan Change Flow

​Prerequisites

​Step-by-Step Implementation Guide

​Preview Plan Changes

​Change Plan API

​Quick start examples

​Collecting Payment via a Checkout Link

​Requirements

​What Happens While the Link Is Unpaid

​Managing Addons

​Applying Discount Codes

​Discount behavior on plan change

​Proration modes

​prorated_immediately

​full_immediately

​difference_immediately

​do_not_bill

​Example scenarios

​How each mode processes billing

​Handling Payment Failures

​Payment Failure Modes

​When to Use Each Mode

​Business & Collection Defaults

​Resolution order

​Handling webhooks

​Event types to handle

​Verify signatures and handle intents

​Best Practices

​Plan Change Strategy

​Webhook Implementation

​User Experience

​Common Issues and Solutions

Update Payment Method API Reference

​Testing Your Implementation

​Error Handling

​HTTP Status Codes

​Error Response Format

​Next steps

What is a subscription upgrade or downgrade?

When to use plan changes

Plan Change Flow

Prerequisites

Step-by-Step Implementation Guide

Preview Plan Changes

Change Plan API

Quick start examples

Collecting Payment via a Checkout Link

Requirements

What Happens While the Link Is Unpaid

Managing Addons

Applying Discount Codes

Discount behavior on plan change

Proration modes

`prorated_immediately`

`full_immediately`

`difference_immediately`

`do_not_bill`

Example scenarios

How each mode processes billing

Handling Payment Failures

Payment Failure Modes

When to Use Each Mode

Business & Collection Defaults

Resolution order

Handling webhooks

Event types to handle

Verify signatures and handle intents

Best Practices

Plan Change Strategy

Webhook Implementation

User Experience

Common Issues and Solutions

Testing Your Implementation

Error Handling

HTTP Status Codes

Error Response Format

Next steps