API ReferenceIntegrationsKnowledge Base

Subscription Workflow

Below is a high level diagrammatic overview of the subscription life cycle at Razorpay:

No Need to Capture Payments:
There is no need to capture any subscription related payment. All payments related to subscription (except the authorization payment) are auto-captured. The authorization payment used to validate a customer's card is auto-refunded.

No Need to Create Customer:
There is no need to create a customer when using Razorpay Subscriptions. Razorpay automatically creates a customer when the authentication payment is made.

Plan#

A plan is the foundation on which a subscription is built. It acts as a reusable template and contains details of the goods or service offered along with the amount to be charged and the frequency at which the customer should be charged (billing cycle). Depending upon your business, you can create multiple plans with different billing cycles and pricing.

You must create a plan before you create a subscriptions via your checkout or via the Subscription Link feature.

International Currencies:
You can create a plan using any of our supported currencies..

You can create plans either via:

Subscription#

A subscription contains details like the plan, the start date, total number of billing cycles, free trial period (if any) and upfront amount to be collected.

Subscriptions can be created via

Trial Period#

Subscriptions allow you to provide a free trial period for your customers. You can create a fully-customized trial period that does not have to follow the typical 1-week or 1-month trial template.

To create a trial period for your customers, all you need to provide is a future start date when creating the subscription. The actual billing cycle automatically starts at the specified date, creating a free trial period.

The following is an example of a trial period:

  • Acme Corp. provides video streaming services and wants to offer a 1-month free trial.
  • The customer selects the plan on March 5th, 2019 and completes the authentication transaction.
  • During the authentication transaction, Acme Corp. creates a subscription with start date of April 5th, 2019.
  • Now, although the authentication transaction was done on March 5th, 2019, the customer’s card will be charged only from April 5th, 2019.
  • The customer or merchant can decide to cancel the subscription at any time before that. The time between March 5th, 2019 and April 5th, 2019 is treated as the trial period.

Note:

  • When creating a subscription or a subscription link using APIs, you can add a trial period by passing a future start date for the start-at parameter in the request.
  • When creating a subscription link via the Dashboard, you can add a trial period by setting the start date to any future date.

Upfront Amount#

There might be scenarios where you want to charge the customers an extra amount either at the start of the subscription or even before the subscription starts. For example, you might want to charge the customer a delivery fee or a setup fee. You can add this to the subscription as an upfront amount as part of the authentication transaction.

The following is an example where an upfront amount is charged by Acme Corp., a company that rents out furniture:

  1. Acme Corp. provides furniture on rent.
  2. Acme Corp. charges ₹1000 as security deposit. This needs to be collected before the furniture is delivered.
  3. While creating a subscription for the customer, Acme Corp. adds an upfront amount of ₹1000.
  4. When the customer subscribes to the service (during authentication transaction), ₹1000 is collected from the customer.

Note:

  • When creating a subscription or a subscription link using APIs, you can add an upfront amount by passing an addons key in the request.
  • When creating a subscription link via the Dashboard, you can add an upfront amount by selecting the I want to add an upfront amount check box and following the instructions on screen.

Authentication Transaction#

The authentication transaction amount is the first amount you charge on the customer's card. The authentication transaction can either be a token amount that is refunded to the customer or an upfront amount or the plan amount that is not refunded to the customer. Based on your business need, you can decide on the authentication transaction amount.

The table below explains what authentication amount is collected from customers for various combinations of start date and upfront amount.

Immediate Start Dates:
In the case of immediate start dates, the authentication transaction amount is not refunded and invoices are generated in all three scenarios.

Start Date

Upfront Amount

Authentication Amount

Immediate

Plan Amount

Future

₹5 (auto refunded)

Immediate

Yes

Upfront Amount + Plan Amount

Future

Yes

Upfront Amount

You can collect the authentication transaction in one of two ways:

Subscriptions via Checkout#

Note:
Integrating Razorpay Subscriptions to your checkout can only be done via APIs.

You can integrate the Razorpay Subscription service with your Razorpay Checkout Form on your website or application. Customers can select their desired subscription plan on your website or application and proceed to make the authentication payment via Razorpay's Checkout.

The subscriptions flow via Checkout is as follows:

  1. You create a plan.
  2. The customer selects the plan from your website or application.
  3. Once the customer selects a plan, a subscription is created in Razorpay and the subscription_id received in the response, is passed on to the Razorpay Checkout via the checkout options.
  4. On the Checkout form, the customer enters their card details and clicks Pay to make the payment.
  5. This acts as an authentication transaction and on a successful payment, a customer is created and linked to the subscription.
  6. Automated charges on the subscription are now made as per the schedule defined by you while creating the plan.

Read more: Integrate Razorpay Subscriptions on your checkout.

Subscriptions via Links#

You can create a custom subscription for a customer and send a subscription link to them. Customers click the link and are taken to a checkout page hosted by Razorpay where they make the authentication payment via Razorpay's checkout page. There is no need to host the link on your website or application.

The subscriptions flow via Subscription Links is as follows:

  1. You create a plan.
  2. You create a subscription link by:
    • Selecting a Plan.
    • Adding an upfront amount and add-ons, if any.
    • Adding customer details.
  3. The subscription link is sent to the customer via email and/or SMS.
  4. The customer click the link and is taken to the Razorpay Checkout form.
  5. The customer enters the card details and clicks Pay to make the payment. This acts as an authentication transaction and on a successful payment, a customer is created and linked to the subscription
  6. Automated charges on the subscription are now made as per the schedule defined by you while creating the plan.

Learn more about Subscription Links.

Add-ons#

Add-ons can be charged to your customer during the course of the subscription. Add-ons are typically charged for additional services taken by a customer during the billing cycle.

Add-ons can be created:

Example#

Acme Corp. is a merchant who provides DTH services. A customer requests a particular sports channels be added to his plan only for the next month. This would cost the customer ₹300 extra.

Acme Corp. creates an add-on for ₹300 and charges this to the customer in addition to the existing plan charges.

Update Subscriptions#

Razorpay allows you to update subscriptions after it has gone live. You can update the following parameters:

  • Plan linked to the subscription.
  • Quantity, that is the number of times the plan amount should be charged to the customer per billing cycle. For example, this would be the number of users for a software product.
  • Subscription Start Date for the updated subscription details. This can either be immediate or any future date. You can choose to update a subscription:
    • Immediately.
    • At the end of the current billing cycle.
  • Total count, that is the number of billing cycles. This determines the duration of the subscription.

Learn more about updating Subscriptions.

Cancel a Subscription#

You can cancel subscriptions yourself at anytime during its life cycle. Once a customer’s subscription is cancelled, no further invoices are generated on that subscription, nor are any charges attempted on the subscription. The subscription cannot be reactivated from this state.

Subscriptions can be cancelled either:

  • Immediately.
  • At the end of the current billing cycle.

A subscription can be cancelled at multiple stages such as authenticated, active or haulted.

If you want to refund money to the customer after cancelling a subscription, you can refund the corresponding amount on a previous payment on the subscription.

You can cancel a subscription:

Example#

  • If a customer is on a trial period, the subscription can be cancelled before the trial period ends. This ensures that the customer is not charged once the trial period ends.
  • If a subscription has moved into the halted state, you can either ask the customer to change their card or cancel the subscription, as per your business model.
  • A customer can ask to cancel the subscription before the end of the subscription period.

Invoice#

Razorpay automatically handles the invoicing for all subscriptions, providing an end-to-end solution. Invoice includes details like, plan, amount, date of charge including merchant details. Invoices are created for every charge made on the customer's card for recurring payments, including the authentication transaction.

  • An invoice is generated at the beginning of each billing cycle for the defined plan and amount.
  • A charge is attempted on the invoice. The invoice is in issued state on your Dashboard.
  • If the charge is successful
    • An email is sent to the customer.
    • The invoice is moved to paid state on your Dashboard.
    • The invoice.paid webhook is fired.

Start Date

Upfront Amount

Invoice sent

Immediate

x

Yes

Future

x

No (Reason: Auth transaction)

Immediate

Yes

Future

Yes

Refer to the Subscription Life Cycle section for more information about the various states a subscription can go through.