What's NewAnnouncementsWebinarsCommunityBlog

Recurring Payments APIs - Configure Plans

United States
Canada

Recurring Payments and Subscriptions APIs include Plan APIs. These APIs allow merchants to define a set of plans that customers can use to initiate automatic payments. In addition, you can use this API to incorporate the same functionality in the apps. Each plan defines the fixed amount, periodic frequency, tax, convenience fees, tip, and so on. You can create as many recurring payment plans as required.

Create a plan

To create a recurring plan, send a POST request to the recurring/v1/plans endpoint. Set the Authorization header as your OAuth-generated access_token.
Refer to the Create plan API for more information on creating a recurring payment plan.

Required header parameters

  • authorization
  • X-Clover-Merchant-Id

Request body fields

FieldDescriptionRequired / Optional
namePlan name.
Length: Minimum 3 characters; Maximum 127 characters		required
intervalPlan interval. Example: Daily, weekly, semi-monthly, monthly, quarterly, yearly.
See Interval Matrix table for details.		required
intervalCountNumber of times the plan interval occurs.required
amountPlan amount.required
tipAmountTip amount.optional
noteAdditional information or note related to the plan.optional
taxRateUuidsTax rate universally unique identifiers (UUIDs).optional

Interval matrix

UX ElementDefinitionAPI frequencyAPI interval
DailyEvery dayDay1
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": "1", 
    "note": "This is an note",
    "taxRateUuids": [
        "3CSH9MF3K0AZC"
    ],
    "tipAmount": 300
}

{
  "name": "Monthly Plan",
  "taxRateUuids": [
    "3CSH9MF3K0AZC"
  ],
  "tipAmount": 300,
  "amount": 1000,
  "active": true,
  "interval": "MONTH",
  "intervalCount": 1,
  "note": "This is a note",
  "createdTime": "[email protected]:56:54.517+0000",
  "modifiedTime": "[email protected]:56:54.517+0000",
  "id": "{planId}",
  "merchantId": "{mId}",
  "developerAppId": "{devAppId}",
  "object": "plan"
}

Note the planId returned in the response for future operations.

Retrieve a plan

You can view only the plans that you created. Refer to Retrieve plans for more information on retrieving a recurring payment plan.

To retrieve a plan, 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 path parameters

  • planId

Required header parameters

  • authorization
  • X-Clover-Merchant-Id

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",
  "amount": 200,
  "active": false,
  "interval": "MONTH",
  "intervalCount": 1,
  "note": "This is a note",
  "createdTime": "[email protected]:56:54.517+0000",
  "modifiedTime": "[email protected]:56:54.517+0000",
  "id": "{planId}",
  "merchantId": "{mId}",
  "developerAppId": "{devAppId}",
  "object": "plan"
}

Search for plans

You can search for and retrieve plans that have specific features such as interval and interval count.
Send a GET request to the recurring/v1/plans endpoint, including query string parameters of the plan information you want to retrieve in the response. Set the Authorization header as your OAuth-generated access_token. Refer to the Get plan API for more information on searching for plans.

Required header parameters

  • authorization
  • X-Clover-Merchant-Id

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.

Sample request and response

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' \

[
  {
    "name": "Monthly Plan",
    "amount": 200,
    "active": true,
    "interval": "MONTH",
    "intervalCount": 1,
    "note": "This is a note",
    "createdTime": "[email protected]:56:54.517+0000",
    "modifiedTime": "[email protected]:56:54.517+0000",
    "subscriptionCount": 0,
    "id": "{planId}",
    "merchantId": "{mId}",
    "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 only the plans that you created. Refer to the Edit a plan API for more information on editing a recurring payment plan.

To edit a recurring plan, send a PUT request to the recurring/v1/plans endpoint with the planId parameter. Set the Authorization header as your OAuth-generated access_token.

Required path parameters

  • planId

Required header parameters

  • authorization
  • X-Clover-Merchant-Id

Editable fields

FieldEditable? (Y/N)
nameY
intervalN
intervalCountN
amountY
tipAmountY
noteY
taxRateUuidsY

🚧

IMPORTANT

The interval and intervalCount fields are not editable. To change these fields, you need to delete and recreate the plan.

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": "[email protected]:39:08.000+0000",
  "modifiedTime": "[email protected]:06:58.000+0000",
  "id": "{planId}",
  "merchantId": "{mId}",
  "developerAppId": "{devAppId}",
  "object": "plan"
}

Deactivate a plan

You can deactivate (cancel) only the plans that you created if there are no active subscriptions associated with the plan. Refer to the Delete a plan API for more information on deactivating a recurring payment plan.

To deactivate a plan, send a PUT request to the recurring/v1/plans endpoint with the planId parameter. Set the Authorization header as your OAuth-generated access_token. Then, set the "active": field to "false".

Required path parameters

  • planId

Required header parameters

  • authorization
  • X-Clover-Merchant-Id

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": "[email protected]:39:08.000+0000",
  "modifiedTime": "[email protected]:06:58.000+0000",
  "id": "{planId}",
  "merchantId": "mId",
  "developerAppId": "devAppId",
  "object": "plan"
}

See also

Recurring Payment APIs - Configure Subscriptions

Updated 2 months ago