Recurring Payments APIs - Configure Plans
The Ecommerce - Recurring 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://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": 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://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",
"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://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' \
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://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": "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://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": "2023-09-19T10:02:59.476+0000",
"modifiedTime": "2023-09-19T10:02:59.476+0000",
"id": "JCYFCH8JS3YT2",
"merchantId": "A1B2C3D4EFG56",
"developerAppId": "A1BCD2EFG34HI",
"object": "plan"
}
See also
Updated 4 months ago