Subscription Upgrade Behavior - Immediate Billing & Proration Question

[wide silo]

Short answer: what you’re seeing is expected behavior.

1) PATCH /subscriptions/{id} behavior

• Changing product_id does NOT charge immediately
• It updates the subscription for the next billing cycle
• No proration, no immediate invoice is generated

That’s why:

• Customer paid $1.01 only
• Dashboard still shows old amount
• User gets upgraded benefits immediately (entitlement is on you to control)

---

2) Immediate upgrade with charge (correct flow)

Dodo currently does not auto-prorate on subscription update

To charge immediately, you must:

• Calculate the upgrade amount on your side
• Create a one-time payment / invoice for the difference
• After successful payment:
  • Then update the subscription to the new product

---

3) Prevent “free upgrades”

Right now your system:

• Grants PRO access immediately after PATCH ❌

Instead:

• Gate access:
  • Only upgrade entitlements after successful payment
• Treat PATCH as future plan change, not payment event

---

4) Webhook behavior

• Expected: webhook still shows old product_id
• Reason: change is scheduled, not applied immediately
• New product reflects:
  • At next billing cycle
  • Or after subscription renew event

---

5) Recommended upgrade pattern

• Step 1: User selects upgrade
• Step 2: Calculate price difference
• Step 3: Create one-time charge
• Step 4: On success:
  • Update subscription (PATCH)
  • Upgrade user access

---

Key takeaway

• PATCH subscription = schedule change
• It is not a billing action

---

If you want, I can sketch the exact API sequence for invoice + upgrade flow.

[jolly stone]

We have it like this

await this.client.subscriptions.changePlan(providerSubscriptionId, {
      product_id: productId,
      quantity: 1,
      proration_billing_mode: 'difference_immediately',
      on_payment_failure: 'prevent_change',
    });

User tries to upgrade, Dodo charges difference from already used payment method. If succesfull - we recieve webhook callback, if no - nothing

As I understand that*

What I know. If price increase - Dodo tries to charge, if decrease - Dodo gives credit to user (so on next charge user will have a discount)

But I have only upgrade (not downgrade) on my service so I don't have expertise at that

[wide silo]

This query has been marked as resolved by @worthy trench.