Recurring Payment APIs - Configuring Subscriptions
Recurring Payments and Subscriptions APIs includes Subscription APIs. Merchants can use these APIs to create subscriptions for plans after they are created. Each subscription associates a customer to a plan to identify who should be billed for the subscription and with what payment method (that is, the credit card on file), as well as the amount and dates on which a scheduled payment should be taken. The subscription then generates an invoice for each payment.
Important
There will be five attempts to pay an invoice once a subscription is configured. If all attempts fail, the subscription is deactivated and no other attempts to pay for the invoice will be made. In addition, if it is determined that the customer data is invalid (for example, no credit card on file), the subscription will be automatically deactivated.
Creating a subscription
NOTE
Before you create a subscription, ensure that you have the customer's UUID and the customer's card on file.
To create a subscription, send a POST request to the recurring/v1/plans/{planId}/subscriptions endpoint. Include the planId path parameter. Set the Authorization header as your OAuth-generated access_token.
Refer to the Create subscription under a plan API for more information on creating a subscription.
Required path parameters
planId
Required header parameters
authorizationX-Clover-Merchant-Id
Request body fields
| Field | Description | Required / Optional |
|---|---|---|
customerId | Customer's UUID | required |
collectionMethod | Method for collecting payment. Currently, CHARGE_AUTOMATICALLY is the only method allowed. | required |
startDate | Start date of subscription; must in the future, Default is the next day. | optional |
endDate | End date of subscription. | optional |
softDescriptor | Information about the business that processed the charge. See Setting soft descriptors. | optional |
amount | Amount, If passed then it will override the plan's amount. | optional |
tipAmount | Tip amount, If passed then it will override the plan's tip amount. | optional |
note | Note text, If passed then it will override the plan's note test. | optional |
taxRateUuids | Tax rate UUID, If passed then it will override the plan's tax rate UUIDs. | optional |
NOTE
Currently,
CHARGE_AUTOMATICALLYis the only collection method allowed.
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": [ "KE26VXP1TNE8Y", "KE26VXP1TNE8Z" ],
"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": [
"KE26VXP1TNE8Y",
"KE26VXP1TNE8Z"
],
"startDate": "[email protected]:08:56.235+0000",
"endDate": "[email protected]:08:56.235+0000",
"createdTime": "[email protected]:04:15.896+0000",
"modifiedTime": "[email protected]:04:15.900+0000",
"plan": {
"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"
},
"object": "subscription"
}
Note the subscriptionId that was returned in the response for future operations.
Retrieving a subscription
You can view only subscriptions that you created. Refer to the Get subscription API for more information on retrieving a subscription.
To retrieve a subscription, send a GET request to the recurring/v1/subscriptions/{subscriptionId} endpoint. Include the subscriptionId path parameter. Set the Authorization header as your OAuth-generated access_token.
Required path parameters
subscriptionId
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": "[email protected]:08:04.000+0000",
"createdTime": "[email protected]:08:04.000+0000",
"modifiedTime": "[email protected]:08:04.000+0000",
"plan": {
"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": "{deAppId}",
"object": "plan"
},
"object": "subscription"
}
Editing a subscription
You can edit only subscriptions that you created. Refer to the Edit a subscription API for more information on editing a subscription.
To edit a subscription, send a PUT request to the recurring/v1/subscriptions/{subscriptionId} endpoint. Include the subscriptionId path parameter. Set the Authorization header as your OAuth-generated access_token.
NOTE
Subscription changes only impact invoices that are created after the subscription changes are made.
Required path parameters
subscriptionId
Editable fields
| Field | Editable? (Y/N) |
|---|---|
active | Y |
amount | Y |
note | Y |
taxRateUuids | Y |
startDate | Y (Note: Only a future subscription's start date is editable.) |
endDate | Y |
IMPORTANT
If the customer payment method changes, you must revoke the existing card on file and add a new one.
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": "[email protected]:40:24.000+0000",
"lastRunDate": "[email protected]:00:03.000+0000",
"createdTime": "[email protected]:40:24.000+0000",
"modifiedTime": "[email protected]:42:59.291+0000",
"plan": {
"name": "API Plan 001",
"amount": 100,
"active": true,
"interval": "MONTH",
"intervalCount": 1,
"note": "This is a note",
"createdTime": "[email protected]:31:56.000+0000",
"modifiedTime": "[email protected]:31:56.000+0000",
"id": "{planId}",
"merchantId": "{mId}",
"developerAppId": "{devAppId}",
"object": "plan"
},
"object": "subscription"
}
Canceling a subscription
You can cancel only subscriptions that you created. Refer to Delete subscription for more information on deleting a subscription.
To cancel a subscription, send a PUT request to the recurring/v1/subscriptions/{subscriptionId} endpoint. Include the subscriptionId path parameter. Set the Authorization header as your OAuth-generated access_token.
Required path parameters
subscriptionId
Set the Active: field to false.
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": "[email protected]:27:16.000+0000",
"lastRunDate": "[email protected]:00:01.000+0000",
"createdTime": "[email protected]:27:16.000+0000",
"modifiedTime": "[email protected]:54:00.973+0000",
"plan": {
"name": "API Plan 001",
"amount": 100,
"active": true,
"interval": "MONTH",
"intervalCount": 1,
"note": "This is a note",
"createdTime": "[email protected]:31:56.000+0000",
"modifiedTime": "[email protected]:31:56.000+0000",
"id": "{planId}",
"merchantId": "{mId}",
"developerAppId": "{devAppId}",
"object": "plan"
},
"object": "subscription"
}
Related topic
Updated 12 months ago