Create Subscription

Use this API to create a new subscription.

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 key 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<UUID>

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 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.

Show child attributes

Example:

{
  "customer_name": "Test Cust",
  "customer_email": "[e-mail]",
  "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

Show child attributes

authorization_details · object

Show child attributes

subscription_meta · object

Show child attributes

subscription_expiry_time · string

Expiry date for the subscription. Cashfree stores timestamps in IST, but you can provide them in a valid ISO 8601 time format.

For IST this 2025-06-01T10:20:12+05:30 translates to 2025-06-01 10:20:12

For UTC this 2025-06-01T10:20:12Z translates to 2025-06-01 15:50:12+05:30.

subscription_first_charge_time · string

Time at which the first charge will be made for the subscription after authorization. Applicable only for PERIODIC plans. Cashfree stores timestamps in IST, but you can provide them in a valid ISO 8601 time format.

For IST this 2025-06-01T10:20:12+05:30 translates to 2025-06-01 10:20:12

For UTC this 2025-06-01T10:20:12Z translates to 2025-06-01 15:50:12+05:30.

subscription_note · string

Note for the subscription.

subscription_tags · object | null

Custom Tags in the form of {"key":"value"} which can be passed for a subscription. A maximum of 10 tags can be added

Show child attributes

Example:

{
  "psp_note": "Monthly subscription payment"
}

subscription_payment_splits · SubscriptionPaymentSplitItem · object[]

Payment splits for the subscription.

Show child attributes

Response

200

application/json

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 payments.

Show child attributes

Example:

{
  "authorization_amount": 1,
  "authorization_amount_refund": false,
  "authorization_reference": "",
  "authorization_time": "2025-06-01T23:47:52+05:30",
  "authorization_status": "INITIALIZED",
  "payment_id": "97877",
  "payment_group": "upi",
  "payment_method": {
    "upi": {
      "channel": "collect",
      "upi_id": "test@upi",
      "upi_instrument": "upiInstrument",
      "upi_instrument_number": "1234567890",
      "upi_payer_account_number": "039861903074",
      "upi_payer_ifsc": "SBIN0001234"
    }
  }
}

cf_subscription_id · string

Cashfree subscription reference number

customer_details · object

Subscription customer details.

Show child attributes

Example:

{
  "customer_name": "Test Cust",
  "customer_email": "[e-mail]",
  "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

Show child attributes

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<ISO8601>

Time at which the subscription will expire. We store timestamps in IST.

Example:

"2025-06-01T10:20:12+05:30"

subscription_first_charge_time · string<ISO8601>

Time at which the first charge will be made for the subscription. Applicable only for PERIODIC plans. Cashfree stores timestamps in IST.

Example:

"2025-06-01T10:20:12+05:30"

subscription_id · string

A unique ID passed by merchant for identifying the subscription.

subscription_meta · object

Subscription metadata.

Show child attributes

subscription_note · string

Note for the subscription.

subscription_session_id · string

Subscription Session Id.

subscription_payment_splits · SubscriptionPaymentSplitItem · object[]

Payment splits for the subscription.

Show child attributes

subscription_status · string

Status of the subscription. For more details, see Subscription Lifecycle.

subscription_tags · object

Tags for the subscription.