Recurring Payment APIs - Configure subscriptions
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 therecurring/v1/plans/{planId}/subscriptions
endpoint, including theplanId
parameter. - Set the
Authorization
header as your OAuth-generatedaccess_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 therecurring/v1/subscriptions/{subscriptionId}
endpoint. - Set the
Authorization
header as your OAuth-generatedaccess_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/subscriptions/{subscriptionId}' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {access_token}' \
--header 'X-Clover-Merchant-Id: {mId}' \
--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"
}
Retrieve all subscriptions
You can view the list of all subscriptions for a merchant. See the Get all subscriptions API for more information.
Steps
- Send a
GET
request to therecurring/v1/subscriptions
endpoint, including thesubscriptionId
path parameter. - Set the
Authorization
header as your OAuth-generatedaccess_token
.
Required header parameters
Field | Description | Required/Optional |
---|---|---|
Authorization | Bearer token | Required |
X-Clover-Merchant-Id | Clover merchant identifier (mId) | Required |
Sample request and response
curl --request GET \
--url 'https://sandbox.dev.clover.com/recurring/v1/subscriptions' \
--header 'X-Clover-Merchant-Id: {mId}'\
--header 'accept: application/json' \
--header 'Authorization: Bearer {access_token}' \
[
{
"id": "{subscriptionId}",
"customerUuid": "{customerUuid}",
"collectionMethod": "CHARGE_AUTOMATICALLY",
"active": true,
"amount": 212,
"additionalCharges": [],
"startDate": "2023-12-16T00:00:00.000+0000",
"lastRunDate": "2023-12-16T00:00:04.000+0000",
"createdTime": "2023-12-15T11:22:26.000+0000",
"modifiedTime": "2023-12-16T00:11:03.000+0000",
"plan": {
"name": "tete",
"amount": 212,
"active": true,
"interval": "WEEK",
"intervalCount": 2,
"createdTime": "2023-12-15T11:20:17.000+0000",
"modifiedTime": "2023-12-15T11:20:17.000+0000",
"id": "KA5KQNVR9B8JT",
"merchantId": "{mId}"
"developerAppId": "{deAppId}",
"object": "plan"
},
"object": "subscription"
},
{
"id": "{subscriptionId}",
"customerUuid": "{customerUuid}",
"collectionMethod": "CHARGE_AUTOMATICALLY",
"active": true,
"amount": 21,
"additionalCharges": [],
"startDate": "2023-11-21T00:00:00.000+0000",
"lastRunDate": "2023-11-21T01:00:28.000+0000",
"createdTime": "2023-11-20T09:42:09.000+0000",
"modifiedTime": "2023-11-21T01:04:13.000+0000",
"plan": {
"name": "plann",
"amount": 21,
"active": true,
"interval": "YEAR",
"intervalCount": 2,
"createdTime": "2023-11-20T09:18:23.000+0000",
"modifiedTime": "2023-11-20T09:18:23.000+0000",
"id": "KGAK0626DY5YT",
"merchantId": "{mId}",
"developerAppId": "{deAppId}",
"object": "plan"
},
"object": "subscription"
},
{
"id": "{subscriptionId}",
"customerUuid": "{customerUuid}",
"collectionMethod": "CHARGE_AUTOMATICALLY",
"active": true,
"amount": 21,
"additionalCharges": [],
"startDate": "2023-11-21T09:18:23.000+0000",
"endDate": "2024-11-20T09:18:23.000+0000",
"lastRunDate": "2023-11-21T01:00:28.000+0000",
"createdTime": "2023-11-20T09:22:05.000+0000",
"modifiedTime": "2023-11-21T01:02:53.000+0000",
"plan": {
"name": "plann",
"amount": 21,
"active": true,
"interval": "YEAR",
"intervalCount": 2,
"createdTime": "2023-11-20T09:18:23.000+0000",
"modifiedTime": "2023-11-20T09:18:23.000+0000",
"id": "{subscriptionId}",
"merchantId": "{mId}",
"developerAppId": "{deAppId}",
"object": "plan"
},
"object": "subscription"
},
{
"id": "{subscriptionId}",
"customerUuid": "{customerUuid}",
"collectionMethod": "CHARGE_AUTOMATICALLY",
"active": true,
"amount": 214,
"additionalCharges": [],
"startDate": "2023-11-15T00:00:00.000+0000",
"lastRunDate": "2023-12-12T01:00:02.000+0000",
"createdTime": "2023-11-14T08:49:43.000+0000",
"modifiedTime": "2023-12-12T01:00:11.000+0000",
"plan": {
"name": "plan07",
"amount": 214,
"active": true,
"interval": "MONTH",
"intervalCount": 1,
"createdTime": "2023-11-01T05:06:16.000+0000",
"modifiedTime": "2023-11-01T05:06:16.000+0000",
"id": "52YGETCNV8VPG",
"merchantId": "{mId}",
"developerAppId": "{deAppId}",
"object": "plan"
},
"object": "subscription"
},
{
"id": "{subscriptionId}",
"customerUuid": "{customerUuid}",
"collectionMethod": "CHARGE_AUTOMATICALLY",
"active": true,
"amount": 214,
"additionalCharges": [],
"startDate": "2023-11-02T00:00:00.000+0000",
"lastRunDate": "2023-11-29T00:01:10.000+0000",
"createdTime": "2023-11-01T05:07:42.000+0000",
"modifiedTime": "2023-11-29T00:09:29.000+0000",
"plan": {
"name": "plan07",
"amount": 214,
"active": true,
"interval": "MONTH",
"intervalCount": 1,
"createdTime": "2023-11-01T05:06:16.000+0000",
"modifiedTime": "2023-11-01T05:06:16.000+0000",
"id": "52YGETCNV8VPG",
"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 therecurring/v1/subscriptions/{subscriptionId}
endpoint, including thesubscriptionId
path parameter. - Set the
Authorization
header as your OAuth-generatedaccess_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 therecurring/v1/subscriptions/{subscriptionId}
endpoint, including thesubscriptionId
path parameter. - Set the
Authorization
header as your OAuth-generatedaccess_token
. - Set the
"Active":
field tofalse
.
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"
}
See also
Updated 6 months ago