Recurring Payment APIs - Configure subscriptions
Recurring Payments and Subscriptions APIs include 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 (COF), 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 are 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 (COF), the subscription is automatically deactivated.
Create 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 | Universally unique identifier (ID) of the customer. | 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 available, it overrides the plan's amount. | optional |
tipAmount | Tip amount. If available, it overrides the plan's amount. | optional |
note | Additional information or note related to the subscription. If available, it overrides will override the plan's note test. | 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 |
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.
Retrieve 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"
}
Edit 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 (COF) 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"
}
Cancel 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"
}
See also
Updated 3 months ago