Recurring Payment APIs—Configure Plans

North America—United States and Canada

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 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://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 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://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 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://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 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://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 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://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