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, third-party developers can use this API to incorporate the same functionality into their apps. Each plan defines the fixed amount, periodic frequency, tax, convenience fees, tip, etc. You can create as many recurring payment plans as necessary.

Creating 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

Field

Description

Required / Optional

name

Plan name

required

interval

Measure of time the charge occurs
for example, each month or year, etc.

required

intervalCount

Number of times the interval is to occur

required

amount

Amount

required

tipAmount

Tip amount

optional

note

Note text

optional

taxRateUuids

Tax rate UUID

optional

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 that was returned in the response for future operations.

Retrieving a plan

You can view only 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"
}

Searching 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 month interval and an interval count of 1. An array of plans meeting the 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,
    ...
  }
]

Editing a plan

You can edit only 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

Field

Editable? (Y/N)

name

Y

interval

N

intervalCount

N

amount

Y

tipAmount

Y

note

Y

taxRateUuids

Y

🚧

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"
}

Deactivating a plan

You can deactivate (cancel) only plans that you created and only 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


Did this page help you?