Skip to main content

Manage recurring plans

Managing a recurring plan allows you control the details of the goods or services you offer, the amount to be charged, and the frequency at which the consumer should be charged (i.e., billing cycle).

Before you begin

Learn about recurring plans and the features that Managed Recurring Payments API provides to help you customize as per your business requirement.

Create a recurring plan

You can create a recurring plan by sending a POST request to the /plans endpoint using the following required fields.

Required fields for creating a recurring plan
Field name Description
planName Uniquely identifies a plan managed by the merchant for a recurring program that includes plan pricing and plan billing frequency.
planType

Identifies the plans based on the recurring business model. There are two plan types to choose from:

  • Subscription: If you have a business model where consumers pay you a fixed amount on a regular basis, this plan type is perfect for you. You can set a fixed pricing amount for all your consumers, while also having the flexibility to offer custom pricing amounts for specific consumers, if required.
  • Auto Pay: If you have a business model where you want to customize the pricing amount for each consumer at the time of enrollment, this plan type is perfect for you. You can achieve this by setting up a zero dollar Autopay plan and use them with custom pricing for different consumers.
billingFrequencyCount The number of times the plan will be billed during the selected billing frequency.
billingFrequencyUnit

Selection of a billing frequency option. The valid values are:

  • DAYS
  • WEEKS
  • MONTHS
  • YEARS
currencyCode Represents a unique identifier for currencies, as assigned by the ISO 4217 specification. Alternatively, a currency code may also be a custom firm assigned value created where an ISO code does not exist.

HTTP method: POST

Endpoint: /plans

Scenario: Create a new plan with monthly billing frequency.

Json
{
    "merchantPlanId": "Plan123",
    "planName": "Gold Plan",
    "planType": "AUTOPAY",
    "planDescription": "Gold Plan Desc",
    "billingFrequencyCount": 1,
    "billingFrequencyUnit": "MONTHS",
    "planAmount": 1000,
    "currencyCode": "USD",
    "defaultPlan": true,
    "autoRenewable": false
}

Response:

Json
{
    "planId": "zBDsp2vXYL",
    "merchantId": "998152096534",
    "requestId": "91528923-2b48-4237-8f32-0b88208aa615",
    "merchantPlanId": "Plan123",
    "planName": "Gold Plan",
    "planType": "AUTOPAY",
    "planDescription": "Gold Plan Desc",
    "billingFrequencyCount": "1",
    "billingFrequencyUnit": "MONTHS",
    "planAmount": "1000",
    "currencyCode": "USD",
    "defaultPlan": true,
    "autoRenewable": false,
    "planStatus": "ACTIVE",
    "statusChangeDate": "2024-07-01T07:36:57.772Z"
}

Update a recurring plan

You can update an existing plan by sending a PATCH request to the /plans endpoint. However, the fields you can update depend on the plan status.

Fields you can update based on the plan status
Plan status (planStatus) Fields
Draft All the fields can be updated.
Active planAmount, currencyCode, billingFrequencyCount, billingFrequencyUnit, and planType cannot be updated.
Cancelled Only planStatus can be updated. Refer to the Plan status transition section for more information.

Plan status transition

You can also update the plan status to move a plan from one status to the other. However, this can only be done in certain scenarios. 

Here's a table that helps you identify when you can update a plan's status.

Plan status transition scenarios
Plan status (planStatus) Draft Active Cancelled
Draft N/A Allowed Allowed
Active Allowed (only if there is no active recurring program linked to the plan) N/A Allowed
Cancelled Allowed (only if there is no active recurring program linked to the plan) Allowed N/A

HTTP method: PATCH

Endpoint: /plans

Scenario: Update a draft plan with the plan amount and billing frequency.

Json
{
    "billingFrequencyCount": 2,
    "billingFrequencyUnit": "WEEKS",
    "planAmount": 50000,
    "currencyCode": "USD"
}

Response:

Json
{
    "planId": "H3h18JFg9g",
    "merchantId": "998152096533",
    "requestId": "CC-105239-D627792-123811-UAT",
    "merchantPlanId": "YOUR_PLAN_ID_005",
    "planName": "Your draft plan",
    "planType": "SUBSCRIPTION",
    "planDescription": "Your Draft Plan Description here",
    "billingFrequencyCount": "2",
    "billingFrequencyUnit": "WEEKS",
    "planAmount": "50000",
    "currencyCode": "USD",
    "defaultPlan": false,
    "autoRenewable": false,
    "planStatus": "DRAFT",
    "statusChangeDate": "2024-07-01T08:48:45.282Z"
}

Retrieve recurring plans

You can retrieve the details of recurring plans by sending a GET request to the /plans endpoint. 

By using the following filters, you can further customize the plans you want to retrieve:

  • planId
  • merchantPlanId
  • planStatus
  • planAmount
  • currencyCode

HTTP method: GET

Endpoint: /plans

Scenario: Retrieve a plan by plan status where planStatus = ACTIVE.

Json
{
    "recurringPlans": [
        {
            "planId": "BHm1bhtMyN",
            "merchantId": "998152096533",
            "requestId": "81528923-2b48-4237-8f32-0b88208aa513",
            "merchantPlanId": "YOUR_PLAN_ID_003",
            "planName": "Gold Plan",
            "planType": "SUBSCRIPTION",
            "planDescription": "Gold Plan Annual",
            "billingFrequencyCount": 1,
            "billingFrequencyUnit": "YEARS",
            "planAmount": 10000,
            "currencyCode": "USD",
            "defaultPlan": true,
            "autoRenewable": false,
            "planStatus": "ACTIVE",
            "statusChangeDate": "2024-04-22T07:02:37.629743"
        },
        {
            "planId": "9tRjjqvYt0",
            "merchantId": "998152096533",
            "requestId": "53d01772-b8cc-4198-b9e0-7fdb721fc1b8",
            "merchantPlanId": "YOUR_PLAN_ID_001",
            "planName": "Silver Plan",
            "planType": "SUBSCRIPTION",
            "planDescription": "Silver Plan Bi-Month",
            "billingFrequencyCount": 2,
            "billingFrequencyUnit": "MONTHS",
            "planAmount": 6000,
            "currencyCode": "USD",
            "defaultPlan": true,
            "autoRenewable": false,
            "planStatus": "ACTIVE",
            "statusChangeDate": "2024-04-29T11:47:26.497863"
        },
        {
            "planId": "vcTA8fn8Sl",
            "merchantId": "998152096533",
            "requestId": "53d01772-b8cc-4198-b9e0-7fdb721fc1b8",
            "merchantPlanId": "YOUR_PLAN_ID_006",
            "planName": "Bronze Plan",
            "planType": "SUBSCRIPTION",
            "planDescription": "Bronze Plan Month",
            "billingFrequencyCount": 1,
            "billingFrequencyUnit": "MONTHS",
            "planAmount": 1100,
            "currencyCode": "USD",
            "defaultPlan": true,
            "autoRenewable": false,
            "planStatus": "ACTIVE",
            "statusChangeDate": "2024-04-29T12:23:48.054147"
        }
    ]
}