Cashfree Subscriptions Integration Docs

Use this doc as a friendly reference for integrating recurring subscriptions, subscription links, plan management, and webhooks.

What we supports

We supports two subscription entry points:

1. Seamless recurring subscriptions using a stored plan andcreate-order.
2. Non-seamless subscription links usingcreate-subscription-link.

It also supports:

• Creating and disabling plans.
• Listing and inspecting subscriptions.
• Charging a subscription on demand.
• Cancelling subscriptions and subscription links.
• Handling Cashfree subscription webhooks.

Base Contract

All routes are tenant-scoped:

/tenant/:tenantId/customer/...

Most endpoints require a bearer token in theAuthorizationheader.

Authorization: Bearer <token>
Content-Type: application/json

1) Create a Plan

Create a plan first if you want a reusable recurring subscription plan.

Endpoint

POST /tenant/:tenantId/customer/create-plan

Check Here

Example request

curl -X POST "https://your-api/tenant/123/customer/create-plan" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "plan_monthly_499",
    "planName": "Monthly Pro Plan",
    "planType": "PERIODIC",
    "planCurrency": "INR",
    "planRecurringAmount": 499,
    "planMaxAmount": 5000,
    "planMaxCycles": 12,
    "planIntervals": 1,
    "planIntervalType": "MONTH",
    "planNote": "Monthly subscription plan"
  }'

Notes

• planIdmust be unique.
• PERIODICplans needplanRecurringAmount,planIntervals, andplanIntervalType.
• ON_DEMANDplans only needplanId,planName, andplanMaxAmount.

2) Create a Seamless Recurring Subscription

Usecreate-orderwhen you want the backend to create a recurring subscription order using an existing plan.

Endpoint

POST /tenant/:tenantId/customer/create-order

Check Here

Example request

curl -X POST "https://your-api/tenant/123/customer/create-order" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "recurring",
    "amount": 10,
    "currency": "INR",
    "leadId": "lead_001",
    "customerId": "cust_001",
    "name": "John Doe",
    "email": "john@example.com",
    "contact": "9876543210",
    "planId": "69cf76c650fd959930ab0e76",
    "notes": {
      "source": "website"
    },
    "notify": true,
    "returnUrl": "https://your-app.com/billing/success",
    "notifyUrl": "https://your-api/tenant/123/customer/webhook"
  }'

Notes

• typemust berecurring.
• planIdis the local plan database ID returned bycreate-plan.
• amountis the one-time authorization amount, not the recurring charge.
• The recurring charge amount comes from the plan.

3) Create a Non-Seamless Subscription Link

Usecreate-subscription-linkwhen you want Cashfree to generate a shareable subscription authorization link.

Endpoint

POST /tenant/:tenantId/customer/create-subscription-link

Check Here

Example request

curl -X POST "https://your-api/tenant/123/customer/create-subscription-link" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "leadId": "lead_001",
    "subscriptionId": "sub_monthly_001",
    "customerName": "John Doe",
    "customerPhone": "9876543210",
    "customerEmail": "john@example.com",
    "authAmount": 10,
    "planInfo": {
      "type": "PERIODIC",
      "planName": "Monthly Pro",
      "maxAmount": 5000,
      "recurringAmount": 499,
      "intervals": 1,
      "intervalType": "MONTH"
    },
    "notificationChannels": ["EMAIL", "SMS"]
  }'

Notes

• customerPhoneandplanInfoare required.
• planInfois inline here, so you do not need a pre-created plan record.
• The response containsauthLink, which is the Cashfree subscription authorization URL.

4) Webhooks

Use your tenant webhook endpoint to receive subscription status updates from Cashfree.

Endpoint

POST /tenant/:tenantId/customer/webhook

Check Here

Subscription webhook events

• SUBSCRIPTION_AUTH_STATUS
• SUBSCRIPTION_STATUS_CHANGED
• SUBSCRIPTION_PAYMENT_SUCCESS
• SUBSCRIPTION_PAYMENT_FAILED
• SUBSCRIPTION_PAYMENT_CANCELLED

Important

• Keep the raw request body available for signature verification.
• Persist webhook results so you can trace subscription state changes.

5) Read and Manage Subscriptions

List subscriptions

GET /tenant/:tenantId/customer/get-subscriptions

Check Here

Optional query params:

• leadId
• status
• planId
• page
• limit
• filteras JSON string

Get a subscription

GET /tenant/:tenantId/customer/get-subscription/:id

Check Here

Charge a subscription

POST /tenant/:tenantId/customer/charge-subscription/:id

Check Here

Example body:

{
  "amount": 499,
  "scheduledOn": "2024-12-31",
  "remarks": "Monthly subscription charge"
}

Cancel a subscription

POST /tenant/:tenantId/customer/cancel-subscription

Check Here

Example body:

{
  "id": "665a1b2c3d4e5f6a7b8c9d0e"
}

6) Manage Subscription Links

Cancel a subscription link

POST /tenant/:tenantId/customer/cancel-subscription-link/:id

Use this to cancel a link that has not already been paid.

7) Easy Split With Recurring Subscriptions

This backend supports Easy Split for recurring orders.

Rules to keep in mind:

• For recurring subscriptions, usepercentagesplits only.
• amountsplits are only for one-time payments.
• Each vendor must already exist and beACTIVEin Cashfree.
• The backend creates a static split configuration after subscription registration.

Integration Checklist

1. Create or choose a plan.
2. Start a recurring subscription withcreate-orderor generate a non-seamless link withcreate-subscription-link.
3. Send the customer to the returned Cashfree auth URL.
4. Handle subscription webhooks.
5. Query subscription state withget-subscriptionsorget-subscription/:id.
6. Charge or cancel the subscription when needed.