Recurring Payments APIs - Configure Plans

North America—United States and Canada

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 the recurring/v1/plans endpoint.
Set the Authorization header as your OAuth-generated access_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 the recurring/v1/plans endpoint, including the planId parameter.
Set the Authorization header as your OAuth-generated access_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 the recurring/v1/plans endpoint, including the planId parameter.
Set the Authorization header as your OAuth-generated access_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 the recurring/v1/plans endpoint, including the planId parameter.
Set the Authorization header as your OAuth-generated access_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 the recurring/v1/plans endpoint, including the planId parameter.
Set the Authorization header as your OAuth-generated access_token.
Set the "active": field to false.

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

Work with the Plans API

Create a plan

Required header parameters

Request body fields

Interval matrix

Sample request and response

Retrieve plans

Required header parameters

Required path parameters

Sample request and response

Search for a plan

Required header parameters

Required path parameters

Sample request and response

Edit a plan

Required header parameters

Required path parameters

Editable fields

Sample request and response

Deactivate a plan

Required header parameters

Required path parameters

Sample request and response

See also