Release NotesAnnouncementsVideosBlog
Guides

Recurring payments API—Configure subscriptions for plans

North America—United States and Canada

The Recurring Payments API includes two APIs: Plan and Subscription. The Subscriptions API for ecommerce allows merchants to create and manage subscriptions through their Clover Merchant Dashboard. You can use the Subscriptions API to create, retrieve, edit, and cancel and delete subscriptions.

Key features of the Subscriptions API include:

  • Subscription creation—Merchants can create subscriptions that associate customers with specific plans, including details such as customer billing information, card-on-file, scheduled payment amount, start date, and payment intervals.
  • Invoice generation—Subscriptions automatically generate invoices for each scheduled payment.
  • Deactivation on failure—A subscription is deactivated if the customer's invoice payment fails after five attempts. Failures can occur due to invalid or missing customer information or card data.

Before you begin

To create subscriptions, you need a plan and a customer with a credit or debit card saved with the merchant as a card-on-file (COF). COF transactions are payments where cardholders authorize merchants to store their card information for future use. You can use sandbox test cards. Follow these steps to create a COF record:

  1. Generate a test merchant API token or OAuth access token.
  2. Use the public token to generate an Ecommerce API key (PAKMS key). The PAKMS key is used to identify the merchant during card tokenization.
  3. Use the PAKMS key to create a card token. You must have all the required details, such as the card number, card verification value (CVV), and expiration date.
  4. Use the card token as the source to create a COF record for the customer's card.

🚧

IMPORTANT

If the customer payment method changes, you must revoke the existing card-on-file (COF) and add a new one. See ​​Save a card for future transactions.

Prerequisites

Create a subscription

You can define subscriptions for a set of plans to initiate automatic payments.

  1. Send a POST request to recurring/v1/plans/{planId}/subscriptions.
  2. Enter the required information:
  • X-Clover-Merchant-Id—Clover merchant identifier (mId).
  • planId—Unique identifier of a plan.
  • collectionMethod—Method for collecting payment. Currently, CHARGE_AUTOMATICALLY is the only method allowed.
  • customerId—Customer identifier (ID).
  1. Enter optional information, such as:
  • startDate and endDate —Subscription plan date start and end dates in ISO-8601 format.
  • softDescriptor—Information about the business that processed the charge. See Set soft descriptors.

The following, when available for the subscription, override the respective amounts in the plan.

  • tipAmount—Tip amount.
  • amount—Subscription amount.
  • taxRateUuids—Universally unique identifiers (UUIDs) of the tax rate.
  1. Set the Authorization header as Bearer token type, and enter the test API token or OAuth-generated access_token.

In response, a unique subscriptionId is generated. Note the subscription Id to update or delete the subscription later.

Request and response sample—Create a subscription

curl --request POST \
     --url 'https://apisandbox.dev.clover.com/recurring/v1/plans/{planId}/subscriptions' \
     --header 'X-Clover-Merchant-Id: {mId}' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {access_token}' \
     --header 'content-type: application/json' \
     --data '{
          "collectionMethod": "CHARGE_AUTOMATICALLY",
          "customerId": "T5JCD05PKP1NJ",
          "amount": 40
      }'

{
  "id": "Y691A4FTGHAJJ", // subscription ID
  "customerUuid": "T5JCD05PKP1NJ",
  "collectionMethod": "CHARGE_AUTOMATICALLY",
  "active": true,
  "amount": 40,
  "total": 40,
  "startDate": "2025-03-13T00:00:00.000+0000",
  "createdTime": "2025-03-12T07:08:56.191+0000",
  "modifiedTime": "2025-03-12T07:08:56.191+0000",
  "plan": {
    "name": "Weekly plan",
    "amount": 2,
    "active": true,
    "interval": "DAY",
    "intervalCount": 36,
    "createdTime": "2025-03-03T09:34:03.000+0000",
    "modifiedTime": "2025-03-03T09:34:03.000+0000",
    "id": "1KVBJ22PQ7D4R", // plan ID
    "merchantId": "4BAJ37QFP50A1",
    "object": "plan"
  },
  "object": "subscription"
}

View subscriptions

Retrieve a subscription

You can view only the subscriptions that you created.

  1. Send a GET request to recurring/v1/subscriptions/{subscriptionId}.
  2. Enter the required information:
    • X-Clover-Merchant-Id—Clover merchant identifier (mId).
    • subscriptionId—Unique identifier of a subscription in a plan.
  3. Set the Authorization header as Bearer token type, and enter the test API token or OAuth-generated access_token.

Sample request and response—Retrieve a subscription

curl --request GET \
  --url 'https://apisandbox.dev.clover.com/recurring/v1/subscriptions/{subscriptionId}' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'X-Clover-Merchant-Id: {mId}' \

{
  "id": "ENMQQ6KKS09ZJ", // subscription ID
  "customerUuid": "T5JCD05PKP1NJ",
  "collectionMethod": "CHARGE_AUTOMATICALLY",
  "active": true,
  "amount": 2,
  "total": 2,
  "additionalCharges": [],
  "startDate": "2025-03-12T00:00:00.000+0000",
  "createdTime": "2025-03-11T10:45:16.000+0000",
  "modifiedTime": "2025-03-11T10:45:16.000+0000",
  "plan": {
    "name": "Weekly plan",
    "amount": 2,
    "active": true,
    "interval": "DAY",
    "intervalCount": 36,
    "createdTime": "2025-03-03T09:34:03.000+0000",
    "modifiedTime": "2025-03-03T09:34:03.000+0000",
    "id": "1KVBJ22PQ7D4R", // plan ID
    "merchantId": "4BAJ37QFP50A1",
    "object": "plan" 
  },
  "object": "subscription"
}

Retrieve all subscriptions

You can view the list of all subscriptions for a merchant.

  1. Send a GET request to recurring/v1/subscriptions.
  2. Enter the required information: X-Clover-Merchant-Id—Clover merchant identifier (mId).
  3. Set the Authorization header as Bearer token type, and enter the test API token or OAuth-generated access_token.

Sample request and response—Retrieve all subscriptions for a merchant

curl --request GET \
  --url 'https://apisandbox.dev.clover.com/recurring/v1/subscriptions' \
  --header 'X-Clover-Merchant-Id: {mId}' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer {access_token}'

[
  {
    "id": "22ZY7VY0KFT3M", //subscription ID
    "customerUuid": "T5JCD05PKP1NJ",
    "collectionMethod": "CHARGE_AUTOMATICALLY",
    "active": true,
    "amount": 20,
    "additionalCharges": [],
    "startDate": "2025-03-12T00:00:00.000+0000",
    "createdTime": "2025-03-11T10:47:38.000+0000",
    "modifiedTime": "2025-03-11T10:47:38.000+0000",
    "plan": {
      "name": "Weekly plan",
      "amount": 20,
      "active": true,
      "interval": "DAY",
      "intervalCount": 36,
      "createdTime": "2025-03-03T09:34:03.000+0000",
      "modifiedTime": "2025-03-03T09:34:03.000+0000",
      "id": "1KVBJ22PQ7D4R", // plan ID
      "merchantId": "4BAJ37QFP50A1",
      "object": "plan"
    },
    "object": "subscription"
  },
  {
    "id": "HB6BJD640AQAP", //subscription ID
    "customerUuid": "T5JCD05PKP1NJ",
    "collectionMethod": "CHARGE_AUTOMATICALLY",
    "active": true,
    "amount": 20,
    "additionalCharges": [],
    "startDate": "2025-03-12T00:00:00.000+0000",
    "createdTime": "2025-03-11T10:46:04.000+0000",
    "modifiedTime": "2025-03-11T10:46:04.000+0000",
    "plan": {
      "name": "Weekly plan",
      "amount": 0,
      "active": true,
      "interval": "DAY",
      "intervalCount": 36,
      "createdTime": "2025-03-03T09:34:03.000+0000",
      "modifiedTime": "2025-03-03T09:34:03.000+0000",
      "id": "1KVBJ22PQ7D4R", // plan ID
      "merchantId": "4BAJ37QFP50A1",
      "object": "plan"
    },
    "object": "subscription"
  },

Retrieve subscriptions under a plan

You can view all subscriptions associated with a plan.

  1. Send a GET request to /recurring/v1/plans/{planId}/subscriptions.
  2. Enter the required information:
  • X-Clover-Merchant-Id—Clover merchant identifier (mId).
  • planId—Unique identifier of a plan.
  1. Set the Authorization header as Bearer token type, and enter the test API token or OAuth-generated access_token.

Sample request and response—Retrieve subscriptions under a plan

curl --request GET \
     --url 'https://apisandbox.dev.clover.com/recurring/v1/plans/{planId}/subscriptions' \
     --header 'X-Clover-Merchant-Id: {mId}' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer {access_token}'

[
  {
    "id": "22ZY7VY0KFT3M", // subscription ID
    "customerUuid": "T5JCD05PKP1NJ",
    "collectionMethod": "CHARGE_AUTOMATICALLY",
    "active": true,
    "amount": 20,
    "additionalCharges": [],
    "customer": {
      "id": "T5JCD05PKP1NJ",
      "firstName": "Test",
      "lastName": "Cust",
      "emailAddresses": {
        "elements": [
          {
            "id": "BNXNZCJTW4ZAJ", 
            "emailAddress": "[email protected]"
          }
        ]
      },
      "cards": {
        "elements": [
          {
            "id": "BS55G8EK5ZWJR",
            "first6": "400001",
            "last4": "1111",
            "expirationDate": "1027",
            "cardType": "VISA",
            "tokenType": "CTOKEN",
            "additionalInfo": {
              "isPurchaseCard": "false",
              "fundingType": "CREDIT"
            }
          }
        ]
      }
    },
    "startDate": "2025-03-12T00:00:00.000+0000",
    "createdTime": "2025-03-11T10:47:38.000+0000",
    "modifiedTime": "2025-03-11T10:47:38.000+0000",
    "plan": {
      "name": "Weekly plan",
      "amount": 20,
      "active": true,
      "interval": "DAY",
      "intervalCount": 36,
      "createdTime": "2025-03-03T09:34:03.000+0000",
      "modifiedTime": "2025-03-03T09:34:03.000+0000",
      "id": "1KVBJ22PQ7D4R", // plan ID
      "merchantId": "4BAJ37QFP50A1",
      "object": "plan"
    },
    "object": "subscription"
  },

Update a subscription

You can edit the subscriptions that you created. Subscription changes only impact invoices that are created after the subscription changes are made.

  1. Send a PUT request to recurring/v1/subscriptions/{subscriptionId}.
  2. Enter the required information:
    • X-Clover-Merchant-Id—Clover merchant identifier (mId).
    • subscriptionId—Unique identifier of the subscription.
  3. Enter updated information for the editable fields only, such as: active, amount, note, taxRateUuids, startDate for a future subscription, and endDate.
  4. Set the Authorization header as Bearer token type, and enter the test API token or OAuth-generated access_token.

Sample request and response—Update a subscription

curl --request PUT \
  --url 'https://apisandbox.dev.clover.com/recurring/v1/subscriptions/{subscriptionId}' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "active": true,
    "note": "This is a revised note.",
    "amount": 25
  }'

{
  "id": "HB6BJD640AQAP", // subscription ID
  "customerUuid": "T5JCD05PKP1NJ",
  "collectionMethod": "CHARGE_AUTOMATICALLY",
  "active": true,
  "amount": 25,
  "total": 25,
  "note": "This is a revised note.",
  "additionalCharges": [],
  "startDate": "2025-03-12T00:00:00.000+0000",
  "createdTime": "2025-03-11T10:46:04.000+0000",
  "modifiedTime": "2025-03-11T11:03:49.113+0000",
  "plan": {
    "name": "Weekly plan",
    "amount": 2,
    "active": true,
    "interval": "DAY",
    "intervalCount": 36,
    "createdTime": "2025-03-03T09:34:03.000+0000",
    "modifiedTime": "2025-03-03T09:34:03.000+0000",
    "id": "1KVBJ22PQ7D4R", // plan ID
    "merchantId": "4BAJ37QFP50A1",
    "object": "plan"
  },
  "object": "subscription"
}

Deactivate a subscription

You can only deactivate or cancel subscriptions that you created.

  1. Send a PUT request to the recurring/v1/subscriptions/{subscriptionId}
  2. Enter the required information:
    • X-Clover-Merchant-Id—Clover merchant identifier (mId).
    • subscriptionId —Unique identifier of the subscription.
  3. To deactivate a subscription without deleting it, set the active: parameter to false.
  4. Set the Authorization header as Bearer token type, and enter the test API token or OAuth-generated access_token.

Sample request and response—Deactivate a subscription

curl --request PUT \
     --url 'https://apisandbox.dev.clover.com/recurring/v1/subscriptions/{subscriptionId}' \
     --header 'X-Clover-Merchant-Id: {mId}' \
     --header 'accept: application/json' \
      --header 'authorization: Bearer {access_token}'
     --header 'content-type: application/json' \
     --data '{"active":false}''

{
  "id": "HB6BJD640AQAP", //subscription Id
  "customerUuid": "T5JCD05PKP1NJ",
  "collectionMethod": "CHARGE_AUTOMATICALLY",
  "active": false,
  "amount": 20,
  "total": 20,
  "additionalCharges": [],
  "startDate": "2025-03-12T00:00:00.000+0000",
  "createdTime": "2025-03-11T10:46:04.000+0000",
  "modifiedTime": "2025-03-11T11:02:22.794+0000",
  "plan": {
    "name": "Weekly plan",
    "amount": 20,
    "active": true,
    "interval": "DAY",
    "intervalCount": 36,
    "createdTime": "2025-03-03T09:34:03.000+0000",
    "modifiedTime": "2025-03-03T09:34:03.000+0000",
    "id": "1KVBJ22PQ7D4R", //plan ID
    "merchantId": "4BAJ37QFP50A1",
    "object": "plan"
  },
  "object": "subscription"
}

Delete a subscription

You can delete a subscription that you created.

  1. Send a DELETE request to /recurring/v1/plans/{planId}.
  2. Enter the required information:
    • X-Clover-Merchant-Id—Clover merchant identifier (mId).
    • planId —Unique identifier of the plan.
  3. Set the Authorization header as Bearer token type, and enter the test API token or OAuth-generated access_token.

Sample request and response—Delete a subscription

curl --request DELETE \
     --url 'https://apisandbox.dev.clover.com/recurring/v1/subscriptions/{subscriptionId}' \
     --header 'X-Clover-Merchant-Id: {mId}' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {access_token}'
     --header 'content-type: application/json' \

{
  "id": "22ZY7VY0KFT3M", //subscription ID
  "customerUuid": "T5JCD05PKP1NJ",
  "collectionMethod": "CHARGE_AUTOMATICALLY",
  "active": false,
  "amount": 20,
  "total": 20,
  "additionalCharges": [],
  "startDate": "2025-03-12T00:00:00.000+0000",
  "createdTime": "2025-03-11T10:47:38.000+0000",
  "modifiedTime": "2025-03-11T10:54:49.821+0000",
  "deletedTime": "2025-03-11T10:54:49.629+0000",
  "plan": {
    "name": "Weekly plan",
    "amount": 20,
    "active": true,
    "interval": "DAY",
    "intervalCount": 36,
    "createdTime": "2025-03-03T09:34:03.000+0000",
    "modifiedTime": "2025-03-03T09:34:03.000+0000",
    "id": "1KVBJ22PQ7D4R", //plan ID
    "merchantId": "4BAJ37QFP50A1",
    "object": "plan"
  },
  "object": "subscription"
}

Related topics

Updated 11 days ago