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

FieldDescriptionRequired / Optional
customerIdCustomer's UUIDrequired
collectionMethodMethod for collecting payment. Currently, CHARGE_AUTOMATICALLY is the only method allowed.required
startDateStart date of subscription; must in the future, Default is the next day.optional
endDateEnd date of subscription.optional
softDescriptorInformation about the business that processed the charge.
See Setting soft descriptors.
optional
amountAmount, If passed then it will override the plan's amount.optional
tipAmountTip amount, If passed then it will override the plan's tip amount.optional
noteNote text, If passed then it will override the plan's note test.optional
taxRateUuidsTax rate UUID, If passed then it will override the plan's tax rate UUIDs.optional

📘

NOTE

Currently, CHARGE_AUTOMATICALLY is 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

FieldEditable? (Y/N)
activeY
amountY
noteY
taxRateUuidsY
startDateY (Note: Only a future subscription's start date is editable.)
endDateY

🚧

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"
}

Did this page help you?