Subscription API's

The Subscription API enables complete management of recurring billing cycles. You can create subscriptions based on predefined plans, update subscription details mid-cycle, or handle billing logic specific to each customer. It supports operations like canceling, pausing, or resuming subscriptions, giving you flexibility to adapt to user preferences or business needs. This API is ideal for SaaS products, memberships, or any service requiring automatic periodic payments.

Additionally, you can generate Subscription Links, allowing customers to securely activate recurring payments through a self-service interface. The API also supports metadata updates, scheduling changes, and automated status checks. With these tools, you can streamline customer onboarding, improve billing reliability, and offer a seamless subscription experience.

End Points

Method Endpoint
POST /subscription/create
GET /subscription/get
GET /subscription/get?id=
PUT /subscription/update?id=
POST /subscriptionLink/create
POST /subscription/cancel?id=
POST /subscription/pause?id=
POST /subscription/resume?id=

Create a Subscription

The Create Subscription endpoint (POST /subscription/create) enables you to initiate a recurring payment plan for a customer. By linking it to a predefined plan and specifying parameters like billing cycles, quantity, and start time, you can manage subscriptions that automatically charge customers over a set period. Optional configurations include metadata, upfront charges, and customer notification settings.

Arguments
plan_id string (Required)

The unique identifier of the plan to be linked to the subscription. For example, plan_00000000000001.

total_count integer (Required)

The number of billing cycles for which the customer is charged. For instance, for a 1-year bi-monthly plan, this would be 6.

quantity integer

The number of units to be billed per invoice. For example, 5 licenses billed at ₹100 each would result in a charge of ₹500 per cycle. Default is 1.

start_at integer

Unix timestamp indicating when the subscription should begin. If omitted, it starts immediately after payment authorization.

expire_by integer

Unix timestamp specifying the latest time the customer can authorize payment. Default is 30 years. Leave empty to avoid setting an expiry date.

customer_notify boolean

Defines whether Razorpay or the business handles customer communication. true (default): Razorpay. false: Business handles it.

addons object

An array containing any upfront charges to be collected during authorization. For example, setup fees or initial costs.

offer_id string

ID of the offer linked to this subscription (if any). Example: offer_JHD834hjbxzhd38d.

notes object

Optional key-value pairs (max 15) for storing additional reference info. Example: "note_key": "Beam me up Scotty".

Request Example

const cloudlesspay = new CloudlessPayment({ key: "Your-API-key" });
const response = await cloudlesspay.subscription.create(data);

curl --request POST \
  --url https://www.cloudlesspayment.com/api/subscription/create \
  --header 'x-api-key: Your-API-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "plan_id": "plan_QteOopYOI2ziLo",
    "total_count": 6,
    "quantity": 1,
    "customer_notify": true
}'
Body Parameters

{
    "plan_id": "plan_QteOopYOI2ziLo",
    "total_count": 6,
    "quantity": 1,
    "customer_notify": true
}                                 
Response Example

 {
    "data": {
        "message": "Razorpay logic executed successfully",
        "result": {
            "action": "created",
            "data": {
                "auth_attempts": 0,
                "change_scheduled_at": null,
                "charge_at": null,
                "created_at": 1753161185,
                "current_end": null,
                "current_start": null,
                "customer_notify": true,
                "end_at": null,
                "ended_at": null,
                "entity": "subscription",
                "expire_by": null,
                "has_scheduled_changes": false,
                "id": "sub_Qvzf1WShV7cr0o",
                "notes": [],
                "paid_count": 0,
                "plan_id": "plan_QteOopYOI2ziLo",
                "quantity": 1,
                "remaining_count": 5,
                "short_url": "https://rzp.io/rzp/MBDTHVz0",
                "source": "api",
                "start_at": null,
                "status": "created",
                "total_count": 6
            },
            "vendor": "razorpay"
        },
        "vendor": "razorpay"
    },
    "status": "success"
}
                                        

Get All Subscription(s)

The Get All Subscriptions endpoint (GET /subscription/get) retrieves a list of all active, paused, or cancelled subscriptions created in the system. This endpoint is useful for managing and reviewing recurring billing activities across customers.

You can use this API to filter subscriptions based on parameters like status, plan ID, customer ID, or date range. It supports pagination for efficient browsing of large datasets and enables businesses to monitor subscription lifecycles, automate workflows, or perform analytics on recurring revenue.

Request Example

const cloudlesspay = new CloudlessPayment({ key: "Your-API-key" });
const response = await cloudlesspay.susbcription.fetchAll();

curl --request GET \
  --url https://www.cloudlesspayment.com/api/susbcription/get \
  --header 'x-api-key: Your-API-key'
Response Example

{
    "data": {
        "message": "Razorpay GET logic executed successfully",
        "result": {
            "action": "fetch",
            "data": {
                "count": 10,
                "entity": "collection",
                "items": [
                    {
                        "auth_attempts": 0,
                        "change_scheduled_at": null,
                        "charge_at": null,
                        "created_at": 1753161185,
                        "current_end": null,
                        "current_start": null,
                        "customer_id": null,
                        "customer_notify": true,
                        "end_at": null,
                        "ended_at": null,
                        "entity": "subscription",
                        "expire_by": null,
                        "has_scheduled_changes": false,
                        "id": "sub_Qvzf1WShV7cr0o",
                        "notes": [],
                        "offer_id": null,
                        "paid_count": 0,
                        "payment_method": null,
                        "plan_id": "plan_QteOopYOI2ziLo",
                        "quantity": 1,
                        "remaining_count": 5,
                        "short_url": "https://rzp.io/rzp/MBDTHVz0",
                        "source": "api",
                        "start_at": null,
                        "status": "created",
                        "total_count": 6
                    },
                    {
                        "auth_attempts": 0,
                        "change_scheduled_at": null,
                        "charge_at": null,
                        "created_at": 1752649646,
                        "current_end": null,
                        "current_start": null,
                        "customer_id": null,
                        "customer_notify": true,
                        "end_at": null,
                        "ended_at": null,
                        "entity": "subscription",
                        "expire_by": null,
                        "has_scheduled_changes": false,
                        "id": "sub_QteP6PYvakBkJY",
                        "notes": [],
                        "offer_id": null,
                        "paid_count": 0,
                        "payment_method": null,
                        "plan_id": "plan_QteOopYOI2ziLo",
                        "quantity": 1,
                        "remaining_count": 5,
                        "short_url": "https://rzp.io/rzp/XRkabO69",
                        "source": "api",
                        "start_at": null,
                        "status": "created",
                        "total_count": 6
                    },
                    {
                        "auth_attempts": 0,
                        "change_scheduled_at": null,
                        "charge_at": null,
                        "created_at": 1752649592,
                        "current_end": null,
                        "current_start": null,
                        "customer_id": null,
                        "customer_notify": true,
                        "end_at": null,
                        "ended_at": null,
                        "entity": "subscription",
                        "expire_by": null,
                        "has_scheduled_changes": false,
                        "id": "sub_QteO9YCMLAvBnY",
                        "notes": [],
                        "offer_id": null,
                        "paid_count": 0,
                        "payment_method": null,
                        "plan_id": "plan_Qtc31VtH9vUm72",
                        "quantity": 1,
                        "remaining_count": 5,
                        "short_url": "https://rzp.io/rzp/eSTZJOd",
                        "source": "api",
                        "start_at": null,
                        "status": "created",
                        "total_count": 6
                    },
                    {
                        "auth_attempts": 0,
                        "change_scheduled_at": null,
                        "charge_at": null,
                        "created_at": 1752647948,
                        "current_end": null,
                        "current_start": null,
                        "customer_id": null,
                        "customer_notify": true,
                        "end_at": null,
                        "ended_at": null,
                        "entity": "subscription",
                        "expire_by": null,
                        "has_scheduled_changes": false,
                        "id": "sub_QtdvDNlr03b0Dy",
                        "notes": [],
                        "offer_id": null,
                        "paid_count": 0,
                        "payment_method": null,
                        "plan_id": "plan_Qtc31VtH9vUm72",
                        "quantity": 1,
                        "remaining_count": 5,
                        "short_url": "https://rzp.io/rzp/AEZt47Z",
                        "source": "api",
                        "start_at": null,
                        "status": "created",
                        "total_count": 6
                    },
                    {
                        "auth_attempts": 0,
                        "change_scheduled_at": null,
                        "charge_at": null,
                        "created_at": 1752646757,
                        "current_end": null,
                        "current_start": null,
                        "customer_id": null,
                        "customer_notify": true,
                        "end_at": null,
                        "ended_at": null,
                        "entity": "subscription",
                        "expire_by": null,
                        "has_scheduled_changes": false,
                        "id": "sub_QtdaF18G1K1JI7",
                        "notes": {
                            "purpose": "demo"
                        },
                        "offer_id": null,
                        "paid_count": 0,
                        "payment_method": null,
                        "plan_id": "plan_Qtc31VtH9vUm72",
                        "quantity": 1,
                        "remaining_count": 5,
                        "short_url": "https://rzp.io/rzp/dWsf1jC",
                        "source": "api",
                        "start_at": null,
                        "status": "created",
                        "total_count": 6
                    },
                    {
                        "auth_attempts": 0,
                        "change_scheduled_at": null,
                        "charge_at": null,
                        "created_at": 1752646636,
                        "current_end": null,
                        "current_start": null,
                        "customer_id": null,
                        "customer_notify": true,
                        "end_at": null,
                        "ended_at": null,
                        "entity": "subscription",
                        "expire_by": null,
                        "has_scheduled_changes": false,
                        "id": "sub_QtdY6hFjizjQ7r",
                        "notes": [],
                        "offer_id": null,
                        "paid_count": 0,
                        "payment_method": null,
                        "plan_id": "plan_Qtc31VtH9vUm72",
                        "quantity": 1,
                        "remaining_count": 5,
                        "short_url": "https://rzp.io/rzp/3He9U7hK",
                        "source": "api",
                        "start_at": null,
                        "status": "created",
                        "total_count": 6
                    },
                    {
                        "auth_attempts": 0,
                        "change_scheduled_at": null,
                        "charge_at": null,
                        "created_at": 1752645509,
                        "current_end": null,
                        "current_start": null,
                        "customer_id": null,
                        "customer_notify": true,
                        "end_at": null,
                        "ended_at": null,
                        "entity": "subscription",
                        "expire_by": null,
                        "has_scheduled_changes": false,
                        "id": "sub_QtdEGkU1pLKxg6",
                        "notes": [],
                        "offer_id": null,
                        "paid_count": 0,
                        "payment_method": null,
                        "plan_id": "plan_Qtc31VtH9vUm72",
                        "quantity": 1,
                        "remaining_count": 5,
                        "short_url": "https://rzp.io/rzp/nbGQFkib",
                        "source": "api",
                        "start_at": null,
                        "status": "created",
                        "total_count": 6
                    },
                    {
                        "auth_attempts": 0,
                        "change_scheduled_at": null,
                        "charge_at": null,
                        "created_at": 1752644672,
                        "current_end": null,
                        "current_start": null,
                        "customer_id": null,
                        "customer_notify": true,
                        "end_at": null,
                        "ended_at": null,
                        "entity": "subscription",
                        "expire_by": null,
                        "has_scheduled_changes": false,
                        "id": "sub_QtczWiNGWQvzvz",
                        "notes": {
                            "note_key_1": "First note",
                            "note_key_2": "Second note"
                        },
                        "offer_id": null,
                        "paid_count": 0,
                        "payment_method": null,
                        "plan_id": "plan_Qtc31VtH9vUm72",
                        "quantity": 5,
                        "remaining_count": 5,
                        "short_url": "https://rzp.io/rzp/cSOUWVA",
                        "source": "api",
                        "start_at": null,
                        "status": "created",
                        "total_count": 6
                    },
                    {
                        "auth_attempts": 0,
                        "change_scheduled_at": null,
                        "charge_at": null,
                        "created_at": 1752644295,
                        "current_end": null,
                        "current_start": null,
                        "customer_id": null,
                        "customer_notify": true,
                        "end_at": null,
                        "ended_at": null,
                        "entity": "subscription",
                        "expire_by": null,
                        "has_scheduled_changes": false,
                        "id": "sub_QtcstIr7K8Rd4t",
                        "notes": [],
                        "offer_id": null,
                        "paid_count": 0,
                        "payment_method": null,
                        "plan_id": "plan_Q2gisxugbN079e",
                        "quantity": 1,
                        "remaining_count": 5,
                        "short_url": "https://rzp.io/rzp/KiUZb0K",
                        "source": "api",
                        "start_at": null,
                        "status": "created",
                        "total_count": 6
                    },
                    {
                        "auth_attempts": 0,
                        "change_scheduled_at": null,
                        "charge_at": null,
                        "created_at": 1752644019,
                        "current_end": null,
                        "current_start": null,
                        "customer_id": null,
                        "customer_notify": true,
                        "end_at": null,
                        "ended_at": null,
                        "entity": "subscription",
                        "expire_by": null,
                        "has_scheduled_changes": false,
                        "id": "sub_Qtco1zsts862jC",
                        "notes": [],
                        "offer_id": null,
                        "paid_count": 0,
                        "payment_method": null,
                        "plan_id": "plan_Qtc31VtH9vUm72",
                        "quantity": 1,
                        "remaining_count": 5,
                        "short_url": "https://rzp.io/rzp/Di27xQUU",
                        "source": "api",
                        "start_at": null,
                        "status": "created",
                        "total_count": 6
                    }
                ]
            },
            "vendor": "razorpay"
        },
        "vendor": "razorpay"
    },
    "status": "success"
}
                                        

Get Specific Subscription

The Get Subscription by ID endpoint (GET /subscription/get/<id>) retrieves the details of a specific subscription using its unique identifier. This is helpful for checking the subscription’s status, plan details, billing cycle, start and end dates, customer linkage, and any recent updates or pauses.

Arguments
id string (Required)

Unique identifier of the subscription to retrieve. This should be a valid subscription ID created previously.

Request Example

const cloudlesspay = new CloudlessPayment({ key: "Your-API-key" });
const response = await cloudlesspay.subscription.fetchById(subscriptionId);

curl --request GET \
  --url https://www.cloudlesspayment.com/api/subscription/get?id=subscriptionId \
  --header 'x-api-key: Your-API-key'
Response Example

{
    "data": {
        "message": "Razorpay GET logic executed successfully",
        "result": {
            "action": "fetch",
            "data": {
                "auth_attempts": 0,
                "change_scheduled_at": 1755282600,
                "charge_at": null,
                "created_at": 1752583288,
                "current_end": 1755282600,
                "current_start": 1752641413,
                "customer_id": null,
                "customer_notify": true,
                "end_at": 1765823400,
                "ended_at": 1752649534,
                "entity": "subscription",
                "expire_by": null,
                "has_scheduled_changes": true,
                "id": "sub_QtLYpH3rQMHg4m",
                "notes": [],
                "offer_id": null,
                "paid_count": 1,
                "payment_method": "card",
                "plan_id": "plan_Q2gisxugbN079e",
                "quantity": 6,
                "remaining_count": 5,
                "short_url": "https://rzp.io/rzp/hS2BFx5",
                "source": "api",
                "start_at": 1752644183,
                "status": "cancelled",
                "total_count": 6
            },
            "vendor": "razorpay"
        },
        "vendor": "razorpay"
    },
    "status": "success"
}
                                        

Update a Subscription

The Update Subscription endpoint (POST /subscription/update) allows you to modify the details of an existing subscription by specifying its ID along with the new data. You can update various fields such as the plan, quantity, remaining billing cycles, or even schedule the change for later.

This endpoint is useful when your customer upgrades or downgrades their subscription, changes user count, or applies a new offer. You must provide the subscription_id as a path or body parameter.

Arguments
id string (Required)

Unique identifier of the subscription. Example: sub_00000000000001.

plan_id string

ID of the new plan to associate with the subscription. Example: plan_00000000000001.

offer_id string

ID of the offer to apply. Example: offer_JHD834hjbxzhd38d.

quantity integer

Number of times the plan should be applied. Useful for per-user pricing (e.g., 5 users × ₹100 = ₹500).

remaining_count integer

Updates the number of remaining billing cycles. Useful for extending or limiting subscription duration.

start_at integer (Unix timestamp)

New start date of the subscription in Unix format (e.g., 1659398400).

schedule_change_at string

When the changes should apply. Options: now (default) or cycle_end.

customer_notify boolean

Whether Razorpay sends notifications to the customer. Default: true.

Request Example

const cloudlesspay = new CloudlessPayment({ key: "Your-API-key" });
const response = await cloudlesspay.subscription.updateById(subscriptionId, data);

curl --request PUT \
  --url https://www.cloudlesspayment.com/api/subscription/update?id=subscriptionId \
  --header 'x-api-key: Your-API-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "plan_id":"plan_Q2gisxugbN079e",
    "quantity":3
}'
Body Parameters

{
    "plan_id":"plan_Q2gisxugbN079e",
    "quantity":3
}
                                        
Response Example

{
  "id":"sub_00000000000002",
  "entity":"subscription",
  "plan_id":"plan_Q2gisxugbN079e",
  "customer_id":"cust_00000000000002",
  "status":"authenticated",
  "current_start":null,
  "current_end":null,
  "ended_at":null,
  "quantity":3,
  "notes":{
    "notes_key_1":"Tea, Earl Grey, Hot",
    "notes_key_2":"Tea, Earl Grey… decaf."
  },
  "charge_at":1580453311,
  "start_at":1580453311,
  "end_at":1606588200,
  "auth_attempts":0,
  "total_count":6,
  "paid_count":0,
  "customer_notify":true,
  "created_at":1580283807,
  "expire_by":1580626111,
  "short_url":"https://rzp.io/i/yeDkUKy",
  "has_scheduled_changes":false,
  "change_scheduled_at":null,
  "source": "api",
  "offer_id":"offer_JHD834hjbxzhd38d",
  "remaining_count":6
}
                                        

Resume a Subscription

The Resume Subscription endpoint (POST /subscription/{id}/resume) allows you to reactivate a subscription that was previously paused. This is useful when a customer decides to continue their subscription after a temporary pause.

You must pass the subscription ID in the URL path. To resume the subscription immediately, set the resume_at parameter to now. You can resume it at a specific future time by providing a valid ISO 8601 timestamp instead.

Path Parameter
id string (Required)

The unique identifier of the subscription to be resumed. For example: sub_00000000000001.

Request Parameters
resume_at string (Required)

Set to now to resume the subscription immediately, or provide a future ISO 8601 timestamp to resume at a specific time.

Request Example

const cloudlesspay = new CloudlessPayment({ key: "Your-API-key" });
const response = await cloudlesspay.subscription.subscriptionResumeById(subscriptionId,data);

curl --request POST \
  --url https://www.cloudlesspayment.com/api/subscription/resume?id=subscriptionId \
  --header 'x-api-key: Your-API-key'
Body Parameters

{
    "resume_at":"now"
}                       
Response Example

 {
    "data": {
        "message": "Razorpay logic executed successfully",
        "result": {
            "action": "resumed",
            "data": {
                "auth_attempts": 0,
                "change_scheduled_at": null,
                "charge_at": 1755282600,
                "created_at": 1752640953,
                "current_end": 1755282600,
                "current_start": 1752641290,
                "customer_id": null,
                "customer_notify": true,
                "end_at": 1810405800,
                "ended_at": null,
                "entity": "subscription",
                "expire_by": null,
                "has_scheduled_changes": false,
                "id": "sub_Qtbw3K9R8blSz8",
                "notes": [],
                "offer_id": null,
                "paid_count": 1,
                "payment_method": "card",
                "plan_id": "plan_Q2gisxugbN079e",
                "quantity": 45,
                "remaining_count": 22,
                "short_url": "https://rzp.io/rzp/yvWzrWCa",
                "source": "api",
                "start_at": 1752641290,
                "status": "active",
                "total_count": 23
            },
            "vendor": "razorpay"
        },
        "vendor": "razorpay"
    },
    "status": "success"
}
                                        

Pause a Subscription

The Pause Subscription endpoint (POST /subscription/{id}/pause) is used to temporarily suspend an active subscription. This feature is helpful when a customer wants to stop receiving services for a while without canceling the subscription entirely.

The pause can be configured based on how the billing cycle should behave during the pause—such as resuming after a specific number of billing cycles, or skipping charges entirely.

Path Parameter
id string (Required)

The unique identifier of the subscription to be paused. For example: sub_00000000000001.

Request Parameters
pause_at string (Required)

Set to now to pause the subscription immediately, or provide a future ISO 8601 timestamp.

Request Example

const cloudlesspay = new CloudlessPayment({ key: "Your-API-key" });
const response = await cloudlesspay.subscription.subscriptionPauseById(subscriptionId,data);

curl --request POST \
  --url https://www.cloudlesspayment.com/api/subscription/pause?id=subscriptionId \
  --header 'x-api-key: Your-API-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "pause_at":"now"
}'
Body Parameters

{
    "pause_at":"now"
}                    
Response Example

 {
    "data": {
        "message": "Razorpay logic executed successfully",
        "result": {
            "action": "paused",
            "data": {
                "auth_attempts": 0,
                "change_scheduled_at": null,
                "charge_at": null,
                "created_at": 1752640953,
                "current_end": 1755282600,
                "current_start": 1752641290,
                "customer_id": null,
                "customer_notify": true,
                "end_at": 1810405800,
                "ended_at": null,
                "entity": "subscription",
                "expire_by": null,
                "has_scheduled_changes": false,
                "id": "sub_Qtbw3K9R8blSz8",
                "notes": [],
                "offer_id": null,
                "paid_count": 1,
                "payment_method": "card",
                "plan_id": "plan_Q2gisxugbN079e",
                "quantity": 45,
                "remaining_count": 22,
                "short_url": "https://rzp.io/rzp/yvWzrWCa",
                "source": "api",
                "start_at": 1752641290,
                "status": "paused",
                "total_count": 23
            },
            "vendor": "razorpay"
        },
        "vendor": "razorpay"
    },
    "status": "success"
}
                                        

Cancel a Subscription

The Cancel Subscription endpoint (POST /subscription/{id}/cancel) allows you to cancel an active subscription. This is useful when a customer no longer wishes to continue the subscription.

You must pass the subscription ID in the URL path. You can choose to cancel the subscription immediately or at the end of the current billing cycle by setting the cancel_at_cycle_end parameter.

Path Parameter
id string (Required)

The unique identifier linked to a subscription. For example: sub_00000000000001.

Request Parameters
cancel_at_cycle_end boolean (Optional)

Use this parameter to specify when to cancel the subscription.
true: Cancel at the end of the current billing cycle.
false (default): Cancel the subscription immediately.

Request Example

const cloudlesspay = new CloudlessPayment({ key: "Your-API-key" });
const response = await cloudlesspay.subscription.cancelSubscription(subscriptionId,data);

curl --request POST \
  --url https://www.cloudlesspayment.com/api/subscription/cancel?id=subscriptionId \
  --header 'x-api-key: Your-API-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "cancel_at_cycle_end": True
}'
Body Parameters

{
    "cancel_at_cycle_end": True
}                    
Response Example

 {
    "data": {
        "message": "Razorpay logic executed successfully",
        "result": {
            "action": "cancelled",
            "data": {
                "auth_attempts": 0,
                "change_scheduled_at": null,
                "charge_at": 1755282600,
                "created_at": 1752640953,
                "current_end": 1755282600,
                "current_start": 1752641290,
                "customer_id": null,
                "customer_notify": true,
                "end_at": 1810405800,
                "ended_at": null,
                "entity": "subscription",
                "expire_by": null,
                "has_scheduled_changes": false,
                "id": "sub_Qtbw3K9R8blSz8",
                "notes": [],
                "offer_id": null,
                "paid_count": 1,
                "payment_method": "card",
                "plan_id": "plan_Q2gisxugbN079e",
                "quantity": 45,
                "remaining_count": 22,
                "short_url": "https://rzp.io/rzp/yvWzrWCa",
                "source": "api",
                "start_at": 1752641290,
                "status": "active",
                "total_count": 23
            },
            "vendor": "razorpay"
        },
        "vendor": "razorpay"
    },
    "status": "success"
}