REST API

Clover provides a REST API for each of its supported markets.

  • United States: https://api.clover.com
  • Europe: https://api.eu.clover.com

In addition, there is a sandbox REST API for use with our Developer Kits and sandbox test merchants:

https://apisandbox.dev.clover.com

You can find a list of supported endpoints in Clover’s REST API Reference. These endpoints accept query parameters in the following format:

[Endpoint URI]?field=value[,additionalValues...]&[additionalQueryStrings...]

Here are some guidelines to follow when using the Clover REST API:

  • Clover’s APIs are only accessible via HTTPS
  • Request and response entities are in JSON
  • All API requests are protected by an OAuth2-derived access token (see the OAuth 2.0 documentation for more information)
  • GET queries made in-browser will also include hyperlinks to the details for each specific object

In this article, we discuss:

Using API Tokens

Requests to the REST API require a merchant ID and an API token. The merchant ID is embedded in the URL that’s used to access the Clover merchant website:

https://apisandbox.dev.clover.com/home/m/[Merchant ID]

 

To retrieve the API token, you must use OAuth in the production environment.

Note

Since the API token request consists of sensitive information about your app, this request does not have CORS support in the production environment. To successfully request an API token, send this request from your app server to the Clover Server. When the Clover Server responds to the request, retrieve the API token from your app server.

Once you have retrieved your API token, you can test Clover’s REST APIs in your app client command line. For testing purposes, we at Clover provide CORS support for such client-side requests. In your request, set the value of the access_token query parameter as your API token.

$ curl -s https://apisandbox.dev.clover.com/v3/merchants/[Merchant ID]/items?access_token={Your API token} | python -mjson.tool

 
When you are making server-side requests to Clover’s REST APIs, use set the value of the Authorization header as Bearer {Your API token}. As a test sample, the following cURL command shows the use of the Authorization header.

$ curl -s https://apisandbox.dev.clover.com/v3/merchants/[Merchant ID]/orders --header "Authorization:Bearer {Your API token}" | python -mjson.tool

Sorting collections

Most JSON responses take the form of collections, which can be sorted by specifying the orderBy query parameter. You can specify multiple fields by separating them with commas.

$ curl -s https://apisandbox.dev.clover.com/v3/merchants/[Merchant ID]/items?orderBy=modifiedTime,price --header "Authorization: Bearer {Your API token}" | python -mjson.tool

{
    "elements": [
        {
            "code": "",
            "defaultTaxRates": false,
            "hidden": false,
            "id": "V33H8XGTZCKNP",
            "isRevenue": true,
            "name": "Item Use",
            "price": 100,
            "priceType": "PER_UNIT",
            "unitName": "hr"
        },
        {
            "code": "",
            "defaultTaxRates": false,
            "hidden": false,
            "id": "EWKZEMNCBQQ9Y",
            "isRevenue": true,
            "name": "Nontax Item",
            "price": 100,
            "priceType": "FIXED",
            "unitName": "oz"
        },
...

 

The default sort order is descending by creation time. You can manually order by ascending or descending by inputting %20ASC or %20DESC, respectively.

$ curl -s https://apisandbox.dev.clover.com/v3/merchants/[Merchant ID]/items?orderBy=modifiedTime%20ASC --header "Authorization: Bearer {Your API token}" | python -mjson.tool

{
  "elements": [ {
      "id": "1CF022RN5TGDM",
      "hidden": false,
      "name": "Pizza Slice",
      "price": 250,
      "priceType": "FIXED",
      "defaultTaxRates": true,
      "cost": 0,
      "isRevenue": true
    }, {
      "id": "SNGFTY41642NY",
      "hidden": false,
      "name": "Pork Rice Bowl with House Salad",
      "price": 1200,
      "priceType": "FIXED",
      "defaultTaxRates": true,
      "cost": 0,
      "isRevenue": true,
      "stockCount": 3
    },
...

Filtering collections

Collections can be filtered with the filter query parameter. The filter parameter supports standard comparison operations, such as =, >=, and !=. Specify multiple filterparameters by joining &filter= statements.

$ curl -s "https://apisandbox.dev.clover.com/v3/merchants/[Merchant ID]/orders?filter=clientCreatedTime>=[unix-time]&filter=clientCreatedTime<=[unix-time]" --header "Authorization: Bearer {Your API token}" | python -mjson.tool

NOTE

The unix-time value of the clientCreatedTime filter refers to unix epoch or unix time in milliseconds. To learn more about or to find the unix time for a specified date, you can find free online solutions, such as EpochConverter.

To determine the parameters that can be filtered for a given method, see the API Reference.

$ curl -s "https://apisandbox.dev.clover.com/v3/merchants/[Merchant ID]/orders?filter=total>1000&filter=payType!=FULL" --header "Authorization: Bearer {Your API token}" | python -mjson.tool

{
    "elements": [
        {
            "clientCreatedTime": 1401286267000,
            "createdTime": 1401286268000,
            "currency": "USD",
            "employee": {
                "id": "QT0DES4CXR572"
            },
            "groupLineItems": true,
            "href": "https://sandbox.dev.clover.com/v3/merchants/[Merchant ID]/orders/8WAD6KV8D90KR",
            "id": "8WAD6KV8D90KR",
            "isVat": false,
            "manualTransaction": false,
            "modifiedTime": 1401286463000,
            "payType": "SPLIT_CUSTOM",
            "state": "locked",
            "taxRemoved": false,
            "testMode": false,
            "total": 5293
        },
        {
            "clientCreatedTime": 1400106245000,
            "createdTime": 1400106245000,
            "currency": "USD",
            "employee": {
                "id": "QT0DES4CXR572"
            },
            "groupLineItems": true,
            "href": "https://sandbox.dev.clover.com/v3/merchants/[Merchant ID]/orders/0S0JJYG231462",
            "id": "0S0JJYG231462",
            "isVat": false,
            "manualTransaction": false,
            "modifiedTime": 1400106366000,
            "payType": "SPLIT_CUSTOM",
            "state": "locked",
            "taxRemoved": false,
            "testMode": false,
            "total": 2829
        }
    ],
    "href": "https://apisandbox.dev.clover.com/v3/merchants/[Merchant ID]/orders?filter=total%3E1000&filter=payType!%3DFULL&limit=100"
}

Pagination

The offset and limit query parameters can be used to page through larger results. The default limit is 100 elements, and the hard limit is 1000.

NOTE

The clientCreatedTime filter value refers to unix epoch or unix time in milliseconds. To learn more about or to find the unix time for a specified date, you can find free online solutions, such as EpochConverter.

$ curl -s "https://apisandbox.dev.clover.com/v3/merchants/[Merchant ID]/orders?offset=10&limit=1" --header "Authorization: Bearer {Your API token}" | python -mjson.tool
{
    "elements": [
        {
            "clientCreatedTime": 1403294602000,
            "createdTime": 1403294602000,
            "currency": "USD",
            "employee": {
                "id": "5PYBJET35969W"
            },
            "groupLineItems": true,
            "href": "https://sandbox.dev.clover.com/v3/merchants/[Merchant ID]/orders/6Z3JQ98FQ8B40",
            "id": "6Z3JQ98FQ8B40",
            "isVat": false,
            "manualTransaction": false,
            "modifiedTime": 1403295698000,
            "state": "open",
            "taxRemoved": false,
            "testMode": false,
            "total": 1743
        }
    ],
    "href": "https://apisandbox.dev.clover.com/v3/merchants/[Merchant ID]/orders?offset=10&limit=1"
}

Field Expansion

Fields can be expanded with the expand query parameter. You can see what parameters are expandable for a given method in the API Reference.

Example:

$ curl -s "https://apisandbox.dev.clover.com/v3/merchants/[Merchant ID]/items/[Item ID]?expand=categories" --header "Authorization: Bearer {Your API token}" | python -mjson.tool

{
    "id": "Z0EPYQ2R5TQ5Y",
    "hidden": false,
    "name": "Bangers and Mash",
    "alternateName": "",
    "code": "024463061095",
    "price": 150,
    "priceType": "FIXED",
    "defaultTaxRates": true,
    "unitName": "",
    "isRevenue": true,
    "categories": {
        "elements": [
            {
                "id": "MHH9XR2YXZ4T4",
                "name": "Food",
                "sortOrder": "0"
            }
        ]
    }
}

 

You can expand multiple fields by separating them with commas.

IMPORTANT

Please limit expansions to a maximum of three fields per API call. This will allow us to continually provide quick API response times and reduce undue load.

$ curl -s "https://apisandbox.dev.clover.com/v3/merchants/[Merchant ID]/items/[Item ID]?expand=tags%2Ccategories" --header "Authorization: Bearer {Your API token}" | python -mjson.tool

{
    "cost": 0,
    "defaultTaxRates": true,
    "hidden": false,
    "id": "AK5ESN5YR8YWY",
    "isRevenue": true,
    "modifiedTime": 1432671908000,
    "name": "Pizza",
    "price": 1499,
    "priceType": "FIXED",
    "tags": {
        "elements": [
            {
                "id": "HYQ5Z74KS9E6W",
                "name": "Hot"
            }
        ]
    },
    "categories": {
        "elements": [
            {
                "id": "1JZPWY014VPEP",
                "name": "Italian",
                "sortOrder": 1
            },
            {
                "id": "0AJNZP04JXB4G",
                "name": "From the Oven",
                "sortOrder": 0
            }
        ]
    }
}

 

Two levels of fields can be expanded by specifying a dotted field path:

$ curl -s "https://apisandbox.dev.clover.com/v3/merchants/[Merchant ID]/orders/[Order ID]?expand=lineItems.taxRates" --header "Authorization: Bearer {Your API token}" | python -mjson.tool

...
{
    "clientCreatedTime": "1389389735000",
    "createdTime": "1389389736000",
    "employee": "id",
    "groupLineItems": "true",
    "id": "QGSS9P64219CM",
    "lineItems": {
        "elements": [
            {
                "createdTime": "1389389734000",
                "id": "VGQRH14DBR7JC",
                "name": "Bangers and Mash",
                "price": "1000",
                "printed": "true",
                "taxRates": {
                    "elements": [
                        {
                            "id": "VSA19B84VG1GT",
                            "isDefault": "true",
                            "name": "VAT",
                            "rate": "1500000"
                        },
                        {
                            "id": "BTHZCAXV6Z5R8",
                            "isDefault": "true",
                            "name": "Zero Tax",
                            "rate": "0"
                        }
                    ]
                }
            }
        ]
    },
    "manualTransaction": "false",
    "payType": "FULL",
    "state": "locked",
    "taxRemoved": "false",
    "total": "1000"
}
...

Inventory Stock

The quantity field holds an item’s stock, and is found by expanding itemStock when viewing items. Note that this field can only be updated through v3/merchants/[Merchant ID]/item_stocks endpoints, which are shown in the new API Reference. The field supports whole or decimal numbers, both positive and negative.

$ cat /tmp/item_stock.json
{
   "quantity": 160.5
}

$ curl -s -X POST "https://apisandbox.dev.clover.com/v3/merchants/[Merchant ID]/item_stock/[Item ID]" --header "Authorization: Bearer {Your API token}" --data "[Content from item_stock.json" | python -mjson.tool

{
  "item": {
    "id": "3Z29BX6C013XC"
  },
  "stockCount": 161,
  "quantity": 160.5
}

 

Stock count is a deprecated field that will always display quantity rounded to the nearest whole number. As a result, its use is discouraged.

Object Associations

Many-to-many associations between objects require their own endpoints. If you want to add an item to a category, for example, we require that you create the item, create the category, and then use an object association call to link the two. We support object associations with the following calls:

  • /v3/merchants/[Merchant ID]/category_items: category to an item
  • /v3/merchants/[Merchant ID]/item_modifier_groups: modifier group to an item
  • v3/merchants/[Merchant ID]/option_items: option to an item
  • /v3/merchants/[Merchant ID]/tax_rate_items: tax rate to an item
  • /v3/merchants/[Merchant ID]/tag_items: label to an item

See the API Reference for more information on these calls.

Example: Category Items

To create an association, POST a tuple of the two object IDs to the association endpoint.

$ cat /tmp/category_items.json
{
  "elements": [
    { "category": {"id": "Y906VJJHTNCVW"}, "item": {"id": "7PARQ2Z2G0336"}}
  ]
}

$ curl -s -X POST "https://apisandbox.dev.clover.com/v3/merchants/[Merchant ID]/category_items" --header "Authorization: Bearer {Your API token}" -H "Content-Type: application/json" --data "[Content from category_items.json]"

 

To create multiple associations in one call, POST a list of tuples. The following example associates three items with two categories:

{
  "elements": [
      { "item": {"id": "ABWN2X43EXJN8"}, "category": {"id": "J615DCVPX97JG"} },
      { "item": {"id": "ABWN2X43EXJN8"}, "category": {"id": "PBRT27S9JBSK8"} },
      { "item": {"id": "F1RBG5MKD3SQR"}, "category": {"id": "J615DCVPX97JG"} },
      { "item": {"id": "F1RBG5MKD3SQR"}, "category": {"id": "PBRT27S9JBSK8"} },
      { "item": {"id": "S9230FJR93DFJ"}, "category": {"id": "J615DCVPX97JG"} },
      { "item": {"id": "S9230FJR93DFJ"}, "category": {"id": "PBRT27S9JBSK8"} }
  ]
}

 

To remove the association, send a POST with ?delete=true appended to the URL, along with the same payload. To remove all categories from an item, use a payload with the item and no category:

{
  "elements": [
    { "item": {"id": "7PARQ2Z2G0336"}}
  ]
}

Displaying NULL Fields

To have a response display all possible fields, you can append return_null_fields=true to your query.

$ curl -s https://apisandbox.dev.clover.com/v3/merchants/[Merchant ID]/orders/[Order ID]?return_null_fields=true  --header "Authorization:Bearer {Your API token}" | python -mjson.tool

{
   "id": "[Order ID]",
   "currency": "USD",
   "employee": {
      "id": "0YN6A3WJ5BEZJ"
   },
   "total": 152,
   "title": "5",
   "note": null,
   "orderType": {
       "id": "2ZPZHQG2Z64NM",
       "labelKey": null,
       "label": null,
       "taxable": null,
       "isDefault": null,
       "isDeleted": null
   },
   "taxRemoved": false,
   "isVat": false,
   "state": "locked",
   "manualTransaction": true,
   "groupLineItems": true,
   "testMode": false,
   "payType": null,
   "createdTime": 1373613867000,
   "clientCreatedTime": 1373613795000,
   "modifiedTime": 1373613868000,
   "serviceCharge": null
}