API ReferenceIntegrationsKnowledge Base

Update Subscriptions

Razorpay allows you to update the following details of a subscription even after it has gone live:

You can either update a subscription:

For example, a customer might want to update from a basic plan to an advanced plan that increases the frequency of your service or they might want to decrease the numbers of users for a software product. In such cases you can update the subscription for them, either immediately or at the end of the current billing cycle.

Subscriptions can be updated via APIs or via the Dashboard.

Notes:

  • You can only update subscriptions in the authenticated and active states. Subscriptions in the created, pending or halted state cannot be updated. There is no state change when a subscription is updated. Refer to the Subscription Life Cycle section for more details about the life cycle for a subscription.
  • You cannot update a subscription if the difference amount on updating a subscription (credit or refund) is less than the update quantity x the smallest currency subunit.

Update Subscription Immediately#

When you update a subscription immediately, you might need to do one of the following:

  • Charge the customer an extra amount.
  • Refund an amount to the customer.

If the remaining amount for the original subscription is the same as the amount to be charged for the updated subscription, no charge or refund needs to be done.

Charge a Customer Extra#

When upgrading a plan or increasing the number of users, you might have to charge a customer more. In such scenarios, Razorpay creates an invoice and charges the customer the difference amount.

If the charge is successful, the invoice is sent to the customer, if Razorpay is handling notifications to the customer.

You are notified via the subscription.updated webhook.

If the charge fails, the subscription is not updated.

Refund Money to a Customer#

When downgrading a plan or reducing the number of users, you might have to give the customer a refund. In such scenarios, Razorpay refunds the amount to the customer.

You are notified about this via the subscription.updated webhook.

Credit Note#

Refund to a customer is done using a Credit Note. Credit notes are similar to add-ons and help you in reconciliation.

Credit notes are not created against invoices, they are created against the total value of payments made by the customer. This means that, only one credit note is created even if refunds have to be made against multiple invoices. You can view credit notes on the Dashboard against the respective subscription.

Currently, these credit notes are refunded automatically.

A credit note can have two states:

  • created: The initial state of a credit note. A credit note stays in this state until a full refund is successfully issued to the customer.
  • refunded: The final state of a refund. A credit note moves to this state once the refund is successfully processed.

Example Scenario - Same Billing Frequency#

In the below examples, the updated subscription has the same billing frequency as the original subscription and the subscription is updated immediately.

Example 1#

In the below example, we are reducing the plan amount, but increasing the quantity. This change is done on the 1st day the subscription goes into effect. The updates take effect immediately.

Original Plan

Updated Plan

Plan amount

₹300

₹150

Quantity

1

2

Billing Frequency

Monthly

Monthly

Frequency at which the amount should be charged in days

30

30

Plan amount per day

(Plan amount x Quantity)/Frequency at which the amount should be charged in days = ₹10

(Plan amount x Quantity)/Frequency at which the amount should be charged in days = ₹10

Plan change day

1

Days to be charged

Plan change day - 1 = 0 days
(since customers are charged at the end of the day)

Remaining days (original plan) = 30

Remaining days

Frequency at which the amount should be charged in days - Days to be charged = 30

Amount to be charged

Plan amount per day x Days to be charged = ₹0

Plan amount per day x Days to be charged = ₹300

Remaining amount

Plan amount per day x Remaining days = ₹300

Amount to be charged/refunded

Amount to be charged (new plan) - Remaining Amount (original plan) = ₹0

In this example, you neither have to charge the customer an extra amount nor give them a refund.

Example 2#

In the below example, we are reducing the plan amount, but increasing the quantity. This change is done on the 15th day after the subscription went into effect. The updates take effect immediately.

Original Plan

Updated Plan

Plan amount

₹300

₹150

Quantity

1

2

Billing Frequency

Monthly

Monthly

Frequency at which the amount should be charged in days

30

30

Plan amount per day

(Plan amount x Quantity)/Frequency at which the amount should be charged in days = ₹10

(Plan amount x Quantity)/Frequency at which the amount should be charged in days = ₹10

Plan change day

15

Days to be charged

Plan change day - 1 = 14 days
(since customers are charged at the end of the day)

Remaining days (original plan) = 16

Remaining days

Frequency at which the amount should be charged in days - Days to be charged = 16

Amount to be charged

Plan amount per day x Days to be charged = ₹140

Plan amount per day x Days to be charged = ₹160

Remaining amount

Plan amount per day x Remaining days = ₹160

Amount to be charged/refunded

Amount to be charged (new plan) - Remaining Amount (original plan) = ₹0

In this example, you neither have to charge the customer an extra amount nor give them a refund.

Example 3#

In the below example, we are reducing the plan amount and the quantity. This change is done on the 6th day after the subscription went into effect. The updates take effect immediately.

Original Plan

Updated Plan

Plan amount

₹1000

₹400

Quantity

2

1

BillingFrequency

Daily

Daily

Frequency at which the amount should be charged in days

8

8

Plan amount per day

(Plan amount x Quantity)/Frequency at which the amount should be charged in days = ₹250

(Plan amount x Quantity)/Frequency at which the amount should be charged in days = ₹50

Plan change day

6

Days to be charged

Plan change day -1 = 5 days
(since customers are charged at the end of the day)

Remaining days (original plan) = 3

Remaining days

Frequency at which the amount should be charged in days - Days to be charged = 3

Amount to be charged

Plan amount per day x Days to be charged = ₹1250

Plan amount per day x Days to be charged = ₹150

Remaining amount

Plan amount per day x Remaining days = ₹750

Amount to be charged/refunded

Amount to be charged (new plan) - Remaining Amount (original plan) = -₹600 (refund)

In this example, you have to refund the customer ₹600.

Example Scenario - Different Billing Frequency#

In the below examples, the updated subscription does not have the same billing frequency as the original subscription and the subscription is updated immediately.

Example 1#

In the below example, we are increasing the plan amount, keeping the quantity the same and reducing the billing frequency. This change is done on the 1st day the subscription goes into effect. The updates take effect immediately.

Original Plan

Updated Plan

Plan amount

₹350

₹350

Quantity

1

1

Billing Frequency

Daily

Weekly

Frequency at which the amount should be charged in days

7

1

Plan amount per day

(Plan amount x Quantity)/Frequency at which the amount should be charged in days = ₹50

Plan change day

1

Days to be charged

Plan change day -1 = 0 days
(since customers are charged at the end of the day)

Remaining days

Frequency at which the amount should be charged in days - Days to be charged = 7

Amount to be charged

Plan amount per day x Days to be charged = ₹0

Plan amount x Quantity = ₹350

Remaining amount

Plan amount per day x Remaining days = ₹350

Amount to be charged/refunded

Amount to be charged (new plan) - Remaining Amount (original plan) = ₹0

In this example, you neither have to charge the customer an extra amount nor give them a refund.

Example 2#

In the below example, we are increasing the plan amount, keeping the quantity the same and reducing the billing frequency. This change is done on the 245th day the subscription goes into effect. The updates take effect immediately.

Note:
If the plans have different billing periods, the new plan is billed at the new interval, starting on the day of the change.

Original Plan

Updated Plan

Plan amount

₹10950

₹21900

Quantity

1

1

Billing Frequency

Yearly

Monthly

Frequency at which the amount should be charged in days

365

30

Plan amount per day

(Plan amount x Quantity)/Frequency at which the amount should be charged in days = ₹30

Plan change day

245

Days to be charged

Plan change day -1 = 244 days
(since customers are charged at the end of the day)

Remaining days (original plan) = 121

Remaining days

Frequency at which the amount should be charged in days - Days to be charged = 121

Amount to be charged

Plan amount per day x Days to be charged = ₹7320

Plan amount x Quantity = ₹21900

Remaining amount

Plan amount per day x Remaining days = ₹3630

Amount to be charged/refunded

Amount to be charged (new plan) - Remaining Amount (original plan) = ₹18300 (charge)

In this example, you have to charge the customer ₹18270 extra.

Example 3#

In the below example, we are increasing the plan amount, increasing the quantity and increasing the billing frequency. This change is done on the 27th day the subscription goes into effect. The updates take effect immediately.

Note:
If the plans have different billing periods, the new plan is billed at the new interval, starting on the day of the change.

Original Plan

New Plan

Plan amount

₹300

₹900

Quantity

1

2

Billing Frequency

Monthly

Quarterly

Frequency at which the amount should be charged in days

30

90

Plan amount per day

(Plan amount x Quantity)/Frequency at which the amount should be charged in days = ₹10

Plan change day

27

Days to be charged

Plan change day -1 = 26 days
(since customers are charged at the end of the day)

Remaining days

Frequency at which the amount should be charged in days - Days to be charged = 4

90 days

Amount to be charged

Plan amount per day x Days to be charged = ₹260

Plan amount x Quantity = ₹1800

Remaining amount

Plan amount per day x Remaining days = ₹40

Amount to be charged/refunded

Amount to be charged (new plan) - Remaining Amount (original plan) = ₹1760 (charge)

In this example, you have to charge the customer ₹1760 extra.