Recurring Payment APIs—Configure Plans
The Ecommerce Recurring Payment APIs include two APIs—Plan and Subscription. The Plans API for ecommerce lets you create recurring payment plans that merchants can use through their dashboards. With the Plans API, you can:
- Define a set of plans that lets customers initiate automatic payments.
- Set the fixed amount, periodic frequency, tax, convenience fees, tips, and so on for each plan.
- Include a consistent set of defined features in your apps and create several recurring payment plans.
Work with the Plans API
You can use endpoints in the Plans API to:
Create a plan
Create a plan lets your merchants define a set of plans to initiate automatic payments. You can create as many recurring payment plans as required.
Steps
- Send a
POST
request to therecurring/v1/plans
endpoint. - Set the
Authorization
header as your OAuth-generatedaccess_token
. - Note the
id
(planID
) to edit or delete the plan later.
Required header parameters
Field | Description | Required/Optional |
---|---|---|
authorization | Bearer token | Required |
X-Clover-Merchant-Id | Clover merchant identifier (mId) | Required |
Request body fields
Field | Description | Required / Optional |
---|---|---|
name | Plan name. Cannot be null or blank. Length: - Minimum 3 characters - Maximum 127 characters | Required |
amount | Plan amount | Required |
note | Additional information or notes related to the plan. | Optional |
taxRateUuids | Tax rate universally unique identifiers (UUIDs). | Optional |
tipAmount | Amount paid in tips. | Optional |
interval | Interval of the plan. Values: - Day - Week - Month - Year See the Interval Matrix table for details. | Required |
intervalCount | Number of intervals in the plan. | Required |
Interval matrix
UX Element | Definition | API frequency | API interval |
---|---|---|---|
Daily | Everyday | 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://apisandbox.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": 3,
"note": "This is your first plan",
"taxRateUuids": [
"1ABC2DE3F4GHI"
],
"tipAmount": 300
}
{
"name": "Monthly Plan",
"taxRateUuids": [
"1ABC2DE3F4GHI"
],
"tipAmount": 300,
"amount": 1000,
"active": true,
"interval": "MONTH",
"intervalCount": 3,
"note": "This is your first plan",
"createdTime": "2023-09-19T10:02:59.476+0000",
"modifiedTime": "2023-09-19T10:02:59.476+0000",
"id": "JCYFCH8JS3YT2",
"merchantId": "A1B2C3D4EFG56",
"developerAppId": "A1BCD2EFG34HI",
"object": "plan"
}
Retrieve plans
You can retrieve plans to view plan details only for the plans that you created. See Retrieve plans for more information on retrieving a recurring payment plan.
Steps
- Send a
GET
request to therecurring/v1/plans
endpoint, including the planId parameter. - Set the
Authorization
header as your OAuth-generatedaccess_token
.
Required header parameters
Field | Description | Required/Optional |
---|---|---|
authorization | Bearer token | Required |
X-Clover-Merchant-Id | Clover merchant identifier (mId) | Required |
Required path parameters
Field | Description | Required/Optional |
---|---|---|
planId | Universally unique identifier (UUID) of a plan. | Required |
Sample request and response
curl --request GET \
--url 'https://apisandbox.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",
"taxRateUuids": [
"1ABC2DE3F4GHI"
],
"tipAmount": 300,
"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",
"developerAppId": "A1BCD2EFG34HI",
"object": "plan"
}
Search for a plan
You can search for a plan with specific features, such as interval and interval count. See Get plan for more information.
Steps
- Send a
GET
request to therecurring/v1/plans
endpoint, including theplanId
parameter. - Set the
Authorization
header as your OAuth-generatedaccess_token
.
Required header parameters
Field | Description | Required/Optional |
---|---|---|
authorization | Bearer token | Required |
Required path parameters
Field | Description | Required/Optional |
---|---|---|
planId | Universally unique identifier (UUID) of a plan. | Required |
Sample request and response
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.
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' \
curl --request GET \
{
"tipAmount": 300,
"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",
"developerAppId": "A1BCD2EFG34HI",
"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 the plans that you created. See Edit a plan for more information. The interval
and intervalCount
fields are not editable. To change these fields, you need to delete and recreate the plan.
Steps
- Send a
PUT
request to therecurring/v1/plans
endpoint, including theplanId
parameter. - Set the
Authorization
header as your OAuth-generatedaccess_token
.
Required header parameters
Field | Description | Required/Optional |
---|---|---|
authorization | Bearer token | Required |
X-Clover-Merchant-Id | Clover merchant identifier (mId) | Required |
Required path parameters
Field | Description | Required/Optional |
---|---|---|
planId | Universally unique identifier (UUID) of a plan. | Required |
Editable fields
Field | Editable? |
---|---|
name | Yes |
interval | No |
intervalCount | No |
amount | Yes |
tipAmount | Yes |
note | Yes |
taxRateUuids | Yes |
Sample request and response
curl --request PUT \
--url 'https://apisandbox.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": "2023-09-19T10:02:59.476+0000",
"modifiedTime": "2023-09-19T10:02:59.476+0000",
"id": "JCYFCH8JS3YT2",
"merchantId": "A1B2C3D4EFG56",
"developerAppId": "A1BCD2EFG34HI",
"object": "plan"
}
Deactivate a plan
You can deactivate (cancel) plans you created if no active subscriptions are associated with them. See Delete a plan for more information.
Steps
- Send a
PUT
request to therecurring/v1/plans
endpoint, including the planId parameter. - Set the
Authorization
header as your OAuth-generatedaccess_token
. - Set the
"active"
: field tofalse
.
Required header parameters
Field | Description | Required/Optional |
---|---|---|
authorization | Bearer token | Required |
X-Clover-Merchant-Id | Clover merchant identifier (mId) | Required |
Required path parameters
Field | Description | Required/Optional |
---|---|---|
planId | Universally unique identifier (UUID) of a plan. | Required |
Sample request and response
curl --request PUT \
--url 'https://apisandbox.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": "2023-09-19T10:02:59.476+0000",
"modifiedTime": "2023-09-19T10:02:59.476+0000",
"id": "JCYFCH8JS3YT2",
"merchantId": "A1B2C3D4EFG56",
"developerAppId": "A1BCD2EFG34HI",
"object": "plan"
}
Updated 12 days ago