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.

Before you start using these APIs, you need to authenticate them.

Subscription Entities#

Plan Entity#

You can create plans on-the-fly via the API and also fetch them as required. The plan entity has the following attributes:

id string
Plan ID which will be used to create subscriptions for the customers.
item.name string
Mandatory. Name of the plan.
item.description string
Optional. Description of the plan.
item.amount integer
Mandatory. Amount of the plan, that will be charged to all the customers subscribed to this plan, on a recurring basis.
item.currency string
Mandatory. Currently, only INR is supported.
interval integer
Mandatory. This, combined with period, defines the frequency. If the billing cycle is of 2 months, the value for this attribute would be 2. For daily plans, the minimum interval is 7.
period string
Mandatory. This, combined with interval, defines the frequency. If the billing cycle is of 2 months, the value for this attribute would be monthly. The values supported for this attribute currently are: weekly and monthly.
notes JSON object
Optional. Object consisting of key value pairs as notes. Refer here for more details.

Subscription Entity#

Subscriptions allow you to charge a customer's card on a recurring basis. A subscription ties a customer to a particular plan you've created. The following are the attributes of a subscription entity:

id string
Subscription ID
plan_id string
Mandatory. ID of the plan to which the customer is subscribing to.
customer_id string
ID of the customer who is subscribing to a plan. This will be populated automatically once the customer completes the first transaction via our checkout.
total_count integer
Mandatory. The number of billing cycles that the customer needs to be charged for. If the customer is buying a 1 year subscription, billed bi-monthly, this value should be 6.
customer_notify integer
Mandatory. This indicates whether the communication to the customer would be handled by you or by us. If it's set to 0, the communication to the customer would be handled by the merchant. If it's set to 1, we would take care of communicating any failures or charges to the customer.
start_at integer (timestamp)
Optional. This would be the start of the first billing cycle. If the start_at is not passed, the billing cycle for the customer starts immediately during the auth transaction. Otherwise, the billing cycle would start at the specified time.
quantity integer
Optional. The quantity of the plan to which the customer should be subscribed. For example, if the plan is Rs100/user/month, and the customer has 5 users, you should pass 5 as the quantity to have the customer charged Rs500 (5 x Rs100) monthly. By default, this value is set to 1, if nothing is passed.
notes object
Optional. Object consisting of key value pairs as notes. Read more here
addons Array of objects
Optional. This can be used to charge the customer a one time fees before the start of the subscription. This can include something like one-time delivery charges or a security deposit. More details about this can be found at upfront section
status string
Status of the subscription. Possible values: created, authenticated, active, pending, halted, cancelled, completed, expired. The explanations for these is provided in the Lifecycle section.
paid_count integer
This indicates the number of billing cycles that the customer has already been charged for.
current_start integer (timestamp)
This indicates the start time of the current billing cycle of the subscription.
current_end integer (timestamp)
This indicates the end time of the current billing cycle of the subscription.
ended_at integer (timestamp)
This will have the timestamp of the time when the subscription has completed its period or has been cancelled midway.
charge_at integer (timestamp)
This indicates the time when the next charge on the subscription will be made.
auth_attempts integer
The number of times that the charge for the current billing cycle has been attempted for, on the card.

Add-on Entity#

You can create add-ons to charge an extra amount for a particular billing cycle. Once you create an add-on, it gets attached to the next invoice that gets generated for the given subscription. Hence, it'll get applied to the next automated charge scheduled for the subscription.

The add-on entity has the following attributes:

id string
Addon ID
item.name string
Mandatory. Name of the add-on.
item.description string
Optional. Description of the add-on.
item.amount integer
Mandatory. Amount of the addon, that will be charged to the subscription for the next billing cycle.
item.currency string
Currently, only INR is supported.
quantity integer
Optional. This specifies the number of units of the item that you want to charge the customer for. By default, this is 1. The total amount is calculated as item.amount * quantity.
subscription_id string
The ID of the subscription to which the addon is being applied to.
invoice_id string
The ID of the invoice to which the addon has been applied to. This field gets populated only after the invoice is generated. Until then, it'll be null. The add-on will get added to the next invoice that gets generated after the addon has been created. Once the addon has been consumed by an invoice, it cannot be deleted.

Plans#

Create a Plan#

The following endpoint creates a plan:

/plans

Fetch a Plan#

The following endpoint fetches the plan with the given ID:

/plans/{planId}

Fetch All Plans#

The following endpoint fetches all plans:

/plans

Request Parameters#

from
Timestamp from when plans are to be fetched
to
Timestamp up till when plans are to be fetched
count
Count of plans to be fetched. Default value is 10. Maximum value is 100. This can be used for pagination, in combination with skip.
skip
Numbers of plans to be skipped. Default value is 0. This can be used for pagination, in combination with count.

Subscriptions#

Create a Subscription#

The following endpoint creates a new subscription on an existing customer:

/subscriptions

Fetch a Subscription#

The following endpoint fetches the subscription with the given ID:

/subscriptions/{subscriptionId}

Fetch All Subscriptions#

The following endpoint fetches all subscriptions of a plan:

/subscriptions

Request Params:#

plan_id
The plan ID of which you want to retrieve all the subscriptions. MANDATORY
from
Timestamp from when subscriptions are to be fetched
to
Timestamp up till when subscriptions are to be fetched
count
Count of subscriptions to be fetched. Default value is 10. Maximum value is 100. This can be used for pagination, in combination with skip.
skip
Numbers of subscriptions to be skipped. Default value is 0. This can be used for pagination, in combination with count.

Cancel a Subscription#

The following endpoint cancels a customer’s subscription. The subscription once cancelled, cannot be renewed or reactivated.

/subscriptions/{subscriptionId}/cancel

The subscription can either be cancelled immediately or at the end of the current billing cycle.

To cancel the subscription at the end of the current billing cycle, send the following body in the request.

Note:
The subscription status will move to cancelled when the actual cancellation happens. That is, if the subscription is being cancelled at cycle end, the subscription's status will move to cancelled at the end of the cycle. Webhook will also be fired at the end of the cycle.
If the subscription was created with customer_notify as 1, then a cancellation email will be sent to the customer when we receive a cancellation request from you, irrespective of immediate or future.

Add-ons#

Create an Add-on#

The following endpoint creates an add-on:

/subscriptions/{subscriptionId}/addons

Fetch an Add-on#

The following endpoint fetches the add-on with the given ID:

/addons/{addonId}

Delete an Add-on#

The following endpoint will allow you to delete an add-on if the add-on has not been associated with any invoice yet. Once the add-on has been associated to an invoice, it cannot be deleted.

https://api.razorpay.com/v1/addons/{addonId}