Clover Invoicing API Tutorial (draft)

Merchants can use Clover's Invoicing APIs to get paid by customers. An invoice can be a "one time" invoice or a recurring invoice sent on a regular basis, such as a subscription. Once a subscription is created, Clover's invoicing APIs will send out a recurring invoice.

Merchants can use the Invoicing Checkout Service API to create an invoice in the Clover database. Once created, an email is sent automatically to the targeted customer with a link for the customer to use to make a payment. Merchants are then notified automatically when a customer pays an invoice. Merchants can also use the Invoice Manager app on their Clover merchant dashboard to view the status of each invoice.

Clover processes invoice payments using the fully secure PCI-compliant hosted checkout page, which can be customized by merchants.

🚧

IMPORTANT

The Clover Recurring Payments API, the Clover Invoicing Checkout Service API, and the recurring payments apps are not for use with HIPAA merchants.

Invoicing tutorials

Creating an invoice

To create an invoice, send a POST request to the invoicingcheckoutservice/v1/invoices endpoint. Set the Authorization header as your OAuth-generated access_token.

Required header parameters:

  • X-Clover-Merchant-Id

Request body fields

Field

Description

Required / Optional

amount

Invoice amount

required

dueDate

Date invoice is due

optional

customerFirstName

Customer first name

optional

customerLastName

Customer last name

optional

customerEmailAddress

Customer email address

required

customerPhoneNumber

Customer phone number

optional

title

Invoice title

optional

notes

Note text

optional

Sample request and response

curl  --request POST \
  --url 'https://sandbox.dev.clover.com/invoicingcheckoutservice/v1/invoices' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access_token}' \
  --header 'X-Clover-Merchant-Id: {mId}' \
  --header 'content-Type: application/json' \
  --data-raw '{
    "customerFirstName": "John",
    "customerLastName": "Doe",
    "customerEmailAddress": "[email protected]",
    "customerPhoneNumber": "6502107888",
    "amount": 1000,
    "notes": "This is test note"
}
{
  "id": "{id}",
  "customerUuid": "{customerUuid}",
  "amount": 1000,
  "orders": [
    {
      "id": "ZYG47EM0RC3AR"
    }
  ],
  "merchantUuid": "{mId}",
  "collectionMethod": "SEND_INVOICE",
  "status": "PENDING",
  "dueTime": "[email protected]:40:02.908+0000",
  "expirationTime": "[email protected]:40:02.908+0000",
  "timelines": [
    {
      "status": "CREATED",
      "paymentStatus": "UNPAID",
      "reminderCount": 1,
      "createdTime": "[email protected]:40:03.192+0000"
    },
    {
      "status": "NOTIFIED",
      "paymentStatus": "UNPAID",
      "reminderCount": 1,
      "createdTime": "[email protected]:40:03.266+0000"
    }
  ],
  "checkoutSession": {
    "id": "4a882db3-651d-428e-825f-638fd4ef21e0",
    "status": "UNPAID",
    "sessionDetails": {
      "merchant": {
        "name": "Test Merchant 1",
        "ownerId": "15FHQCZQC1JNP",
        "ownerEmail": "[email protected]",
        "logos": {
          "elements": []
        },
        "properties": {
          "defaultCurrency": "USD"
        },
        "id": "{mId}"
      },
      "shoppingCart": {
        "lineItems": [],
        "total": 1000
      },
      "customer": {
        "firstName": "FirstName",
        "lastName": "LastName",
        "emailAddresses": {
          "elements": [
            {
              "emailAddress": "[email protected]"
            }
          ]
        },
        "phoneNumbers": {
          "elements": [
            {
              "phoneNumber": "4083216789"
            }
          ]
        }
      },
      "metaData": {}
    },
    "merchantUuid": "{mId}",
    "expirationTime": "[email protected]:40:02.908+0000",
    "createdTime": "[email protected]:40:03.194+0000",
    "modifiedTime": "[email protected]:40:03.197+0000"
  },
  "createdTime": "[email protected]:40:03.185+0000",
  "modifiedTime": "[email protected]:40:03.185+0000"
}

Note the invoice id that is returned for future operations.

📘

NOTE

If you create a one-time invoice and do not specify a due date in the request, then the due date will be the invoice creation date, plus seven days. If you send a due date in the request, then that is the invoice due date.

Sample customer invoice

The customer clicks the Pay (amount) link to pay the invoice.

After paying an invoice, the customer receives a receipt and the merchant is notified that the invoice was paid.

Retrieving invoices

To retrieve an invoice, send a GET request to the invoicingcheckoutservice/v1/invoices/ endpoint. Set the Authorization header as your OAuth-generated access_token.

Required header parameters:

  • X-Clover-Merchant-Id

Sample response

The response returns a list of the merchant's subscriptions and subscription details.

[
  {
    "id": "{id}",
    "customer": {
      "id": "{id}",
      "firstName": "John",
      "lastName": "Doe",
      "emailAddresses": {
        "elements": [
          {
            "emailAddress": "[email protected]"
          }
        ]
      },
      "phoneNumbers": {
        "elements": [
          {
            "phoneNumber": "4085551965"
          }
        ]
      }
    },
    "amount": 1000,
    "dueTime": "[email protected]:56:09.000+0000",
    "sentTime": "[email protected]:56:09.000+0000",
    "status": "OVERDUE",
    "collectionMethod": "SEND_INVOICE"
  },
  ...
  {
    "id": "{id}",
    "customer": {
      "id": "{id}",
      "firstName": "John",
      "lastName": "Doe",
      "emailAddresses": {
        "elements": [
          {
            "id": "2SXZ55BB5HV7E",
            "emailAddress": "[email protected]"
          }
        ]
      }
    },
    "subscriptionUuid": "BYPVM7S9Y37D8",
    "amount": 100,
    "dueTime": "[email protected]:56:09.000+0000",
    "sentTime": "[email protected]:56:09.000+0000",
    "status": "PAID",
    "collectionMethod": "CHARGE_AUTOMATICALLY"
  },
  ...
]

Editing an invoice

You can edit invoices if they have not been paid yet. To edit an invoice, send a PUT request to the invoicingcheckoutservice/v1/invoices/{id} endpoint (where id is the invoice id). Set the Authorization header as your OAuth-generated access_token.

Required path parameters:

  • id (invoice id)

Required header parameters:

  • X-Clover-Merchant-Id

Editable fields

Field

Editable? (Y/N)

amount

Y

dueDate

Y

customerFirstName

N

customerLastName

N

customerEmailAddress

N

customerPhoneNumber

N

notes

Y

deletedTime

N

Sample request and response

curl  --request PUT \
  --url 'https://sandbox.dev.clover.com/invoicingcheckoutservice/v1/invoices/{id}' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access_token}' \
  --header 'X-Clover-Merchant-Id: {mId}' \
  --header 'content-Type: application/json' \
  --data-raw '{
    "amount" : 400
}'
{
  "id": "{id}",
  "customerUuid": "{customerUuid}",
  "amount": 400,
  "orders": [
    {
      "id": "45G1MGYAKQ8DR"
    }
  ],
  "merchantUuid": "{mId}",
  "collectionMethod": "SEND_INVOICE",
  "status": "OVERDUE",
  "dueTime": "[email protected]:48:46.000+0000",
  "expirationTime": "[email protected]:48:46.000+0000",
  "timelines": [
    {
      "status": "CREATED",
      "paymentStatus": "UNPAID",
      "reminderCount": 1,
      "remindedTime": "[email protected]:48:47.000+0000",
      "createdTime": "[email protected]:48:46.000+0000"
    },
    {
      "status": "NOTIFIED",
      "paymentStatus": "UNPAID",
      "reminderCount": 1,
      "remindedTime": "[email protected]:48:47.000+0000",
      "createdTime": "[email protected]:48:47.000+0000"
    }
  ],
  "checkoutSession": {
    "id": "5b472535-d18c-45ec-aa72-f940bcbc9845",
    "status": "UNPAID",
    "sessionDetails": {
      "merchant": {
        "name": "Test Merchant 1",
        "ownerId": "{ownerId}",
        "ownerEmail": "[email protected]",
        "logos": {
          "elements": []
        },
        "properties": {
          "defaultCurrency": "USD"
        },
        "id": "{mId}"
      },
      "shoppingCart": {
        "lineItems": [],
        "total": 400
      },
      "customer": {
        "firstName": "FirstName",
        "lastName": "LastName",
        "emailAddresses": {
          "elements": [
            {
              "emailAddress": "[email protected]"
            }
          ]
        },
        "phoneNumbers": {
          "elements": [
            {
              "phoneNumber": "4085981116"
            }
          ]
        }
      },
      "metaData": {}
    },
    "merchantUuid": "{mId}",
    "expirationTime": "[email protected]:48:46.000+0000",
    "createdTime": "[email protected]:48:46.000+0000",
    "modifiedTime": "[email protected]:34:27.000+0000"
  },
  "createdTime": "[email protected]:48:46.000+0000",
  "modifiedTime": "[email protected]:48:47.000+0000"
}

Deleting an invoice

You can delete invoices if they have not already been paid. To delete an invoice, send a PUT request to the invoicingcheckoutservice/v1/invoices/{id} endpoint (where id is the invoice id. Set the Authorization header as your OAuth-generated access_token.

Required header parameters:

  • X-Clover-Merchant-Id
curl  --request PUT \
  --url 'https://sandbox.dev.clover.com/invoicingcheckoutservice/v1/invoices/{id}' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access_token}' \
  --header 'X-Clover-Merchant-Id: {mId}' \
  --header 'content-Type: application/json' \
  --data-raw '{
    "delete" : true
}'

Related topics


Did this page help you?