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

  • authorization
  • 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_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. 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


Did this page help you?