Manage a subscription.

Use this API to manage subscriptions. You can cancel, pause, activate, or change the plan associated with a subscription. To update the recurring amount for a periodic subscription, create a new plan with the revised amount, and then use the Manage Subscription API to associate the subscription with the new plan. Include the CHANGE_PLAN action and the new plan ID in the request body.

Customers will not be notified about the restructuring. The charge amount cannot exceed the maximum amount defined in the original plan.

Please note that the CHANGE_PLAN and PAUSE actions are not supported for On-Demand Subscriptions.

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: 2023-08-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.

Path Parameters

subscription_id · string · required

Provide the SubscriptionId using which the subscription was created.

Body

application/json

Request body to manage a subscription.

subscription_id · string · required

The unique ID which was used to create subscription.

action · string · required

Action to be performed on the subscription. Possible values - CANCEL, PAUSE, ACTIVATE, CHANGE_PLAN.

action_details · object

Details of the action to be performed.

Show child attributes

Response

200

application/json

Subscription Updated

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.

Show child attributes

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.

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

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.

Show child attributes

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.

subscription_tags · object

Tags for the subscription.