Recurring Payments APIs - Configure Plans
Recurring Payments and Subscriptions APIs include 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, and so on. 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
Field | Description | Required / Optional |
---|---|---|
name | Plan name. Length: Minimum 3 characters; Maximum 127 characters | required |
interval | Plan interval. Example: Daily, weekly, semi-monthly, monthly, quarterly, yearly. See Interval Matrix table for details. | required |
intervalCount | Number of times the plan interval occurs. | required |
amount | Plan amount. | required |
tipAmount | Tip amount. | optional |
note | Additional information or note related to the plan. | optional |
taxRateUuids | Tax rate universally unique identifiers (UUIDs). | optional |
Interval matrix
UX Element | Definition | API frequency | API interval |
---|---|---|---|
Daily | Every day | Day | 1 |
Weekly | Every 7 days | Week | 1 |
Bi-weekly | Every 14 days | Week | 2 |
Monthly | Every month on the same date. | Month | 1 |
Bi-monthly | Every two months on the same date. | Month | 2 |
Quarterly | Every three months on the same date. | Month | 3 |
Four months | Every four months on the same date. | Month | 4 |
Semi-annually | Every six months on the same date. | Month | 6 |
Annually | Once a year on the same date. | Year | 1 |
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
Field | Editable? (Y/N) |
---|---|
name | Y |
interval | N |
intervalCount | N |
amount | Y |
tipAmount | Y |
note | Y |
taxRateUuids | Y |
IMPORTANT
The
interval
andintervalCount
fields are not editable. To change these fields, you 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"
}
See also
Updated 2 months ago