Recurring Payments APIs - Configuring Plans

Recurring Payments and Subscriptions APIs includes Plan APIs. These APIs allow merchants to define a set of plans that customers can use to initiate automatic payments. In addition, you can use this API to incorporate the same functionality in the apps. Each plan defines the fixed amount, periodic frequency, tax, convenience fees, tip, etc. You can create as many recurring payment plans as required.

Create a plan

To create a recurring plan, send a POST request to the recurring/v1/plans endpoint. Set the Authorization header as your OAuth-generated access_token.
Refer to the Create plan API for more information on creating a recurring payment plan.

Required header parameters

  • authorization
  • X-Clover-Merchant-Id

Request body fields

FieldDescriptionRequired / Optional
namePlan namerequired
interval
See Interval Matrix table for details.
Measure of time the charge occurs
for example, each month or year, etc.
required
intervalCountNumber of times the interval is to occurrequired
amountAmountrequired
tipAmountTip amountoptional
noteNote textoptional
taxRateUuidsTax rate UUIDoptional

Interval matrix

UX ElementDefinitionAPI frequencyAPI interval
DailyEvery dayDay1
WeeklyEvery 7 daysWeek1
Bi-weeklyEvery 14 daysWeek2
MonthlyEvery month on the same date.Month1
Bi-monthlyEvery two months on the same date.Month2
QuarterlyEvery three months on the same date.Month3
Four monthsEvery four months on the same date.Month4
Semi-annuallyEvery six months on the same date.Month6
AnnuallyOnce a year on the same date.Year1

Sample request and response

curl  --request POST \
  --url 'https://sandbox.dev.clover.com/recurring/v1/plans' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access_token}' \
  --header 'X-Clover-Merchant-Id: {mId}' \
  --header 'content-Type: application/json' \
  --data-raw '{
    "name": "Monthly Plan",
    "amount": "1000", 
    "interval": "MONTH", 
    "intervalCount": "1", 
    "note": "This is an note",
    "taxRateUuids": [
        "3CSH9MF3K0AZC"
    ],
    "tipAmount": 300
}
{
  "name": "Monthly Plan",
  "taxRateUuids": [
    "3CSH9MF3K0AZC"
  ],
  "tipAmount": 300,
  "amount": 1000,
  "active": true,
  "interval": "MONTH",
  "intervalCount": 1,
  "note": "This is a note",
  "createdTime": "[email protected]:56:54.517+0000",
  "modifiedTime": "[email protected]:56:54.517+0000",
  "id": "{planId}",
  "merchantId": "{mId}",
  "developerAppId": "{devAppId}",
  "object": "plan"
}

Note the planId returned in the response for future operations.

Retrieve a plan

You can view only the plans that you created. Refer to Retrieve plans for more information on retrieving a recurring payment plan.

To retrieve a plan, send a GET request to the recurring/v1/plans endpoint, including the planId parameter. Set the Authorization header as your OAuth-generated access_token.

Required path parameters

  • planId

Required header parameters

  • authorization
  • X-Clover-Merchant-Id

Sample request and response

curl --request GET \
  --url 'https://sandbox.dev.clover.com/recurring/v1/plans/{planId}' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'X-Clover-Merchant-Id: {mId}'
  --header 'content-Type: application/json' \
{
  "name": "Monthly Plan",
  "amount": 200,
  "active": false,
  "interval": "MONTH",
  "intervalCount": 1,
  "note": "This is a note",
  "createdTime": "[email protected]:56:54.517+0000",
  "modifiedTime": "[email protected]:56:54.517+0000",
  "id": "{planId}",
  "merchantId": "{mId}",
  "developerAppId": "{devAppId}",
  "object": "plan"
}

Search for plans

You can search for and retrieve plans that have specific features such as interval and interval count.
Send a GET request to the recurring/v1/plans endpoint, including query string parameters of the plan information you want to retrieve in the response. Set the Authorization header as your OAuth-generated access_token. Refer to the Get plan API for more information on searching for plans.

Required header parameters

  • authorization
  • X-Clover-Merchant-Id

The following example retrieves all plans that are set to a monthly frequency and an interval count of 1. The list of plans meeting specified criteria is returned.

Sample request and response

curl --request GET \
  --url 'https://sandbox.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' \
[
  {
    "name": "Monthly Plan",
    "amount": 200,
    "active": true,
    "interval": "MONTH",
    "intervalCount": 1,
    "note": "This is a note",
    "createdTime": "[email protected]:56:54.517+0000",
    "modifiedTime": "[email protected]:56:54.517+0000",
    "subscriptionCount": 0,
    "id": "{planId}",
    "merchantId": "{mId}",
    "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,
    ...
  }
]

Edit a plan

You can edit only the plans that you created. Refer to the Edit a plan API for more information on editing a recurring payment plan.

To edit a recurring plan, send a PUT request to the recurring/v1/plans endpoint with the planId parameter. Set the Authorization header as your OAuth-generated access_token.

Required path parameters

  • planId

Required header parameters

  • authorization
  • X-Clover-Merchant-Id

Editable fields

FieldEditable? (Y/N)
nameY
intervalN
intervalCountN
amountY
tipAmountY
noteY
taxRateUuidsY

🚧

IMPORTANT

The interval and intervalCount fields are not editable. If you must change these fields, you will need to delete and recreate the plan.

Sample request and response

curl --request PUT \ 
  --url 'https://sandbox.dev.clover.com/recurring/v1/plans/{planId}' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'X-Clover-Merchant-Id: {mId}'
  --header 'content-Type: application/json' \
  --data-raw '{
    "name": "Plan_name",
    "amount": "", 
    "active": "true"
}'
{
  "name": "Recurring_plan 2",
  "amount": 200,
  "active": true,
  "interval": "MONTH",
  "intervalCount": 1,
  "note": "This is a note",
  "createdTime": "[email protected]:39:08.000+0000",
  "modifiedTime": "[email protected]:06:58.000+0000",
  "id": "{planId}",
  "merchantId": "{mId}",
  "developerAppId": "{devAppId}",
  "object": "plan"
}

Deactivate a plan

You can deactivate (cancel) only the plans that you created if there are no active subscriptions associated with the plan. Refer to the Delete a plan API for more information on deactivating a recurring payment plan.

To deactivate a plan, send a PUT request to the recurring/v1/plans endpoint with the planId parameter. Set the Authorization header as your OAuth-generated access_token. Then set the "active": field to "false".

Required path parameters

  • planId

Required header parameters

  • authorization
  • X-Clover-Merchant-Id

Sample request and response

curl --request PUT \ 
  --url 'https://sandbox.dev.clover.com/recurring/v1/plans/{planId}' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'X-Clover-Merchant-Id: {mId}'
  --header 'content-Type: application/json' \
  --data-raw '{
    "active": false
}'
{
  "name": "Recurring_plan 2",
  "amount": 200,
  "active": false,
  "interval": "MONTH",
  "intervalCount": 1,
  "note": "This is a note",
  "createdTime": "[email protected]:39:08.000+0000",
  "modifiedTime": "[email protected]:06:58.000+0000",
  "id": "{planId}",
  "merchantId": "mId",
  "developerAppId": "devAppId",
  "object": "plan"
}

Related topic