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#

  • All Razorpay APIs are authorized using Basic Authorization.
    • Generate API Keys from the Dashboard .
    • Add your API Keys in Postman. Selected the required API → Auth → Type = Basic Auth → Username = <Your_Key_ID>; Password = <Your_Key_secret>
  • 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
Data type string. 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.

Pause a Subscription#

Only subscriptions in the active state can be paused.

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

Use the below endpoint to pause a subscription.

/subscriptions/:sub_id/pause

Path Parameters#

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

Request Parameters#

pause_at optional
Data type string. It has to be now. That is, subscription is paused immediately.

Resume a Subscription#

Use the below endpoint to resume a subscription in the paused state.

/subscriptions/:sub_id/resume

Path Parameters#

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

Request Parameters#

resume_at optional
Data type string. It has to be now. That is, the subscription resumes immediately.

Fetch All Invoices for a Subscription#

Use the below endpoint to fetch all invoices for a subscription. Here, the count indicates the number of invoices generated for the subscription.

/invoices?subscription_id=:sub_id

Query Parameter#

subscription_id mandatory
string. The unique identifier that is 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 that has been issued for the subscription.

entity

string Here, it will be invoice.

receipt

string Here, it will be null.

invoice_number

string Here, it will be null.

customer_id

string The unique identifier associated with the customer to whom the subscription has been linked.

customer_details

Details of the customer.

id
string The unique identifier associated with the customer to whom the subscription has been linked.
name
string The customer's name. For example, Gaurav Kumar. Refer to the Customers document to learn how you can add or update this information.
email
string The customer's email address. For example, gaurav.kumar@example.com.
contact
string The customer's contact number. For example, +919876543210.
billing_address
string Details of the customer's billing address. Refer to the Customers document to learn how you can add or update this information.
shipping_address
string Details of the customer's shipping address. Refer to the Customers document to learn how you can add or update this information.
customer_name
string The customer's name. For example, Gaurav Kumar. Refer to the Customers document to learn how you can add or update this information.
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 that is linked to 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 Unique identifier linked to item billed in the invoice. For example, li_00000000000001.
item_id
string Here, it will be null.
name
string The item's name. For example, Monthly Plan.
description
string A brief description of the item. Here, it will be 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 are:

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

integer Timestamp, in Unix format, at which the invoice will expire. For example, 1593411509

issued_at

integer Timestamp, in Unix format, at which the invoice was issued to the customer. For example, 1593411209

paid_at

integer Timestamp, in Unix format, at which the payment was made. For example, 1593411325

cancelled_at

integer Timestamp, in Unix format, which the Invoice was canceled by you. For example, 1593411209

expired_at

integer Timestamp, in Unix format, 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 are:

  • pending
  • sent
email_status

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

  • pending
  • sent
date

integer Timestamp, in Unix format, 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 will be false.

amount

integer Amount to be paid using the Invoice. Must 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 will be 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 will be 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 Timestamp, in Unix format, that indicates when this invoice entity was created. For example, 1593411943.

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 along with the other options to the Razorpay Standard Manual checkout. 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.

Handler Function vs Callback URL:

  • Handler Function:
    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.
  • Callback URL:
    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.

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