Subscriptions: Recurring Billing for SaaS and Memberships

Razorpay Subscriptions lets you automate recurring charges for your customers. You define a plan with a billing amount and interval, link customers to that plan, and Razorpay handles authentication, scheduling, and retry logic for every charge that follows.

Key concepts

Plan

Defines the billing amount, currency, and interval (daily, weekly, monthly, or yearly). You create plans once and reuse them across multiple subscriptions.

Subscription

Links a specific customer to a plan for a set number of billing cycles. Charges occur automatically on each renewal date.

Addon

A one-time charge added to a subscription cycle — for example, a setup fee or a usage overage.

Supported intervals

daily, weekly, monthly, and yearly. Set the interval field to bill every N periods (for example, every 3 months).

Subscription states

A subscription moves through these states during its lifecycle:

created

The subscription has been created but the customer has not yet authenticated a payment method.

authenticated

The customer completed authentication (e.g., card mandate). Razorpay will charge on the scheduled start date.

active

The subscription is running. Charges occur automatically on each billing date.

pending

A charge attempt failed. Razorpay is retrying according to the configured retry schedule.

halted

Maximum retry attempts were reached without a successful charge. Customer action is required to resume.

cancelled

The subscription was stopped by you or the customer. No further charges will occur.

completed

All billing cycles defined by total_count have been charged successfully.

expired

The subscription passed its end date without completing all cycles.

Step 1: Create a plan

A plan defines what you charge and how often. Create a plan once and attach multiple subscriptions to it.

curl -X POST https://api.razorpay.com/v1/plans \
  -u rzp_test_YOUR_KEY_ID:YOUR_KEY_SECRET \
  -H "Content-Type: application/json" \
  -d '{
    "period": "monthly",
    "interval": 1,
    "item": {
      "name": "Pro Plan",
      "amount": 4999,
      "currency": "USD",
      "description": "Monthly Pro subscription"
    }
  }'

The amount is in the smallest currency unit. For USD, 4999 equals $49.99. The interval field multiplies the period — set "period": "monthly" with "interval": 3 to bill every quarter.

Step 2: Create a subscription

Link a customer to your plan by creating a subscription. Pass the plan_id returned from the previous step.

curl -X POST https://api.razorpay.com/v1/subscriptions \
  -u rzp_test_YOUR_KEY_ID:YOUR_KEY_SECRET \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "plan_00000000000001",
    "total_count": 12,
    "quantity": 1,
    "customer_notify": 1,
    "start_at": 1735689600,
    "addons": [],
    "notes": {
      "order_ref": "12345"
    }
  }'

The response contains a subscription_id (for example, sub_00000000000001). Pass this to the Razorpay Checkout in the next step so your customer can authenticate.

Step 3: Authenticate the customer on the frontend

Open Razorpay Checkout with the subscription_id instead of an order_id. The customer authenticates their payment method (for example, registers a card mandate), and recurring charges begin on the start_at date.

var options = {
  "key": "rzp_test_YOUR_KEY_ID",
  "subscription_id": "sub_00000000000001",
  "name": "Acme Corp",
  "description": "Monthly Pro Plan",
  "handler": function (response) {
    // Send these three values to your server for signature verification
    console.log(response.razorpay_payment_id);
    console.log(response.razorpay_subscription_id);
    console.log(response.razorpay_signature);
  }
};
var rzp = new Razorpay(options);
rzp.open();

Always verify the razorpay_signature on your server after the customer completes authentication. Skipping this step exposes you to fraudulent callbacks.

Step 4: Handle webhook events

Subscribe to subscription webhooks in your Dashboard under Account & Settings → Webhooks to keep your system in sync with billing events.

Event	Description
`subscription.activated`	The subscription moved to `active` status.
`subscription.charged`	A recurring charge succeeded.
`subscription.completed`	All billing cycles finished.
`subscription.cancelled`	The subscription was cancelled.
`subscription.halted`	Maximum payment retries reached; customer action required.

Use subscription.halted events to trigger dunning workflows — for example, sending the customer an email with a link to update their payment method.

Managing subscriptions

From the Razorpay Dashboard you can:

Pause and resume an active subscription
Cancel a subscription immediately or at the end of the current billing cycle
Add addons to a subscription for one-time charges in the next cycle
View charge history for each subscription

For programmatic control, use the Subscriptions API to cancel, pause, resume, or update a subscription without touching the Dashboard.

​Key concepts

Plan

Subscription

Addon

Supported intervals

​Subscription states

​Step 1: Create a plan

​Step 2: Create a subscription

​Step 3: Authenticate the customer on the frontend

​Step 4: Handle webhook events

​Managing subscriptions

Key concepts

Subscription states

Step 1: Create a plan

Step 2: Create a subscription

Step 3: Authenticate the customer on the frontend

Step 4: Handle webhook events

Managing subscriptions