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

  1. Send a POST request to the recurring/v1/plans endpoint.
  2. Set the Authorization header as your OAuth-generated access_token.
  3. Note the id (planID) to edit or delete the plan later.

Required header parameters

FieldDescriptionRequired/Optional
authorizationBearer tokenRequired
X-Clover-Merchant-IdClover merchant identifier (mId)Required

Request body fields

FieldDescriptionRequired / Optional
namePlan name. Cannot be null or blank.
Length:

- Minimum 3 characters
- Maximum 127 characters
Required
amountPlan amountRequired
noteAdditional information or notes related to the plan.Optional
taxRateUuidsTax rate universally unique identifiers (UUIDs).Optional
tipAmountAmount paid in tips.Optional
intervalInterval of the plan.
Values:

- Day
- Week
- Month
- Year
See the Interval Matrix table for details.
Required
intervalCountNumber of intervals in the plan.Required

Interval matrix

UX ElementDefinitionAPI frequencyAPI interval
DailyEverydayDay1
WeeklyEvery 7 daysWeek1
Bi-weeklyEvery 14 daysWeek2
MonthlyEvery month on the same date.Month1
Bi-monthlyEvery two months on the same date.Month2
QuarterlyEvery three months on the same date.Month3
Four monthsEvery four months on the same date.Month4
Semi-annuallyEvery six months on the same date.Month6
AnnuallyOnce a year on the same date.Year1

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

  1. Send a GET request to the recurring/v1/plans endpoint, including the planId parameter.
  2. Set the Authorization header as your OAuth-generated access_token.

Required header parameters

FieldDescriptionRequired/Optional
authorizationBearer tokenRequired
X-Clover-Merchant-IdClover merchant identifier (mId)Required

Required path parameters

FieldDescriptionRequired/Optional
planIdUniversally 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

  1. Send a GET request to the recurring/v1/plans endpoint, including the planId parameter.
  2. Set the Authorization header as your OAuth-generated access_token.

Required header parameters

FieldDescriptionRequired/Optional
authorizationBearer tokenRequired

Required path parameters

FieldDescriptionRequired/Optional
planIdUniversally 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

  1. Send a PUT request to the recurring/v1/plans endpoint, including the planId parameter.
  2. Set the Authorization header as your OAuth-generated access_token.

Required header parameters

FieldDescriptionRequired/Optional
authorizationBearer tokenRequired
X-Clover-Merchant-IdClover merchant identifier (mId)Required

Required path parameters

FieldDescriptionRequired/Optional
planIdUniversally unique identifier (UUID) of a plan.Required

Editable fields

FieldEditable?
nameYes
intervalNo
intervalCountNo
amountYes
tipAmountYes
noteYes
taxRateUuidsYes

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

  1. Send a PUT request to the recurring/v1/plans endpoint, including the planId parameter.
  2. Set the Authorization header as your OAuth-generated access_token.
  3. Set the "active": field to false.

Required header parameters

FieldDescriptionRequired/Optional
authorizationBearer tokenRequired
X-Clover-Merchant-IdClover merchant identifier (mId)Required

Required path parameters

FieldDescriptionRequired/Optional
planIdUniversally 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"
}