Api

Payments

Subscriptions

Subscriptions

Create and fetch Plans and Subscriptions. Create and delete Add-ons using Razorpay Subscriptions APIs.

You can use Razorpay

Subscriptions

to set up and manage recurring payments. You can create, fetch, query or cancel plans, Subscriptions and add-ons using Subscriptions APIs. These operations can also be performed using the

Razorpay Dashboard

.

You can try out our APIs on the Razorpay Postman Public Workspace.

Run in Postman

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, 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 should create a plan using the Checkout or Subscription link before creating a Subscription.

Plan Entity

The plan entity has the following fields:

id

string The unique identifier linked to a plan. This is used when creating a Subscription for customers.

entity

string The entity being created. Here, it is plan.

interval

integer This, combined with period, defines the frequency. If the billing cycle is 2 months, the value should be 2.

Handy Tips

For daily plans, the minimum value should be 7.

period

string This, combined with interval, defines the frequency. Possible values:

  • daily
  • weekly
  • monthly
  • yearly

If the billing cycle is 2 months, the value should be monthly.

item

Details of the plan.

id

string The unique identifier linked to an item. For example, item_00000000000001.

name

string Name of the plan. For example, Test Plan.

amount

integer Amount for the plan. When you use this plan to create a Subscription, the customer will be charged this amount periodically.

currency

string Currency for the payment. Defaults to INR. You can accept payment in any of the

supported currencies

.

description

string Description of the plan. For example, Description of the test plan.

notes

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

integer The Unix timestamp at which the plan was created.

Create a Plan

The following endpoint creates a plan.

POST
/plans

Request Parameters

period

mandatory

string This, combined with interval, defines the frequency. Possible values:

  • daily
  • weekly
  • monthly
  • yearly

interval

mandatory

integer This, combined with period, defines the frequency. If the billing cycle is 2 months, the value should be 2.

Handy Tips

For daily plans, the minimum value should be 7.

item

Details of the plan.

name

mandatory

string Name of the plan. For example, Test Plan.

amount

mandatory

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

string Currency for the payment. For example, INR. You can accept payment in any of the

supported currencies

.

description

optional

string Description for the plan. For example, Description for the test plan.

notes

optional

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

Check the response parameters descriptions in the

Plan entity

parameters table.

Error Response Parameters

Given below is a list of possible errors you may face while creating a Subscription.

ErrorCauseSolution
offer_id is/are not required and should not be sentThis error occurs when you are passing offer_id parameter in the request body.offer_id should not be passed in the request body.

Fetch all Plans

The following endpoint fetches the details of all plans.

GET
/plans

Query Parameters

from

optional

integer The Unix timestamp from when plans are to be fetched.

to

optional

integer The Unix timestamp till when plans are to be fetched.

count

optional

integer The number of plans to be fetched. Default value is 10. Maximum value is 100. This can be used for pagination in combination with skip.

skip

optional

integer The number of plans to be skipped. Default value is 0. This can be used for pagination in combination with count.

Response Parameters

Check the response parameters descriptions in the

Plan entity

parameters table.

Fetch a Plan by ID

The following endpoint retrieves the details of a plan using its unique identifier.

GET
/plans/:id

Path Parameter

id

mandatory

string The unique identifier of the plan. For example, plan_00000000000001.

Response Parameters

Check the response parameters descriptions in the

Plan entity

parameters table.

Error Response Parameters

Given below is a list of possible errors you may face while fetching a plan by ID.

ErrorCauseSolution
an_id%7D is not a valid idThis error occurs when you are not passing the plan_id in the API endpoint to fetch a plan based on the ID.Ensure that you are passing the plan_id in the API endpoint.
For example, https://api.razorpay.com/v1/plans/plan_K8lVuxetc2OGR8 .

Subscriptions

You can use Subscriptions to charge a customer 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.

Subscriptions Entity

The Subscription entity has the following fields:

id

string The unique identifier linked to a Subscription.

entity

string The entity being created. Here, it is subscription.

plan_id

string The unique identifier of a plan that should be linked to the Subscription. For example, plan_00000000000001.

customer_id

string The unique identifer of the customer who is subscribing to a plan. This is populated automatically after the customer completes the authorisation transaction.

total_count

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

customer_notify

boolean Indicates whether the communication to the customer would be handled by you or us. Possible values:

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

start_at

integer The Unix timestamp, indicates from when the Subscription should start. If not passed, the Subscription starts immediately after the authorisation payment. For example, 1581013800.

quantity

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

notes

object Object consisting of key value pairs as notes.

addons

array of objects This can be used to charge the customer a one-time fee before the start of the Subscription. This can include something like a one-time delivery charge or a security deposit. Know more about

Add-ons

.

status

string Status of the Subscription. Possible values:

  • created
  • authenticated
  • active
  • pending
  • halted
  • cancelled
  • completed
  • expired

Know more about

Subscriptions States

.

paid_count

integer Indicates the number of billing cycles the customer has already been charged.

current_start

integer Indicates the start time of the current billing cycle of a Subscription.

current_end

integer Indicates the end time of the current billing cycle of a Subscription.

ended_at

integer The Unix timestamp of when the Subscription has completed its period or has been cancelled midway.

charge_at

integer The Unix timestamp of when the next charge on the Subscription should be made.

auth_attempts

integer The number of times the charge for the current billing cycle has been attempted on the card.

expire_by

integer The Unix timestamp that indicates till when the customer can make the authorisation payment. For example, 1581013800. Do not pass any value if you do not want to set an expiry date.

addons

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

item

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

name

string A name for the upfront amount you want to charge the customer. For example, Delivery Fee.

amount

integer The upfront amount in the currency subunit you want to charge the customer. For example ,30000.

currency

string The currency in which you want to charge the customer. This has to match the plan currency. For example, INR. Defaults to INR.

offer_id

string The unique identifier of the offer that is linked to the Subscription. You can obtain this from the Dashboard. For example, offer_JHD834hjbxzhd38d.

notes

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”.

short_url

string URL that can be used to make the authorisation payment. For example, https://rzp.io/i/PWtAiEo.

has_scheduled_changes

boolean Indicates if the Subscription has any scheduled changes. Possible values:

  • true
  • false

schedule_change_at

string Represents when the Subscription should be updated. Possible values:

  • now (default value): Updates the Subscription immediately.
  • cycle_end: Updates the Subscription at the end of the current billing cycle.

remaining_count

integer Indicates the number of billing cycles remaining on the Subscription. For example, 2.

Create a Subscription

Use the following endpoint to create a Subscription.

POST
/subscriptions

Request Parameters

plan_id

mandatory

string The unique identifier of a plan that should be linked to the Subscription. For example, plan_00000000000001.

total_count

mandatory

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

quantity

optional

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

start_at

optional

integer Unix timestamp that indicates from when the Subscription should start. If not passed, the Subscription starts immediately after the authorisation payment. For example, 1581013800.

expire_by

optional

integer Unix timestamp that indicates till when the customer can make the authorisation payment. For example, 1581013800. Do not pass any value if you do not want to set an expiry date.

customer_notify

optional

boolean Indicates whether the communication to the customer would be handled by you or us. Possible values:

  • 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 authorisation transaction.

item

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

name

optional

string A name for the upfront amount you want to charge the customer. For example, Delivery Fee.

amount

optional

integer The upfront amount in the currency subunit you want to charge the customer. For example ,30000.

currency

optional

string The currency in which you want to charge the customer. This has to match the plan currency. For example, INR. Defaults to INR.

offer_id

optional

string The unique identifier of the offer that is linked to the Subscription. You can obtain this from the Dashboard. For example, offer_JHD834hjbxzhd38d.

notes

optional

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

Check the response parameters descriptions in the

Subscription entity

parameters table.

Error Response Parameters

Given below is a list of possible errors you may face while creating a Subscription.

ErrorCauseSolution
The requested URL was not found on the server.This error occurs when the Subscriptions feature is not enabled.Ensure that the

Subscriptions feature

is enabled both in the test and live modes before creating a Subscription.
The id provided does not existThis error occurs when passing an incorrect plan_id .Ensure that you are passing the correct plan_id . The plan should be active and created using the same API key and Secret.
Offer Not FoundThis error occurs when you are linking an invalid/expired offer to a Subscription.Ensure that the Subscription offer created on the Dashboard is valid and has not expired.
Offer not applicable for this SubscriptionThis error occurs when you are linking/passing an offer_id to a Subscription on which the offer doesn't apply.Ensure that the plan amount is greater than the minimum amount set for the offer.

Create a Subscription Link

The following endpoint creates a Subscription link.

POST
/subscriptions

Request Parameters

plan_id

mandatory

string The unique identifier of a plan that should be linked to the Subscription. For example, plan_00000000000001.

total_count

mandatory

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

quantity

optional

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

start_at

optional

integer Unix timestamp that indicates from when the Subscription should start. If not passed, the Subscription starts immediately after the authorisation payment. For example, 1581013800.

expire_by

optional

integer Unix timestamp that indicates till when the customer can make the authorisation payment. For example, 1581013800. Do not pass any value if you do not want to set an expiry date.

customer_notify

optional

boolean Indicates whether the communication to the customer would be handled by you or us. Possible values:

  • 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 authorisation transaction.

item

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

name

optional

string A name for the upfront amount you want to charge the customer. For example, Delivery Fee.

amount

optional

integer The upfront amount in the currency subunit you want to charge the customer. For example ,30000.

currency

optional

string The currency in which you want to charge the customer. This has to match the plan currency. For example, INR. Defaults to INR.

offer_id

optional

string The unique identifier of the offer that is linked to the Subscription. You can obtain this from the Dashboard. For example, offer_JHD834hjbxzhd38d.

notes

optional

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

object 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.

Watch Out!

The customer details entered in the API request are only to notify the customer about the Subscription. The same will not be prefilled in the checkout as per the government guidelines.

notify_phone

optional

string The customer's phone number. For example, 911234567890.

notify_email

optional

string The customer's email. For example, abc.xyz@example.com.

You can perform various actions related to Subscriptions using the

Razorpay Dashboard

.

Response Parameters

Check the response parameters descriptions in the

Subscription entity

parameters table.

Error Response Parameters

Given below is a list of possible errors you may face while creating a Subscription link.

ErrorCauseSolution
Link expire by cannot be lesser than the current time.This error occurs when the time mentioned in the expire_by parameter has already passed. For example, if today's date is 12 December 2022, but the expiry date is mentioned as 10 December 2022.Ensure that the time passed in the expiry_by parameter occurs after the current time at the time of creating the Subscription link.

Fetch All Subscriptions

The following endpoint retrieves all the created Subscriptions.

GET
/subscriptions

Query Parameters

plan_id

optional

string The unique identifier of the plan for which you want to retrieve all the Subscriptions.

from

optional

integer The Unix timestamp from when Subscriptions are to be fetched.

to

optional

integer The Unix timestamp till when Subscriptions are to be fetched.

count

optional

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

optional

integer The number of Subscriptions to be skipped. Default value is 0. This can be used for pagination, in combination with count.

Response Parameters

Check the response parameters descriptions in the

Subscription entity

parameters table.

Fetch a Subscription by ID

The following endpoint retrieves a Subscription using the sub_id.

GET
/subscriptions/:sub_id

Path Parameters

id

mandatory

string The unique identifier linked to a Subscription. For example, sub_00000000000001.

Response Parameters

Check the response parameters descriptions in the

Subscription entity

parameters table.

Error Response Parameters

Given below is a list of possible errors you may face while fetching a Subscription by ID.

ErrorCauseSolution
ub_id%7D is not a valid idThis error occurs when you are not passing the right subscription_id in the API endpoint to fetch a plan based on the ID.Ensure that you are passing the right subscription_id in the API endpoint.
For example, https://api.razorpay.com/v1/subscriptions/sub_KA8rfWnXwyEw0j .

Cancel a Subscription

You can either cancel the Subscription immediately or at the end of the current billing cycle. Once cancelled, you cannot renew or reactivate it.

Status Change

  • When you cancel a Subscription, the status changes to cancelled.
  • If you choose to cancel a Subscription at the end of a billing cycle, its status changes to cancelled only at the end of the current billing cycle.

The following endpoint cancels a Subscription.

POST
/subscriptions/:sub_id/cancel

Path Parameter

id

mandatory

string The unique identifier linked to a Subscription. For example, sub_00000000000001.

Request Parameter

cancel_at_cycle_end

optional

boolean Use this parameter to cancel a Subscription at the end of a billing cycle. Possible values:

  • 0 (default): Cancel the subscription immediately.
  • 1: Cancel the subscription at the end of the current billing cycle.

Response Parameters

Check the response parameters descriptions in the

Subscription entity

parameters table.

Error Response Parameter

Given below is a list of possible errors you may face while cancelling a Subscription.

ErrorCauseSolution
Subscription is not cancellable in expired status.This error occurs when you are trying to cancel a Subscription which is in the expired state.You cannot cancel a Subscription in the expired state. Ensure that the Subscription is in the active or authenticated state to cancel.

Update a Subscription

The following endpoint updates a Subscription.

PATCH
/subscriptions/:sub_id

Path Parameter

id

mandatory

string The unique identifier linked to a Subscription. For example, sub_00000000000001.

Request Parameters

plan_id

optional

string The unique identifier of the new plan that should be linked to the Subscription. For example, plan_00000000000001.

offer_id

optional

string The unique identifier of the offer that should be linked to the Subscription. You can obtain this from the Dashboard. For example, offer_JHD834hjbxzhd38d.

quantity

optional

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_count

optional

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_at

optional

integer Unix timestamp. The new start date for the Subscription.

schedule_change_at

optional

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_notify

optional

boolean Represents who sends notifications to the customer. Possible values:

  • 1 (default): Notifications sent by Razorpay.
  • 0: Notifications sent by you.

Response Parameters

Check the response parameters descriptions in the

Subscription entity

parameters table.

Error Response Parameters

Given below is a list of possible errors you may face while updating a Subscription.

ErrorCauseSolution
Subscriptions cannot be updated when payment mode is UPIThis error occurs when you are trying to update a Subscription authorised via UPI.You cannot update a Subscription authorised via UPI mode or Emandate.
Can't update Subscription when Subscription is not in Authenticated or Active stateThis error occurs when you are trying to update a Subscription in the created state.Ensure that the Subscription status is either in the authenticated or active state.

Fetch Details of a Pending Update

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

GET
/subscriptions/:sub_id/retrieve_scheduled_changes

Example

A Subscription is to be charged on the 1st of every month. It was charged on January 01, 2021. On January 15, 2021, 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, 2021. Such updates are said to be scheduled updates and details of such updates can be fetched using this API.

Path Parameter

id

mandatory

string The unique identifier linked to a Subscription. For example, sub_00000000000001.

Response Parameters

Check the response parameters descriptions in the

Subscription entity

parameters table.

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.

POST
/subscriptions/:subscription_id/cancel_scheduled_changes

Example

A Subscription is to be charged on the 1st of every month. It was charged on January 01, 2021. On January 15, 2021, 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, 2021. Such updates are said to be scheduled updates and can be cancelled using this API.

Handy Tips

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

Path Parameter

id

mandatory

string The unique identifier linked to a Subscription. For example, sub_00000000000001.

Response Parameters

Check the response parameters descriptions in the

Subscription entity

parameters table.

Pause a Subscription

Use the following endpoint to pause a Subscription.

POST
/subscriptions/:sub_id/pause

Watch Out!

  • You can only pause a Subscriptions in the active state.
  • If you pause a Subscription in the authenticated state, it goes to the cancelled state.

Path Parameter

id

mandatory

string The unique identifier linked to a Subscription. For example, sub_00000000000001.

Request Parameter

pause_at

optional

string The value should be now to pause a Subscription immediately.

Response Parameters

Check the response parameters descriptions in the

Subscription entity

parameters table.

Resume a Subscription

Use the following endpoint to resume a Subscription.

POST
/subscriptions/:sub_id/resume

Path Parameter

id

mandatory

string The unique identifier linked to a Subscription. For example, sub_00000000000001.

Request Parameter

resume_at

optional

string The value should be now to resume a Subscription immediately.

Response Parameters

Check the response parameters descriptions in the

Subscription entity

parameters table.

Fetch all Invoices of a Subscription

The following endpoint retrieves all invoices of a Subscription. The count in the response indicates the number of invoices generated for a Subscription.

GET
/invoices?subscription_id=:sub_id

Query Parameter

subscription_id

mandatory

string The unique identifier linked to the Subscription. For example, sub_00000000000001.

Response Parameters

count

integer The number of invoices generated for the Subscription.

item

array List of invoices generated for the Subscription.

id

string The unique identifier of the invoice issued for the Subscription.

entity

string The entity being created. Here, it is invoice.

receipt

string Here, it is null.

invoice_number

string The invoice number. Here, it is null.

customer_id

string The unique identifier of the customer linked to the Subscription.

customer_details

Details of the customer.

id

string The unique identifier of the customer linked to the Subscription.

name

string The customer's name. For example, Gaurav Kumar. Know more

Customers API

.

email

string The customer's email address. For example, gaurav.kumar@example.com.

contact

string The customer's contact number. For example, +911234567890.

billing_address

string The customer's billing address.

shipping_address

string The customer's shipping address.

customer_name

string The customer's name. For example, Gaurav Kumar.

customer_email

string The customer's email address. For example, gaurav.kumar@example.com.

customer_contact

string The customer's contact number. For example, +919876543210.

order_id

string The unique identifier of the order associated with the invoice.

subscription_id

string The unique identifier of the Subscription. For example, sub_00000000000001.

line_items

array Details of the line item that is billed in the invoice. Number of arrays = number of line items billed in the invoice. For example, if the Subscription starts immediately and has an upfront fee attached to it, the number of line items = 2. One for the Subscription charge and one for the upfront fee.

id

string The unique identifier linked to the item billed in the invoice. For example, li_00000000000001.

item_id

string Here, it is null.

name

string The item's name. For example, Monthly Plan.

description

string A brief description of the item. Here, it is null.

amount

integer The item's price, in currency subunits. For example, 99900.

currency

string The currency for the amount charged for the item.

type

string The type of charge. Possible values:

  • plan
  • addon

quantity

integer The number of units of the item billed in the invoice. For example, 1.

payment_id

string Unique identifier of the payment made by the customer using this invoice. For example, pay_00000000000001.

status

string The status of the invoice. Possible values:

  • draft
  • issued
  • partially_paid
  • paid
  • expired
  • cancelled
  • deleted

expire_by

integer The Unix timestamp, indicates at which the invoice will expire. For example, 1593411509

issued_at

integer The Unix timestamp, indicates at which the invoice was issued to the customer. For example, 1593411209

paid_at

integer The Unix timestamp, indicates at which the payment was made. For example, 1593411325

cancelled_at

integer The Unix timestamp, indicates at which the invoice was canceled by you. For example, 1593411209

expired_at

integer The Unix timestamp, indicates at which the invoice has expired. For example, 1593411209

sms_status

string Indicates whether the SMS notification for the invoice was sent to the customer. Possible values:

  • pending
  • sent

email_status

boolean Indicates whether the email notification for the invoice was sent to the customer. Possible values:

  • pending
  • sent

date

integer The Unix timestamp, that indicates the date of the invoice.

terms

string Any terms to be included in the invoice. Here, it is null.

partial_payment

boolean Indicates whether the customer can make a partial payment on the invoice. Here, it is false.

amount

integer Amount to be paid using the invoice. This should be in the smallest unit of the currency. For example, 29995.

amount_paid

integer Amount paid by the customer using the invoice. For example, 29995.

amount_due

integer The remaining amount to be paid by the customer for the issued invoice.

currency

string The currency associated with the item.

description

string A brief description of the invoice. Here, it is null.

notes

object Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scotty”.

comment

string Any comments to be added in the invoice. Here, it is null.

short_url

string The short URL that is generated. This is the link that can be shared with customers to accept payments. Once canceled, no payments can be accepted using the link. For example, https://rzp.io/i/gb5827Hh.

view_less

boolean Indicates if the description of the invoice is collapsed. Here, it is true.

type

string Here, it is invoice.

created_at

integer The Unix timestamp, that indicates when this invoice entity was created. For example, 1593411943.

Link an Offer to a Subscription

You can link an existing

Offer

with a new Subscription using this API. Pass the offer_id: <offer_id> parameter in the request when creating a Subscription.

The following endpoint creates a Subscription link.

POST
/subscriptions

Request Parameters

plan_id

mandatory

string The unique identifier of a plan that should be linked to the Subscription. For example, plan_00000000000001.

total_count

mandatory

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

quantity

optional

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

start_at

optional

integer Unix timestamp that indicates from when the Subscription should start. If not passed, the Subscription starts immediately after the authorisation payment. For example, 1581013800.

expire_by

optional

integer Unix timestamp that indicates till when the customer can make the authorisation payment. For example, 1581013800. Do not pass any value if you do not want to set an expiry date.

customer_notify

optional

boolean Indicates whether the communication to the customer would be handled by you or us. Possible values:

  • 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 authorisation transaction.

item

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

name

optional

string A name for the upfront amount you want to charge the customer. For example, Delivery Fee.

amount

optional

integer The upfront amount in the currency subunit you want to charge the customer. For example ,30000.

currency

optional

string The currency in which you want to charge the customer. This has to match the plan currency. For example, INR. Defaults to INR.

offer_id

optional

string The unique identifier of the offer that is linked to the Subscription. You can obtain this from the Dashboard. For example, offer_JHD834hjbxzhd38d.

notes

optional

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

Check the response parameters descriptions in the

Subscription entity

parameters table.

Delete an Offer Linked to a Subscription

The following endpoint deletes an offer linked to a Subscription.

DELETE
/subscriptions/:sub_id/offer_id

Path Parameters

sub_id

mandatory

string The unique identifier of the Subscription from which you want to remove the offer. For example, sub_00000000000001.

offer_id

mandatory

string The unique identifier of the offer you want remove from the Subscription. For example, offer_JHD834hjbxzhd38d.

Response Parameters

Check the response parameters descriptions in the

Subscription entity

parameters table.

Checkout Integration

After you create a Subscription, you need the customer's permission to charge their card at periodic intervals. For this, the customer has to complete an authentication/authorisation transaction.

Authentication Transaction

You can collect the authorisation transaction by passing the subscription_id along with the other options to the

Razorpay Standard Manual Checkout

.

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

  • razorpay_payment_id
  • razorpay_subscription_id
  • razorpay_signature

Handy Tips

  • You do not have to pass any order_id to the checkout.

  • As part of the authorisation transaction, we create a customer using the details entered on the checkout and link it to the Subscription.

Handler FunctionCallback URL
When you use the handler function, the response object of the successful payment ( razorpay_payment_id , razorpay_order_id and razorpay_signature ) is submitted to the checkout form. You need to collect these and send them to your server.When you use a callback URL, the response object of the successful payment ( razorpay_payment_id , razorpay_order_id and razorpay_signature ) is submitted to the callback URL.

Error Response Parameters

Given below is a list of possible checkout errors you may face.

ErrorCauseSolution
Customer payment is not allowed for the Subscription at this stage.This error occurs when you are trying to make a payment for the next billing cycle during the current cycle.Users cannot pay for the next billing cycle during the current cycle.
Payment failed. Please contact the site adminThis error occurs when the amount of a plan exceeds the pricing plan configured to the business account for UPI.Ensure the minimum amount is greater than or equal to the configured pricing plan for the respective payment method, such as UPI recurring.
end_time must be between 946684800 and 4765046400This error occurs when the end date of the Subscription is beyond the acceptable limits or if the current start and end are null.Currently, you can only charge a Subscription for up to 10 years.
Oops! Something went wrong. Please contact the merchant for further assistance.
  • This error occurs when Flash Checkout is not enabled on the Razorpay Dashboard.
  • This error also occurs if the subscription_id is in the cancelled/expired state.
  • Ensure that flash checkout is enabled on the dashboard by navigating to Razorpay Dashboard → Settings → Configuration →

    Flash Checkout

    .
  • Ensure that the Subscription is in the authenticated or active state.

Payment Verification

This is a mandatory step that allows you to confirm the authenticity of the card details returned to the Checkout form for successful payments.

Handy Tips

You should consider the payment as successful and Subscription as authorised only after the signature has been successfully verified.

To verify the razorpay_signature returned to you by the Checkout form:

  1. Create a signature in your server using the following attributes:

    • subscription_id: Retrieve the subscription_id from your server. Do not use the razorpay_subscription_id returned by Checkout.
    • razorpay_payment_id: Returned by Checkout.
    • key_secret: Available in your server.
      The key_secret that was generated from the

      Dashboard

      .

  2. Use the SHA256 algorithm, the razorpay_payment_id and the subscription_id to construct a HMAC hex digest as shown below:

    generated_signature = hmac_sha256(razorpay_payment_id + "|" + subscription_id, secret);
    

      if (generated_signature == razorpay_signature) {
        payment is successful
      }

  3. If the signature you generate on your server matches the razorpay_signature returned to you by the Checkout form, the payment received is from an authentic source.