API ReferenceIntegrationsKnowledge Base

Subscription Life Cycle

You can track a subscription through its various stages from creation to completion. While the life cycle for a subscription includes creation, authentication, active and then completion, you also have the option to cancel a subscription.

The stages that a subscription is likely to go through are illustrated here:

subscription life cycle

Subscription States#

During its life cycle, a subscription can go through the below states.

Created#

A subscription attains the created state once it is created.

Authenticated#

A subscription goes to the authenticated state when the customer completes the authentication transaction.

It moves to the active state right before the first charge attempt is made on the subscription.

Active#

A subscription goes to the active state when the billing cycle for the subscription starts.

Action on Razorpay:
When the subscription moves to the active state from the authenticated state, we attempt to charge the authorized card against the invoice amount.

Pending#

A subscription goes to the pending state when an auto-charge on a payment is unsuccessful. We continue to retry the payment while it is in this state. In the meanwhile, you can ask the customer to authenticate another card, if required.

After all the retry attempts have been exhausted, the subscription moves to the halted state.

Action on Razorpay:
When the subscription moves to the halted state from the pending state, invoices continue to be generated as per the billing cycles. However, no auto-charge is attempted. It is important to note that once the subscription moves back to the active state, the previous charges will not be re-attempted. Only future billing cycles are charged automatically.

Action on Razorpay:
When the subscription moves to the pending state from the active state, you are notified about the failed attempt via our webhooks. For subscriptions authenticated via cards, we continue to automatically process a retry without you having to take any action. We also send the customer an email notifying them about the failure. This email has a call-to-action from the customer to change the card that is associated with the subscription.

Action on merchant/customer:
To move the subscription back to the active state from the pending state, the customer needs to authenticate another card. This enables us to successfully perform a charge on it. You or the customer can also manually attempt a charge on the same card by attempting to charge any of the older unpaid invoices. If they go through successfully, the subscription moves back to the active state.

Halted#

The subscription goes to the halted state when the last auto-charge is unsuccessful and all retries are exhausted.

Note:
It is possible for the subscription to continue to remain in the halted state for more than one billing cycle. In such scenarios:

  • Invoices are generated for all billing cycles, but no auto-charge is attempted.
  • The customer needs to authenticate another card or you or the customer needs to manually attempt a charge on an older unpaid invoice. If the older invoice is successfully charged, the subscription will automatically move to the active state.

The subscription moves to the active state once the customer changes their card details and we are able to successfully perform a charge on it.

  • It can also move to the active state if a charge on an older invoice is attempted and it goes through successfully.
  • You can charge an older invoice from the Dashboard.

Note:
Once the subscription moves to the active state from the halted state, the previous charges are not re-attempted. Only future payments are charged automatically.

Cancelled#

When you cancel a subscription, it moves to the cancelled state. Once cancelled, a subscription cannot be restarted.

A subscription can be cancelled using the Cancel API or via the Dashboard.

Paused#

Only subscriptions in the active state can be paused.

You can pause a subscription.

  • You can pause a subscription either:

Note:
If you pause a subscription in the authenticated state, the subscription goes to the cancelled state.

Expired#

If the start_at time for the subscription has been set and the authentication transaction has not been done by the start_at time, the subscription moves to the expired state and cannot be used again.

Completed#

A subscription moves to the completed state when it reaches the end of its life cycle, as per the end_date set for the subscription.