Create a subscription

Creates a new subscription for a customer based on an existing plan.

POST /subscriptions

Create a subscription

cURL

curl --request POST \
  --url https://api.razorpay.com/v1/subscriptions \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "plan_id": "plan_00000000000001",
  "total_count": 6,
  "customer_notify": 1,
  "start_at": 1580453311,
  "quantity": 1,
  "addons": [],
  "notes": {
    "notes_key_1": "Tea, Earl Grey, Hot",
    "notes_key_2": "Tea, Earl Grey… decaf."
  }
}
'

200

{
  "id": "sub_00000000000001",
  "entity": "subscription",
  "plan_id": "plan_00000000000001",
  "status": "created",
  "total_count": 6,
  "paid_count": 0,
  "remaining_count": 6,
  "customer_notify": 1,
  "start_at": 1580453311,
  "end_at": null,
  "charge_at": 1580453311,
  "created_at": 1580453311
}

Authorizations

Authorization · string · header · required

Use your Razorpay Key ID as the username and Key Secret as the password.

Body

application/json

plan_id · string · required

Unique identifier of the plan to subscribe to.

Example:

"plan_00000000000001"

total_count · integer · required

Total number of billing cycles for the subscription.

Example:

6

customer_notify · enum<integer>

Set to 1 to notify the customer via email and SMS, 0 to suppress notifications.

Available options: 0, 1

Example:

1

start_at · integer

Unix timestamp at which the subscription should start. Defaults to the current time if not provided.

Example:

1580453311

quantity · integer

Number of subscriptions to be charged on a single charge.

Example:

1

addons · object[]

List of add-ons to include with the subscription.

Example:

[]

notes · object

Key-value pairs for storing additional information. Maximum 15 pairs, each key up to 40 characters and value up to 256 characters.

Show child attributes

Example:

{
  "notes_key_1": "Tea, Earl Grey, Hot",
  "notes_key_2": "Tea, Earl Grey… decaf."
}

Response

200

application/json

Subscription created successfully.

A Razorpay Subscription object.

id · string

Unique identifier of the subscription.

Example:

"sub_00000000000001"

entity · string

Entity type. Always subscription.

Example:

"subscription"

plan_id · string

Unique identifier of the plan associated with this subscription.

Example:

"plan_00000000000001"

status · enum<string>

Current status of the subscription.

Available options: created, authenticated, active, pending, halted, cancelled, completed, expired

Example:

"created"

total_count · integer

Total number of billing cycles in the subscription.

Example:

6

paid_count · integer

Number of billing cycles that have been successfully paid.

Example:

0

remaining_count · integer

Number of billing cycles remaining.

Example:

6

customer_notify · enum<integer>

Indicates whether the customer should be notified. 1 for yes, 0 for no.

Available options: 0, 1

Example:

1

start_at · integer | null

Unix timestamp at which the subscription starts billing.

Example:

1580453311

end_at · integer | null

Unix timestamp at which the subscription ends.

Example:

null

charge_at · integer | null

Unix timestamp of the next scheduled charge.

Example:

1580453311

created_at · integer

Unix timestamp at which the subscription was created.

Example:

1580453311