Recurring Payment APIs - Configure subscriptions

United States

Canada

The Ecommerce - Recurring APIs include two APIs—Plan and Subscription. The Subscriptions API for ecommerce lets you create subscriptions for plans that merchants can use on their Clover Merchant dashboard. Each subscription associates a customer to a plan to identify:

Who is billed for the subscription?
Whether credit card on file (COF) is present?
What is the amount of the scheduled payment?
What are the dates to take a scheduled payment?

Using this information the subscription generates an invoice for each payment.

A configured subscription is deactivated if the customer's invoice payment fails after five attempts. Invoice payments can fail if the customer's information or card data is invalid or missing, for example, if there is no card-on-file during payment.

Work with the Subscriptions API

You can use subscriptions API to:

Create a subscription

Define subscriptions for the set of plans to initiate automatic payments. See Create subscription under a plan API for more information on creating a subscription.

Prerequisites

Customer's universally unique identifier (UUID)
Customer's card-on-file details

Steps

Send a POST request to the recurring/v1/plans/{planId}/subscriptions endpoint, including the planId parameter.
Set the Authorization header as your OAuth-generated access_token.
Note the subscriptionId from the response to edit or delete the subscription.

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

Request body parameters

Field	Description	Required / Optional
`startDate`	Start date of the subscription plan in ISO-8601 format. For example, September 7, 2023, displays as 20230907 or with delimiters as 2023-09-07. Time displays in hours, minutes, and seconds, as 12:07:22.	Optional
`collectionMethod`	Method for collecting payment. Currently, `CHARGE_AUTOMATICALLY` is the only method allowed.	Required
`endDate`	End date of the subscription plan in ISO-8601 format.	Optional
`softDescriptor`	Information about the business that processed the charge. See Set soft descriptors.	Optional
`note`	Subscription note. If available, it overrides the plan's note test.	Optional
`tipAmount`	Tip amount. If available, it overrides the plan's amount.	Optional
`amount`	Amount of the subscription. If available, it overrides the plan's amount.	Optional
`active`	Indicates whether the subscription is currently active. Values: - True - False	Optional
`taxRateUuids`	Universally unique identifiers (UUIDs) of the tax rate. If available, it overrides the plan's subscription. Length: Maximum length of combined UUIDs is more than 255 characters.	Optional
`customerId`	Customer identifier (ID).	Required

Sample request and response

curl --request POST \ 
  --url 'https://sandbox.dev.clover.com/recurring/v1/plans/{planId}/subscriptions' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'X-Clover-Merchant-Id: {mId}'
  --header 'content-Type: application/json' \
  --data-raw '{
    "customerId" : "{customerId}",
    "collectionMethod" : "CHARGE_AUTOMATICALLY",
    "startDate": "2021-12-24T12:08:56.235-0700",
    "endDate": "2022-12-24T12:08:56.235-0700",
    "softDescriptor": { "dbaName": "ccc" },
    "taxRateUuids": [ "1ABC2DE3F4GHI", "2ABC4DE6F8JKL" ],
    "tipAmount": 7
}'

{
  "id": "{subscriptionId}",
  "customerUuid": "{customerId}",
  "collectionMethod": "CHARGE_AUTOMATICALLY",
  "active": true,
  "tipAmount": 7,
  "amount": 200,
  "total": 200,
  "note": "This is a note",
  "softDescriptor": {
    "dbaName": "ccc"
  },
  "taxRateUuids": [
    "1ABC2DE3F4GHI",
    "2ABC4DE6F8JKL"
  ],
  "startDate": "2021-12-24@19:08:56.235+0000",
  "endDate": "2022-12-24@19:08:56.235+0000",
  "createdTime": "2021-12-03@22:04:15.896+0000",
  "modifiedTime": "2021-12-03@22:04:15.900+0000",
  "plan": {
    "name": "Recurring_plan 2",
    "amount": 200,
    "active": false,
    "interval": "MONTH",
    "intervalCount": 1,
    "note": "This is a note",
    "createdTime": "2021-10-16@17:39:08.000+0000",
    "modifiedTime": "2021-10-18@23:06:58.000+0000",
    "id": "{planId}",
   "merchantId": "A1B2C3D4EFG56",
  "developerAppId": "A1BCD2EFG34HI", 
    "object": "plan"
  },
  "object": "subscription"
}

Retrieve a subscription

You can view only the subscriptions that you created. See the Get subscription API for more information.

Prerequisites

Customer's universally unique identifier (UUID)
Customer's card-on-file details

Steps

Send a GET request to the recurring/v1/subscriptions/{subscriptionId} endpoint, including the subscriptionId path 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
`subscriptionId`	Universally unique identifier (UUID) of a subscription in a plan.	Required

Sample request and response

curl --request GET \
  --url 'https://sandbox.dev.clover.com/recurring/v1/subsriptions/{subscriptionId}' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'content-Type: application/json' \
}'

{
  "id": "{subscriptionId}",
  "customerUuid": "{customerUuid}",
  "collectionMethod": "CHARGE_AUTOMATICALLY",
  "active": false,
  "amount": 200,
  "total": 200,
  "note": "This is a note",
  "additionalCharges": [],
  "startDate": "2021-10-21@21:08:04.000+0000",
  "createdTime": "2021-10-21@21:08:04.000+0000",
  "modifiedTime": "2021-10-21@21:08:04.000+0000",
  "plan": {
    "name": "Recurring_plan 2",
    "amount": 200,
    "active": false,
    "interval": "MONTH",
    "intervalCount": 1,
    "note": "This is a note",
    "createdTime": "2021-10-16@17:39:08.000+0000",
    "modifiedTime": "2021-10-18@23:06:58.000+0000",
    "id": "{planId}",
    "merchantId": "{mId}",
    "developerAppId": "{deAppId}",
    "object": "plan"
  },
  "object": "subscription"
}

Edit a subscription

You can edit the subscriptions that you created. See the Edit a subscription API for more information. Subscription changes only impact invoices that are created after the subscription changes are made.

🚧
Important
If the customer payment method changes, you must revoke the existing card-on-file (COF) and add a new one. See Save a card for future transactions.

Prerequisites

Customer's universally unique identifier (UUID)
Customer's card-on-file details

Steps

Send a PUT request to the recurring/v1/subscriptions/{subscriptionId} endpoint, including the subscriptionId path 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
`subscriptionId`	Universally unique identifier (UUID) of a subscription in a plan.	Required

Editable fields

Field	Editable?
`active`	Yes
`amount`	Yes
`note`	Yes
`taxRateUuids`	Yes
`startDate`	Yes Note: Only a future subscription's start date is editable.
`endDate`	Yes

Sample request and response

curl --request PUT \
  --url 'https://sandbox.dev.clover.com/recurring/v1/subsriptions/{subscriptionId}' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'content-Type: application/json' \
  --data-raw '{
    "note" : "This is a revised note"
}'

{
  "id": "{subscriptionId}",
  "customerUuid": "{customerUuid}",
  "collectionMethod": "CHARGE_AUTOMATICALLY",
  "active": true,
  "amount": 100,
  "total": 100,
  "note": "This is a revised note",
  "additionalCharges": [],
  "startDate": "2021-10-15@22:40:24.000+0000",
  "lastRunDate": "2021-11-13@00:00:03.000+0000",
  "createdTime": "2021-10-15@22:40:24.000+0000",
  "modifiedTime": "2021-12-06@14:42:59.291+0000",
  "plan": {
    "name": "API Plan 001",
    "amount": 100,
    "active": true,
    "interval": "MONTH",
    "intervalCount": 1,
    "note": "This is a note",
    "createdTime": "2021-10-15@22:31:56.000+0000",
    "modifiedTime": "2021-10-15@22:31:56.000+0000",
    "id": "{planId}",
  "merchantId": "A1B2C3D4EFG56",
  "developerAppId": "A1BCD2EFG34HI",
    "object": "plan"
  },
  "object": "subscription"
}

Cancel a subscription

You can only cancel subscriptions that you created. See Delete subscription for more information on deleting a subscription.

Prerequisites

Customer's universally unique identifier (UUID)
Customer's card-on-file details

Steps

Send a PUT request to the recurring/v1/subscriptions/{subscriptionId} endpoint, including the subscriptionId path 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
`subscriptionId`	Universally unique identifier (UUID) of a subscription in a plan.	Required

Sample request and response

curl --request PUT \
  --url 'https://sandbox.dev.clover.com/recurring/v1/subsriptions/{subscriptionId}' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'content-Type: application/json' \
  --data-raw '{
    "active" : "false" 
}'

{
  "id": "{subscriptionId}",
  "customerUuid": "{customerUuid}",
  "collectionMethod": "CHARGE_AUTOMATICALLY",
    "active": false,
  "amount": 100,
  "total": 100,
  "note": "This is a note",
  "additionalCharges": [],
  "startDate": "2021-10-18@19:27:16.000+0000",
  "lastRunDate": "2021-11-16@00:00:01.000+0000",
  "createdTime": "2021-10-18@19:27:16.000+0000",
  "modifiedTime": "2021-12-06@14:54:00.973+0000",
  "plan": {
    "name": "API Plan 001",
    "amount": 100,
    "active": true,
    "interval": "MONTH",
    "intervalCount": 1,
    "note": "This is a note",
    "createdTime": "2021-10-15@22:31:56.000+0000",
    "modifiedTime": "2021-10-15@22:31:56.000+0000",
    "id": "{planId}",
 "merchantId": "A1B2C3D4EFG56",
  "developerAppId": "A1BCD2EFG34HI",
    "object": "plan"
  },
  "object": "subscription"
}

Work with the Subscriptions API

Create a subscription

Prerequisites

Steps

Required header parameters

Required path parameters

Request body parameters

Sample request and response

Retrieve a subscription

Prerequisites

Steps

Required header parameters

Required path parameters

Sample request and response

Edit a subscription

Prerequisites

Steps

Required header parameters

Required path parameters

Editable fields

Sample request and response

Cancel a subscription

Prerequisites

Steps

Required header parameters

Required path parameters

Sample request and response

See also