Recurring payments - subscription (Draft)
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.
Required path parameters
planId
Required header parameters
X-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.
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.
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.
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"
}
Updated 4 months ago