Recurring payments API includes two APIs—Plan and Subscription. The Plan APIs are designed to facilitate the creation and management of recurring payment plans for merchants, enabling them to offer subscription-based services to their customers. The API supports automatic payments, reducing the need for manual billing and improving efficiency.

Key features of the Plans API include:

• Plan creation—Merchants can create various recurring payment plans through their Merchant Dashboards. These plans define the billing cycle and amount for automatic payments.
• Customization—Developers can create and customize the plans, including setting fixed amounts, periodic frequencies, taxes, convenience fees, and tips.
• Consistency—Developers can include a consistent set of defined features in their apps, enabling the creation of multiple recurring payment plans.
• Subscription management—Once plans are created, merchants can use the Subscription API to create subscriptions for those plans, managing customer enrollments and payments. Merchants can offer different subscription options to their customers by creating multiple plans.

Prerequisites

• For sandbox—Generate a test API token.
• For production—Generate OAuth expiring (access and refresh) token.

Create a plan

You can set up plans for merchants to start automatic payments. Create as many recurring payment plans as needed.

1. Send a POST request to recurring/v1/plans.
2. Enter the required information:

• X-Clover-Merchant-Id—Clover merchant identifier (mId).
• name —Plan name. Cannot be null or blank. Length: Minimum 3 characters; Maximum 127 characters.
• amount—Plan amount.
• interval—Interval of the plan, such as Day, Week, Month, or Year. See the Interval Matrix table for details.
• intervalCount—Number of intervals in the plan.
  Example: For an interval: Month and intervalCount: 12, the plan recurs every month for a total of 12 months. The plan is billed monthly and continues for one year.

3. Set the Authorization header as Bearer token type, and enter the test API token or OAuth-generated access_token.

In response, a unique planId is generated. Note the plan Id to update or delete the plan later.

Interval matrix

Sample request and response—Create a plan

curl --request POST \
  --url 'https://apisandbox.dev.clover.com/recurring/v1/plans' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'X-Clover-Merchant-Id: {mId}' \
  --header 'content-Type: application/json' \
  --data '{
    "interval": "MONTH",
    "name": "Semi-annual plan",
    "amount": 10,
    "note": "This is a test plan.",
    "intervalCount": 6
  }'

{
  "name": "Semi-annual plan",
  "amount": 10,
  "active": true,
  "interval": "MONTH",
  "intervalCount": 6,
  "note": "This is a test plan.",
  "createdTime": "2025-03-04T06:54:48.867+0000",
  "modifiedTime": "2025-03-04T06:54:48.867+0000",
  "id": "BBJ37BFWEP7TA", // plan ID
  "merchantId": "A1B2C3D4EFG56",
  "object": "plan"
}

View plans

Retrieve all plans

You can retrieve all recurring plans to view the plan details.

1. Send a GET request to /recurring/v1/plans.
2. Enter the required information: X-Clover-Merchant-Id—Clover merchant identifier (mId).
3. Enter other information to narrow down your search results, for example, enter interval and intervalCount.
4. Set the Authorization header as Bearer token type, and enter the test API token or OAuth-generated access_token.

Sample request and response—View all plans for specific criteria

The following example retrieves all plans that are set to a monthly frequency and an interval count of 1.

curl --request GET \
  --url 'https://apisandbox.dev.clover.com/recurring/v1/plans?interval=MONTH&intervalCount=1' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'X-Clover-Merchant-Id: {mId}' \
  --header 'content-Type: application/json'

 {
  "amount": 1000,
  "active": true,
  "interval": "MONTH",
  "intervalCount": 1,
  "note": "This is a note",
  "createdTime": "2023-09-19T10:02:59.476+0000",
  "modifiedTime": "2023-09-19T10:02:59.476+0000",
  "id": "JCYFCH8JS3YT2",
  "merchantId": "A1B2C3D4EFG56",
  "object": "plan"
  },
  {
    "name": "Monthly Plan 2",
    "amount": 200,
    "active": false,
    "interval": "MONTH",
    "intervalCount": 1,
   ...
  },
  {
    "name": "Monthly API Plan",
    "amount": 100,
    "active": true,
    "interval": "MONTH",
    "intervalCount": 1,
    ...
  }
]

Retrieve a plan

You can view a specific plan based on the plan ID.

1. Send a GET request to /recurring/v1/plans/{planId}.
2. Enter the required information:

• X-Clover-Merchant-Id—Clover merchant identifier (mId).
• planId —Unique identifier of the plan.

3. Set the Authorization header as Bearer token type, and enter the test API token or OAuth-generated access_token.

Sample request and response—View a plan

curl --request GET \
     --url 'https://apisandbox.dev.clover.com/recurring/v1/plans/{planId}' \
     --header 'Authorization: Bearer {access_token}' \
     --header 'X-Clover-Merchant-Id: {mId}' \
     --header 'content-Type: application/json'

{
  "name": "Annual plan",
  "amount": 500,
  "active": true,
  "interval": "YEAR",
  "intervalCount": 5,
  "subscriptionCount": 0,
  "activeSubscriptionCount": 0,
  "createdTime": "2025-03-03T09:30:42.000+0000",
  "modifiedTime": "2025-03-03T09:32:39.000+0000",
  "id": "1408M6R65QPX6", //plan Id
  "merchantId": "A1B2C3D4EFG56",
  "object": "plan"
}

Update a plan

You can edit specific parameters in the plans that you created.

• Editable fields include: name, amount, tipAmount, note, taxRateUuids
• Non-editable fields include: interval and intervalCount. To update these fields, you need to delete and recreate the plan.

1. Send a PUT request to /recurring/v1/plans.
2. Enter the required information:
   • X-Clover-Merchant-Id—Clover merchant identifier (mId).
   • planId —Unique identifier of the plan.
3. Enter updated information for the editable fields only, such as: name, amount, tipAmount, note, taxRateUuids
4. Set the Authorization header as Bearer token type, and enter the test API token or OAuth-generated access_token.

Sample request and response—Update a plan

curl --request PUT \
  --url 'https://apisandbox.dev.clover.com/recurring/v1/plans/{planId}' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'X-Clover-Merchant-Id: {mId}' \
  --header 'content-Type: application/json' \
  --data '{
    "amount": 400,
    "name": "Annual discounted plan",
    "note": "This is a special discounted plan.",
    "active": true
  }

{
  "name": "Annual discounted plan",
  "amount": 400,
  "active": true,
  "interval": "YEAR",
  "intervalCount": 5,
  "note": "This is a special discounted plan.",
  "createdTime": "2025-03-03T09:30:42.000+0000",
  "modifiedTime": "2025-03-04T09:42:56.488+0000",
  "id": "1408M6R65QPX6", //plan Id
  "merchantId": "A1B2C3D4EFG56",
  "object": "plan"
}

Deactivate a plan

You can deactivate or cancel plans only if no active subscriptions are associated with them.

1. Send a PUT request to /recurring/v1/plans.
2. Enter the required information:
   • X-Clover-Merchant-Id—Clover merchant identifier (mId).
   • planId —Unique identifier of the plan.
3. To deactivate a plan without deleting it, set the active: parameter to false.
4. Set the Authorization header as Bearer token type, and enter the test API token or OAuth-generated access_token.

Sample request and response—Deactivate a plan

curl --request PUT \
  --url 'https://apisandbox.dev.clover.com/recurring/v1/plans/{planId}' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'X-Clover-Merchant-Id: {mId}' \
  --header 'content-Type: application/json' \
  --data '{
    "amount": 400,
    "name": "Seasonal plan",
    "note": "This is a seasonal plan.",
    "active": false
  }

{
  "name": "Seasonal plan",
  "amount": 400,
  "active": false,
  "interval": "YEAR",
  "intervalCount": 5,
  "note": "This is a seasonal plan.",
  "createdTime": "2025-03-03T09:30:42.000+0000",
  "modifiedTime": "2025-03-04T09:47:31.401+0000",
  "id": "1408M6R65QPX6",
  "merchantId": "A1B2C3D4EFG56",
  "object": "plan"
}

Delete a plan

You can delete a plan only if no active subscriptions are associated with them.

1. Send a DELETE request to /recurring/v1/plans/{planId}.
2. Enter the required information:
   • X-Clover-Merchant-Id—Clover merchant identifier (mId).
   • planId —Unique identifier of the plan.
3. Set the Authorization header as Bearer token type, and enter the test API token or OAuth-generated access_token.

Sample request and response—Delete a plan

curl --request DELETE \
     --url 'https://apisandbox.dev.clover.com/recurring/v1/plans/{planId}' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'X-Clover-Merchant-Id: {mId}' \
  --header 'content-Type: application/json' \

{
  "name": "Monthly plan",
  "amount": 10,
  "active": false,
  "interval": "MONTH",
  "intervalCount": 12,
  "createdTime": "2025-03-03T09:33:21.000+0000",
  "modifiedTime": "2025-03-04T06:51:52.779+0000",
  "deletedTime": "2025-03-04T06:51:52.758+0000",
  "id": "5FDQ4TSBPVQF2",
  "merchantId": "A1B2C3D4EFG56",
  "object": "plan"
}

Related topics

• Recurring payments with plans and subscriptions
• Recurring payments API—Configure Subscription tutorial
• Create a plan endpoint
• Update a plan endpoint
• Get a plan endpoint
• Get all plans endpoint
• Delete a plan endpoint