Create a Plan

Create a plan with basic details such as amount and currency

POST /v1/plans

Curl

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/plans \
-H "Content-Type: application/json" \
-d '{
  "period": "weekly",
  "interval": 1,
  "item": {
    "name": "Test plan - Weekly",
    "amount": 69900,
    "currency": "MYR",
    "description": "Description for the test plan"
  },
  "notes": {
    "notes_key_1": "Tea, Earl Grey, Hot",
    "notes_key_2": "Tea, Earl Grey… decaf."
  }
}'

Success

{
  "id":"plan_00000000000001",
  "entity":"plan",
  "interval":1,
  "period":"weekly",
  "item":{
    "id":"item_00000000000001",
    "active":true,
    "name":"Test plan - Weekly",
    "description":"Description for the test plan - Weekly",
    "amount":69900,
    "unit_amount":69900,
    "currency":"MYR",
    "type":"plan",
    "unit":null,
    "tax_inclusive":false,
    "hsn_code":null,
    "sac_code":null,
    "tax_rate":null,
    "tax_id":null,
    "tax_group_id":null,
    "created_at":1580219935,
    "updated_at":1580219935
  },
  "notes":{
    "notes_key_1":"Tea, Earl Grey, Hot",
    "notes_key_2":"Tea, Earl Grey… decaf."
  },
  "created_at":1580219935
}

Use this endpoint to create a plan.

Curl

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/plans \
-H "Content-Type: application/json" \
-d '{
  "period": "weekly",
  "interval": 1,
  "item": {
    "name": "Test plan - Weekly",
    "amount": 69900,
    "currency": "MYR",
    "description": "Description for the test plan"
  },
  "notes": {
    "notes_key_1": "Tea, Earl Grey, Hot",
    "notes_key_2": "Tea, Earl Grey… decaf."
  }
}'

Success

{
  "id":"plan_00000000000001",
  "entity":"plan",
  "interval":1,
  "period":"weekly",
  "item":{
    "id":"item_00000000000001",
    "active":true,
    "name":"Test plan - Weekly",
    "description":"Description for the test plan - Weekly",
    "amount":69900,
    "unit_amount":69900,
    "currency":"MYR",
    "type":"plan",
    "unit":null,
    "tax_inclusive":false,
    "hsn_code":null,
    "sac_code":null,
    "tax_rate":null,
    "tax_id":null,
    "tax_group_id":null,
    "created_at":1580219935,
    "updated_at":1580219935
  },
  "notes":{
    "notes_key_1":"Tea, Earl Grey, Hot",
    "notes_key_2":"Tea, Earl Grey… decaf."
  },
  "created_at":1580219935
}

Request Parameters

period · string · required

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

• daily
• weekly
• monthly
• quarterly
• yearly

Handy Tips

You can create custom frequencies while creating a plan. For example, once in 3 weeks.

• For UPI, all undefined frequencies except daily, weekly, monthly, quarterly and yearly are considered as-presented.
• For domestic cards, all undefined frequencies except weekly, monthly and yearly are considered as-presented while registering the mandate with banks.
• For Emandate, all defined and undefined frequencies are considered as-presented while registering the mandate with banks.

interval · integer · required

This, combined with period, defines the frequency of the plan. If the billing cycle is 2 months, the value should be 2. For daily plans, the minimum value should be 7.

item · object

Details of the plan.

name · string · required

Name of the plan. For example, Test Plan.

amount · integer · required

Amount for the plan that is to be charged to the subscription in the next billing cycle. For example, 69900 translates to ₹699.

currency · string · required

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

description · string

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

notes · object

Notes you can enter of 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": "Monthly gym membership".

Response Parameters

id · string

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

entity · string

The entity being created. Here, it is plan.

interval · integer

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

period · string

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

• daily
• weekly
• monthly
• yearly

item · array

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. You can accept payment in any of the supported currencies.

description · string

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

notes · object

Notes you can enter of 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": "Monthly Gym".

created_at · integer

The Unix timestamp at which the plan was created.

Errors

Authentication failed

Code: 401

This error occurs when you use incorrect or invalid API Keys.

Solution: Use the right set of API keys.

`offer_id` is/are not required and should not be sent

Code: 400

This error occurs when you are passing offer_id parameter in the request body.

Solution: offer_id should not be passed in the request body.

The amount must be at least INR 1.00.

Code: 400

The amount specified is less than the minimum amount. Currency subunits, such as paise (in the case of INR), should always be greater than 100.

Solution: Enter an amount equal to or greater than the minimum amount, that is 100.

The period field is required.

Code: 400

The period field was not included in the request body.

Solution: Pass period as one of the supported values (for example daily, weekly, monthly, yearly).

Invalid argument for period passed.

Code: 400

The value passed for period is not one of the supported values.

Solution: Use one of the supported period values: daily, weekly, monthly, yearly.

The interval field is required.

Code: 400

The interval field was not included in the request body.

Solution: Pass interval as a positive integer specifying how many period units between each billing cycle.

The interval must be at least 1.

Code: 400

The interval value is 0 or negative.

Solution: Pass interval as an integer greater than or equal to 1.

The interval must be an integer.

Code: 400

A non-integer value was passed for interval.

Solution: Pass interval as an integer.

The item id field is required when item is not present.

Code: 400

Neither the item object nor an item_id was included in the request body.

Solution: Pass either an inline item object (with name, amount, currency) or an existing item_id.

The name field is required.

Code: 400

The item.name field was not included in the inline item object.

Solution: Always include item.name when passing an inline item.

The amount field is required when unit amount is not present.

Code: 400

Neither item.amount nor item.unit_amount was included in the request body.

Solution: Pass item.amount (in currency subunits) or item.unit_amount.

The amount must be valid integer between 0 and 4294967295.

Code: 400

A negative or out-of-range value was passed for item.amount.

Solution: Pass item.amount as a non-negative integer below 4294967295.

Currency provided is not supported.

Code: 400

The item.currency value is not one of the supported ISO currency codes.

Solution: Use a supported 3-letter ISO currency code (for example, INR).

{any extra field} is/are not required and should not be sent.

Code: 400

The request body contains fields that are not part of the Plans API schema.

Solution: Only include documented fields in the request body.