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

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

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

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

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

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

Recurring Payment APIs - Configure Subscriptions