API ReferenceIntegrationsKnowledge Base

Subscriptions

You can create, fetch, query or cancel plans, subscriptions and addons using the Subscriptions API. These operations can also be performed on the Dashboard.

Postman Collection#

We have a Postman collection to make the integration quicker and easier. Click the Download Postman Collection button below to get started.

Instructions to use the Postman Collection#

  • APIs in the Postman collection are configured to inherit auth from parent.
  • Generate your API Keys and add them to the parent folder.
  • Some APIs in the collection require data specific to your account such as plan_id, sub_id and ao_id either in the request body or as a query parameter.
    • For example, the create subscription API requires you to add the plan_id (Plan ID) in the request body.
    • These parameters are enclosed in {} in the collection. For example, {plan_id}.
    • The API throws an error if these are incorrect or do not exist in your system.

Plans#

A plan is a foundation on which a subscription is built. It acts as a reusable template and contains details of the goods or services 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 subscription via your checkout or using the Subscription Link feature.

Create a Plan#

Use the below endpoint to create a plan.

/plans

Request Parameters#

period mandatory

Data type string. Used together with interval to define how often the customer should be charged. For example, if you want to create a monthly subscription, pass period monthly and interval 1. Possible values:

  • daily
  • weekly
  • monthly
  • yearly
interval mandatory

Data type integer. Used together with period to define how often the customer should be charged. For example, if you want to create a monthly subscription, pass period monthly and interval 1.

For daily plans, the minimum interval is 7.

item

Details of the plan.

name mandatory
Data type string. Name of the plan. For example, Test Plan.
amount mandatory
Data type integer. Amount for the plan that is to be charged to the subscription in the next billing cycle. For example, 69900 translates to ₹699.
currency mandatory
Data type string. Currency for the payment. For example, INR. You can accept payment in any of the supported currencies.
description optional
Data type string. Description for the plan. For example, Description for the test plan.
notes optional

Data type object. Notes you can enter for the contact for future reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. For example, "note_key": "Beam me up Scotty”.

Response Parameters#

id

Data type string. The unique identifier linked to a plan. For example, plan_00000000000001. This ID is used when creating a subscription for a customer.

entity

Data type string. The entity being created. Here it is plan.

interval

Data type integer. Used together with period to define how often the customer should be charged.

period

Data type string. Used together with interval to define how often the customer should be charged. Possible values:

  • daily
  • weekly
  • monthly
  • yearly
item

Details of the plan.

id
Data type string. The unique identifier linked to an item. For example, item_00000000000001.
name
Data type string. Name of the plan. For example, Test Plan.
amount
Data type integer. Amount for the plan. When you use this plan to create a subscription, the customer will be charged this amount periodically.
currency
Data type string. Currency for the payment. Defaults to INR. You can accept payment in any of the supported currencies.
description
Data type string. Description for the plan. For example, Description for the test plan.
notes

Data type object. Notes you can enter for the contact for future reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. For example, "note_key": "Beam me up Scotty”.

created_at

Data type integer. The Unix timestamp at which the plan was created.

Fetch all Plans#

Use the below endpoint to fetch all plans.

/plans

Query Parameters#

from
Data type integer. The Unix timestamp from when plans are to be fetched.
to
Data type integer.The Unix timestamp till when plans are to be fetched.
count
Data type integer. The number of plan to be fetched. Default value is 10. Maximum value is 100. This can be used for pagination, in combination with skip.
skip
Data type integer. The number of plans to be skipped. Default value is 0. This can be used for pagination, in combination with count.

Fetch a Plan by ID#

Use the below endpoint to fetch details of a plan by its ID.

/plans/:id

Path Parameter#

id mandatory
Data type string. The unique ID linked to a plan. For example, plan_00000000000001.

Subscriptions#

Subscriptions allow you to charge a customer's card periodically. A subscription ties a customer to a particular plan you have created. It contains details like the plan, the start date, total number of billing cycles, free trial period (if any) and upfront amount to be collected.

Create a Subscription#

Use the below endpoint to create a subscription.

/subscriptions

Request Parameters#

plan_id mandatory

Data type string. The unique identifier for a plan that should be linked to the subscription. For example, plan_00000000000001.

total_count mandatory

Data type integer. The number of billing cycles for which the customer should be charged. For example, if a customer is buying a 1-year subscription that should be billed on a bi-monthly basis, this value should be 6.

quantity optional

Data type integer. The number of times the customer should be charged the plan amount per invoice. For example, a customer subscribes to use a software. The charges are ₹100/month/license. The customer wants 5 licenses. You should pass 5 as the quantity in this case. The customer is charged ₹500 (5 x ₹100) monthly. By default, this value is set to 1.

start_at optional

Data type integer. The timestamp, in Unix format, for when the subscription should start. If not passed, the subscription starts immediately after the authorization payment. For example, 1581013800.

expire_by optional

Data type integer. The timestamp, in Unix format, till when the customer can make the authorization payment. For example, 1581013800. Do not pass any value if you do not want to set an expiry date.

customer_notify optional

Data type boolean. Indicates whether the communication to the customer would be handled by you or us.

  • 0: communication handled by you.
  • 1 (default): communication handled by Razorpay.
addons

Array that contains details of any upfront amount you want to collect as part of the authorization transaction.

item

Details of the upfront amount you want to charge your customer.

name optional
Date type string. A name for the upfront amount you want to charge the customer. For example, Delivery Fee.
amount optional
Data type integer. The upfront amount in the currency subunit you want to charge the customer. For example ,30000.
currency optional
Data type string. The currency in which you want to charge the customer. This has to match the plan currency. For example, INR. Defaults to INR.
notes optional

Data type object. Notes you can enter for the contact for future reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. For example, "note_key": "Beam me up Scotty”.

Response Parameters#

id
Data type string. The unique identifier that is linked to the subscription. For example, sub_00000000000001.
entity
Data type string. The entity being created. Here it will be subscription.
plan_id
Data type string. The unique identifier for a plan that is linked to the created subscription. For example, plan_00000000000001.
customer_id
Data type string. The unique identifier of the customer linked to the subscription. This is populated automatically once the customer completes the authorization transaction. For example, cust_00000000000001.
status
Data type string. Status of the subscription. Refer to the life cycle section for more details. Possible values:
  • created
  • authenticated
  • active
  • pending
  • halted
  • cancelled
  • completed
  • expired
current_start
Data type integer. Unix timestamp. The start time of the current billing cycle of the subscription. For example, 1581013800.
current_end
Data type integer. Unix timestamp. The end time of the current billing cycle of the subscription. For example, 1581013800.
ended_at
Data type integer. The timestamp, in Unix format, when the subscription was completed or was cancelled. For example, 1581013800.
quantity
Data type integer. The number of times the plan should be linked to the subscription. For example, if the plan is ₹100/user/month and the customer has 5 users, you should pass 5 as the quantity to have the customer charged ₹500 (5 x ₹100) monthly. By default, this value is set to 1.
notes
Data type object. Notes you can enter for the contact for future reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. For example, "note_key": "Beam me up Scotty”.
charge_at
Data type integer. Unix timestamp. This indicates when the next charge on the subscription should be made. For example, 1581013800.
start_at
Data type integer. The timestamp, in Unix format, that indicates when the subscription should start. If not passed, the subscription starts immediately after the authorization payment. For example, 1581013800.
end_at
Data type integer. The timestamp, in Unix format, when the subscription should end. For example, 1581013800.
auth_attempts
Data type integer. The number of times that the charge for the current billing cycle has been attempted on the card. For example, 2.
total_count
Data type integer. The number of billing cycles for which the customer should be charged. For example, 2.
paid_count
Data type integer. This indicates the number of billing cycles for which the customer has already been charged. For example, 2.
customer_notify
Data type boolean. Indicates whether the communication to the customer would be handled by you or us.
  • false: communication handled by you.
  • true: communication handled by Razorpay. Defaults to true.
created_at
Data type integer. The timestamp, in Unix format, when the subscription was created. For example, 1581013800.
expire_by
Data type integer. The timestamp, in Unix format, till when the customer can make the authorization payment. For example, 1581013800.
short_url
Data type string. URL that can be used to make the authorization payment. For example, https://rzp.io/i/PWtAiEo.
has_scheduled_changes
Data type boolean. Indicates if the subscription has any scheduled changes. Possible values:
  • true
  • false
schedule_change_at
Data type string. Represents when the subscription should be updated. Possible values:
  • now: Updates the subscription immediately. Default value.
  • cycle_end: Updates the subscription at the end of the current billing cycle.
remaining_count
Data type integer. This indicates the number of billing cycles remaining on the subscription. For example, 2.

Create a Subscription Link#

Use the below endpoint to create a new subscription link.

/subscriptions

Request Parameters#

plan_id mandatory

Data type string. The unique identifier for a plan that should be linked to the subscription. For example, plan_00000000000001.

total_count mandatory

Data type integer. The number of billing cycles for which the customer should be charged. For example, if a customer is buying a 1-year subscription that should be billed on a bi-monthly basis, this value should be 6.

quantity optional

Data type integer. The number of times the customer should be charged the plan amount per invoice. For example, a customer subscribes to use a software. The charges are ₹100/month/license. The customer wants 5 licenses. You should pass 5 as the quantity in this case. The customer is charged ₹500 (5 x ₹100) monthly. By default, this value is set to 1.

start_at optional

Data type integer. The timestamp, in Unix format, for when the subscription should start. If not passed, the subscription starts immediately after the authorization payment. For example, 1581013800.

expire_by optional

Data type integer. The timestamp, in Unix format, till when the customer can make the authorization payment. For example, 1581013800. Do not pass any value if you do not want to set an expiry date.

customer_notify optional

Data type boolean. Indicates whether the communication to the customer would be handled by you or us.

  • 0: communication handled by you.
  • 1 (default): communication handled by Razorpay.
addons

Array that contains details of any upfront amount you want to collect as part of the authorization transaction.

item

Details of the upfront amount you want to charge your customer.

name optional
Date type string. A name for the upfront amount you want to charge the customer. For example, Delivery Fee.
amount optional
Data type integer. The upfront amount in the currency subunit you want to charge the customer. For example ,30000.
currency optional
Data type string. The currency in which you want to charge the customer. This has to match the plan currency. For example, INR. Defaults to INR.
notes optional

Data type object. Notes you can enter for the contact for future reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. For example, "note_key": "Beam me up Scotty”.

notify_info

The customer's email and phone number to which notifications are to be sent. Use this array only if you have set the customer_notify parameter to 1. That is, Razorpay sends notifications to the customer.

notify_phone optional
Data type string. For example, 9123456789.
notify_email optional
Data type string. For example, gaurav.kumar@example.com.

Response Parameters#

id
Data type string. The unique identifier that is linked to the subscription. For example, sub_00000000000001.
entity
Data type string. The entity being created. Here it will be subscription.
plan_id
Data type string. The unique identifier for a plan that is linked to the created subscription. For example, plan_00000000000001.
customer_id
Data type string. The unique identifier of the customer linked to the subscription. This is populated automatically once the customer completes the authorization transaction. For example, cust_00000000000001.
status
Data type string. Status of the subscription. Refer to the life cycle section for more details. Possible values:
  • created
  • authenticated
  • active
  • pending
  • halted
  • cancelled
  • completed
  • expired
current_start
Data type integer. Unix timestamp. The start time of the current billing cycle of the subscription. For example, 1581013800.
current_end
Data type integer. Unix timestamp. The end time of the current billing cycle of the subscription. For example, 1581013800.
ended_at
Data type integer. The timestamp, in Unix format, when the subscription was completed or was cancelled. For example, 1581013800.
quantity
Data type integer. The number of times the plan should be linked to the subscription. For example, if the plan is ₹100/user/month and the customer has 5 users, you should pass 5 as the quantity to have the customer charged ₹500 (5 x ₹100) monthly. By default, this value is set to 1.
notes
Data type object. Notes you can enter for the contact for future reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. For example, "note_key": "Beam me up Scotty”.
charge_at
Data type integer. Unix timestamp. This indicates when the next charge on the subscription should be made. For example, 1581013800.
start_at
Data type integer. The timestamp, in Unix format, that indicates when the subscription should start. If not passed, the subscription starts immediately after the authorization payment. For example, 1581013800.
end_at
Data type integer. The timestamp, in Unix format, when the subscription should end. For example, 1581013800.
auth_attempts
Data type integer. The number of times that the charge for the current billing cycle has been attempted on the card. For example, 2.
total_count
Data type integer. The number of billing cycles for which the customer should be charged. For example, 2.
paid_count
Data type integer. This indicates the number of billing cycles for which the customer has already been charged. For example, 2.
customer_notify
Data type boolean. Indicates whether the communication to the customer would be handled by you or us.
  • false: communication handled by you.
  • true: communication handled by Razorpay. Defaults to true.
created_at
Data type integer. The timestamp, in Unix format, when the subscription was created. For example, 1581013800.
expire_by
Data type integer. The timestamp, in Unix format, till when the customer can make the authorization payment. For example, 1581013800.
short_url
Data type string. URL that can be used to make the authorization payment. For example, https://rzp.io/i/PWtAiEo.
has_scheduled_changes
Data type boolean. Indicates if the subscription has any scheduled changes. Possible values:
  • true
  • false
schedule_change_at
Data type string. Represents when the subscription should be updated. Possible values:
  • now: Updates the subscription immediately. Default value.
  • cycle_end: Updates the subscription at the end of the current billing cycle.
remaining_count
Data type integer. This indicates the number of billing cycles remaining on the subscription. For example, 2.

Fetch All Subscriptions#

Use the below endpoint to fetch all subscriptions.

/subscriptions

Query Parameters#

plan_id
The plan ID of which you want to retrieve all the subscriptions.
from
Data type integer. The Unix timestamp from when subscriptions are to be fetched.
to
Data type integer.The Unix timestamp till when subscriptions are to be fetched.
count
Data type integer. The number of subscriptions to be fetched. Default value is 10. Maximum value is 100. This can be used for pagination, in combination with skip.
skip
Data type integer. The number of subscriptions to be skipped. Default value is 0. This can be used for pagination, in combination with count.

Fetch Subscription by ID#

Use the below endpoint to fetch a subscription using the sub_id.

/subscriptions/:sub_id

Path Parameters#

id mandatory
Data type string. The unique ID linked to a subscription. For example, sub_00000000000001.

Cancel a Subscription#

Use the below endpoint to cancel a subscription.

/subscriptions/:sub_id/cancel

The subscription can either be cancelled immediately or at the end of the current billing cycle. Once cancelled, the subscription cannot be renewed or reactivated.

Status Change:

  • When you cancel a subscription immediately, the status changes to cancelled.
  • If you choose to cancel a subscription at the end of a billing cycle, its status does not change till the end of the current billing cycle. It remains in its current status till the end of the billing cycle. The subscription status changes to cancelled only at the end of the current billing cycle.

Path Parameters#

id mandatory
Data type string. The unique ID linked to a subscription. For example, sub_00000000000001.

Request Parameter#

cancel_at_cycle_endoptional
Data type boolean. Possible values:
  • 0 (default): Cancel the subscription immediately.
  • 1: Cancel the subscription at the end of the current billing cycle.

Update a Subscription#

Use the below endpoint to update a subscription.

/subscriptions/:sub_id

Path Parameters#

id mandatory
Data type string. The unique ID linked to a subscription. For example, sub_00000000000001.

Request Parameters#

plan_idoptional
Data type string. The new plan ID that should be linked to the subscription. For example, plan_00000000000001.
quantityoptional
Data type integer. The number of times the plan should be linked to the subscription. For example, if the plan is ₹100/user/month and the customer has 5 users, you should pass 5 as the quantity to have the customer charged ₹500 (5 x ₹100) monthly. By default, this value is set to 1.
remaining_countoptional
Data type integer. This parameter is used to update the total_count for a subscription. For example, let us consider a monthly subscription with 12 billing cycles. The subscription has been charged successfully 4 times and 3 more invoices have been issued, but have not been charged. The remaining count in such cases is 5. However, you can overwrite this value using this parameter.
start_atoptional
Data type integer. Unix timestamp. The new start date for the subscription.
schedule_change_atoptional
Data type string. Represents when the subscription should be updated.
  • now (default): Updates the subscription immediately.
  • cycle_end: Updates the subscription at the end of the current billing cycle.
customer_notifyoptional
Date type boolean. Represents who sends notifications to the customer. Possible values:
  • 1 (default): Notifications sent by Razorpay.
  • 0: Notifications sent by you.

Fetch Details of a Pending Update#

The following endpoint fetches details of a pending update. This happens when a subscription is updated using the end of cycle option for the schedule_change_at parameter.

/subscriptions/:sub_id/retrieve_scheduled_changes

For example, a subscription is to be charged on the 1st of every month. It was charged on January 01, 2020. On January 15, 2020, it was updated using the end of cycle option for the schedule_change_at parameter. In this case, the update goes live after the subscription is charged on February 01, 2020. Such updates are said to be scheduled updates and details of such updates can be fetched using this API.

Path Parameters#

id mandatory
Data type string. The unique ID linked to a subscription. For example, sub_00000000000001.

Cancel an Update#

The following endpoint cancels a pending update. This happens when a subscription is updated using the end of cycle option for the schedule_change_at parameter.

/subscriptions/:subscription_id/cancel_scheduled_changes

For example, a subscription is to be charged on the 1st of every month. It was charged on January 01, 2020. On January 15, 2020, it was updated using the end of cycle option for the schedule_change_at parameter. In this case, the update goes live after the subscription is charged on February 01, 2020. Such updates are said to be scheduled updates and can be cancelled using this API.

Note:
You can only cancel a pending update for a subscription. You cannot cancel an update once it is live.

Path Parameters#

id mandatory
Data type string. The unique ID linked to a subscription. For example, sub_00000000000001.

Checkout Integration#

Authentication Transaction#

After you create a subscription, permission to charge the customer's card at periodic intervals is required. For this, the customer has to complete an authorization transaction.

You can collect the authorization transaction by passing the subscription_id in the checkout options, while instantiating your Razorpay Standard Checkout.

The checkout options are similar to the normal payment. The only difference is that subscription_id is to be passed in the options, along with the other options. Refer to the Razorpay Standard Checkout documentation for a complete list of options.

Note:

  • You do not have to pass any order_id to the checkout.
  • As part of the authorization transaction, we create a customer using the details entered on the checkout and link it to the subscription.

Payment Verification#

Once the authorization transaction is successful, Razorpay returns the following data in the response:

  • razorpay_payment_id
  • razorpay_subscription_id
  • razorpay_signature

The razorpay_signature received needs to be verified on your backend server. To verify the signature, you need to fetch the subscription_id from your database, not the one from the checkout response, and use your <key_secret> to generate the signature.

To generate the signature, calculate an HMAC hex digest using SHA256 algorithm and these fields. The razorpay_payment_id and subscription_id fields are concatenated using the | (pipe) symbol.

Criteria for successful payment and authorization of a subscription:
You should only consider the payment as successful and subscription as authorized after the signature has been successfully verified.

Add-ons#

You can create add-ons to charge the customer an extra amount for a particular billing cycle. Once you create an add-on for a subscription, it is added to the next invoice that is generated. On the next scheduled charge, the customer is charged the add-on amount in addition to their regular subscription amount.

Create an Add-on#

Use the below endpoint to create an add-on.

/subscriptions/:id/addons

Path Parameter#

id mandatory
Data type string. The subscription ID to which the add-on is being added.

Request Parameters#

item

Details of the add-on you want to create.

name mandatory
Data type string. A name for the add-on. For example, Extra appala (papadum).
amount mandatory
Data type integer. The amount, in the currency subunit, you want to charge the customer for the add-on. For example, 30000.
currency mandatory
Data type string. The currency in which the customer should be charged for the add-on. For example, INR. You can charge the customer in any of the supported currencies.
description optional
Data type string. Description for the add-on. For example, 1 extra oil fried appala with meals.
quantity optional

Data type integer. This specifies the number of units of the add-on to be charged to the customer. For example, 2. Defaults to 1. The total amount is calculated as amount * quantity.

Response Parameters#

id

Data type string. The unique identifier linked to the created add-on. For example, ao_00000000000001.

item

Details of the add-on created.

id
Data type string. The unique identifier linked to the created item. For example, item_00000000000001.
active
Data type boolean. Here the value will be true.
name
Data type string. Name of the add-on. For example, Extra appala (papadum).
description
Data type string. Description for the add-on. For example, 1 extra oil fried appala with meals.
amount
Data type integer. Amount for the add-on that is to be charged to the subscription in the next billing cycle. For example, 30000.
currency
Data type string. The currency in which the customer should be charged for the add-on. For example, INR. Learn about the currencies we support.
created_at
Data type integer. The timestamp, in Unix format, when the item was created. For example, 1581597318.
quantity

Data type integer. This specifies the number of units of the add-on to be charged to the customer. For example, 2. The total amount is calculated as amount * quantity.

created_at

Data type integer. The timestamp, in Unix format, when the add-on was created. For example, 1581597318.

subscription_id

Data type string. The unique identifier of the subscription to which the add-on is being added. For example, sub_00000000000001.

invoice_id

Data type string. The add-on is added to the next invoice that is generated after the add-on is created. This field is populated only after the invoice is generated. Until then, it is null. Once the add-on is linked to an invoice, it cannot be deleted.

Fetch all Add-ons#

Use the below endpoint to fetch all add-ons.

/addons/

Query Parameters#

from
Data type integer. The timestamp, in Unix, from when add-ons are to be fetched.
to
Data type integer. The timestamp, in Unix, till when add-ons are to be fetched.
count
Data type integer. The number of add-ons to be fetched. Default value is 10. Maximum value is 100. This can be used for pagination, in combination with skip.
skip
Data type integer. The number of add-ons to be skipped. Default value is 0. This can be used for pagination, in combination with count.

Fetch an Add-on by ID#

Use the below endpoint to fetch an add-on by its ID.

/addons/:id

Path Parameter#

id mandatory
Data type string. The unique identifier linked to an add-on. For example, ao_00000000000001.

Delete an Add-on#

Use the below endpoint to delete an add-on. You receive a blank response if the add-on is successfully deleted.

/addons/:id

Note:
Once the add-on has been associated with an invoice, it cannot be deleted.

Path Parameter#

id mandatory
Data type string. The unique identifier linked to an add-on. For example, ao_00000000000001.

Available Webhook Events#

The table below lists the webhook events available for Subscriptions.

Note:
The payload for all these events would contain the subscription entity. They also contain a payment entity if a payment attempt was made before the event was triggered.

Webhook Event
Description
subscription.activated
Sent when the subscription moves to the active state either from the authenticated, pending or halted state. If a subscription moves to the active state from the pending or halted state, only the subsequent invoices that are generated are charged. Existing invoices that were already generated are not charged.
subscription.charged
Sent every time a successful charge is made on the subscription.
subscription.completed
Sent when all the invoices are generated for a subscription and the subscription moves to the completed state.
subscription.updated
Sent when a subscription is successfully updated. There is no state change when a subscription is updated.
subscription.pending
Sent when the subscription moves to the pending state. This happens when a charge on the card fails. We try to charge the card on a periodic basis while it is in the pending state. If the payment fails again, the webhook is triggered again.
subscription.halted
Sent when all retries have been exhausted and the subscription moves from the pending state to the halted state. The customer has to manually retry the charge or change the card linked to the subscription, for the subscription to move back to the active state.
subscription.cancelled
Sent when a subscription is cancelled and the subscription moves to the cancelled state.

Sample Payloads#

Refer to our Webhook document to learn how to set up webhooks.

Subscription Activated#

Subscription Charged#

Subscription Completed#

Subscription Updated#

Subscription Pending#

Subscription Halted#

Subscription Cancelled#