POST
/
subscriptions
curl --request POST \
  --url https://sandbox.cashfree.com/pg/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --header 'x-client-id: <api-key>' \
  --header 'x-client-secret: <api-key>' \
  --data '{
  "subscription_id": "Demo_Subscription",
  "customer_details": {
    "customer_name": "john",
    "customer_email": "john@dummy.com",
    "customer_phone": "9908730221",
    "customer_bank_account_number": "59108290701802",
    "customer_bank_ifsc": "HDFC0002614",
    "customer_bank_code": "HDFC",
    "customer_bank_account_type": "SAVINGS"
  },
  "plan_details": {
    "plan_name": "plan12345",
    "plan_type": "PERIODIC",
    "plan_amount": 10,
    "plan_max_amount": 100,
    "plan_max_cycles": 100,
    "plan_intervals": 2,
    "plan_interval_type": "WEEK",
    "plan_note": "Bi-weekly INR 10 plan"
  },
  "authorization_details": {
    "authorization_amount": 100,
    "authorization_amount_refund": true,
    "payment_methods": [
      "enach",
      "pnach",
      "upi",
      "card"
    ]
  },
  "subscription_meta": {
    "return_url": "https://wa.me/9512440440?text=Payment%20Successfull",
    "notification_channel": [
      "EMAIL",
      "SMS"
    ]
  },
  "subscription_expiry_time": "2024-01-14T23:00:08+05:30",
  "subscription_first_charge_time": "2024-01-10T23:00:08+05:30",
  "subscription_note": "testSUB",
  "subscription_tags": {
    "key1": "value1",
    "key2": "value2"
  },
  "subscription_payment_splits": [
    {
      "vendor_id": "vendor1",
      "amount": 100,
      "percentage": 10
    },
    {
      "vendor_id": "vendor2",
      "amount": 100,
      "percentage": 10
    }
  ]
}'
{
  "authorisation_details": {
    "authorization_amount": 1,
    "authorization_amount_refund": false,
    "authorization_reference": "",
    "authorization_time": "2022-06-14T23:47:52+05:30",
    "authorization_status": "INITIALIZED",
    "payment_id": "97877",
    "payment_method": "NPCI_SBC"
  },
  "cf_subscription_id": "4",
  "customer_details": {
    "customer_name": "Test Cust",
    "customer_email": "test@gmail.com",
    "customer_phone": "9900755700",
    "customer_bank_account_holder_name": "",
    "customer_bank_account_number": "",
    "customer_bank_ifsc": "",
    "customer_bank_code": "",
    "customer_bank_account_type": ""
  },
  "plan_details": {
    "plan_id": "od-20k-plan",
    "plan_name": "On demand plan for 20000 max amount",
    "plan_type": "ON_DEMAND",
    "plan_max_cycles": 0,
    "plan_recurring_amount": 0,
    "plan_max_amount": 20000,
    "plan_interval_type": "",
    "plan_intervals": 0,
    "plan_currency": "INR",
    "plan_note": "",
    "plan_status": ""
  },
  "subscription_expiry_time": "2100-01-01T05:29:59+05:30",
  "subscription_first_charge_time": "",
  "subscription_id": "SUB0028",
  "subscription_meta": {
    "return_url": ""
  },
  "subscription_note": "",
  "subscription_session_id": "subs_token_tc9JCN4MzUIJ",
  "subscription_payment_splits": null,
  "subscription_status": "INITIALIZED",
  "subscription_tags": null
}

Authorizations

​
x-client-id
string
header
required

Client app ID. You can find your app id in the merchant dashboard.

​
x-client-secret
string
header
required

Client secret key. You can find your secret in the merchant dashboard.

Headers

​
x-api-version
string
default:2025-01-01
required

API version to be used. Format is in YYYY-MM-DD

​
x-request-id
string

Request id for the API call. Can be used to resolve tech issues. Communicate this in your tech related queries to cashfree

​
x-idempotency-key
string

An idempotency key is a unique identifier you include with your API call. If the request fails or times out, you can safely retry it using the same key to avoid duplicate actions.

Body

application/json
Request body to create a subscription.

Request body to create a new subscription.

​
subscription_id
string
required

A unique ID for the subscription. It can include alphanumeric characters, underscore, dot, hyphen, and space. Maximum characters allowed is 250.

Required string length: 1 - 250
​
customer_details
object
required

Subscription customer details.

Example:
{
  "customer_name": "Test Cust",
  "customer_email": "test@gmail.com",
  "customer_phone": "9900755700",
  "customer_bank_account_holder_name": "",
  "customer_bank_account_number": "",
  "customer_bank_ifsc": "",
  "customer_bank_code": "",
  "customer_bank_account_type": ""
}
​
plan_details
object
required
​
authorization_details
object
​
subscription_meta
object
​
subscription_expiry_time
string

Expiry date for the subscription.

​
subscription_first_charge_time
string

Time at which the first charge will be made for the subscription after authorization. Applicable only for PERIODIC plans.

​
subscription_note
string

Note for the subscription.

​
subscription_tags
object

Tags for the subscription.

​
subscription_payment_splits
object[]

Payment splits for the subscription.

Subscription Payment Split Item

Response

200
application/json
Subscription Created

The response returned for Get, Create or Manage Subscription APIs.

​
authorisation_details
object

Details of the authorization done for the subscription. Returned in Get subscription and auth payments.

Example:
{
  "authorization_amount": 1,
  "authorization_amount_refund": false,
  "authorization_reference": "",
  "authorization_time": "2022-06-14T23:47:52+05:30",
  "authorization_status": "INITIALIZED",
  "payment_id": "97877",
  "payment_method": "NPCI_SBC"
}
​
cf_subscription_id
string

Cashfree subscription reference number

​
customer_details
object

Subscription customer details.

Example:
{
  "customer_name": "Test Cust",
  "customer_email": "test@gmail.com",
  "customer_phone": "9900755700",
  "customer_bank_account_holder_name": "",
  "customer_bank_account_number": "",
  "customer_bank_ifsc": "",
  "customer_bank_code": "",
  "customer_bank_account_type": ""
}
​
plan_details
object

The response returned for Get, Create and Manage Plan APIs

Example:
{
  "plan_currency": "INR",
  "plan_id": "144436-03471-JD_TEST",
  "plan_interval_type": "WEEK",
  "plan_intervals": 1,
  "plan_max_amount": 1,
  "plan_max_cycles": 4,
  "plan_name": "abscede",
  "plan_note": "lsdkdn",
  "plan_recurring_amount": 1,
  "plan_status": "ACTIVE",
  "plan_type": "PERIODIC"
}
​
subscription_expiry_time
string

Time at which the subscription will expire.

​
subscription_first_charge_time
string

Time at which the first charge will be made for the subscription. Applicable only for PERIODIC plans.

​
subscription_id
string

A unique ID passed by merchant for identifying the subscription.

​
subscription_meta
object

Subscription metadata.

​
subscription_note
string

Note for the subscription.

​
subscription_session_id
string

Subscription Session Id.

​
subscription_payment_splits
object[]

Payment splits for the subscription.

Subscription Payment Split Item

​
subscription_status
string

Status of the subscription.

​
subscription_tags
object

Tags for the subscription.

Was this page helpful?