United States

Canada

Europe

Merchants group similar items into categories. For example, in a restaurant, a merchant can create categories for Salads and Beverages. In the Clover Register app, merchants see categories and items under those categories.

Using the REST API, you can build custom solutions for creating, managing, and querying categories.

Creating a category

To create a category, send a POST request to /v3/merchants/{mId}/categories. The name value is required. You can assign a colorCode to a category using the hex values.

curl --request POST \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/categories' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{"name":"Salads",'colorCode': '#FF00Z011'}'

{
    "id": "AN7WTGHSKE9XG", // category ID
    "name": "Salads",
    'colorCode': '#FF00Z011'
    "sortOrder": 0
}

In response, a unique category id is generated. The sortOrder value is set by default as the last category in the Clover Register and Dining apps. For example, if you already have five categories, the new category would be sixth in the sort order.

Managing items in a category

Associating items with a category

To associate items with a category, send a POST request to /v3/merchants/{mId}/category_items. The category id and item id values are required.

curl --request POST \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/category_items' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{"elements":[{"category":{"id":"{categoryId}"},"item":{"id":"{item1Id}"}},{"category":{"id":"{categoryId}"},"item":{"id":"{item2Id}"}}]}'

Querying categories associated with an item

To query categories associated with an item, send a GET request to /v3/merchants/{mId}/items/{itemId}?expand=categories. The item id value is required.

curl --request GET \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/items/{itemId}?expand=categories' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}'

{
    "id": "N2WWSQBTAADZC", // item ID
    "hidden": false,
    "name": "Greek Salad",
    ...
    "categories": { // expansion
        "elements": [
            {
                "id": "AN7WTGHSKE9XG",
                "name": "Salads",
                    “colorCode”: “#FF00Z011”
                "sortOrder": 0
            }
        ]
    },
    "modifiedTime": 1611643817000
}

In response, the categories expansion shows categories associated with the item. See Expanding fields for more information on working with expand parameters in your requests.

Deleting item associations

To delete an association between an item and category, send a POST request to /v3/merchants/{mId}/category_items?delete=true. The category id and item id values are required. Set the delete value as true.

curl --request POST \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/category_items?delete=true' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{"elements":[{"category":{"id":"{categoryId}"},"item":{"id":"{itemId}"}}]}'

Querying items in a category

To query items in a category, send a GET request to /v3/merchants/{mId}/categories/{categoryId}/items. You can use filters and expansions to fine-tune responses.

curl --request GET \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/categories/{categoryId}/items?filter=modifiedTime>={unix_time}' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}'

{
    "elements": [
        {
            "id": "N2WWSQBTAADZC", // item ID
            "hidden": false,
            "name": "Greek Salad",
            ...
            "modifiedTime": 1611643817000
        },
        {
            "id": "9J1F7WW503CZW", // item ID
            "hidden": true,
            "name": "Caesar Salad",
            ...
            "modifiedTime": 1611644393000
        }
    ],
    "href": "http://sandbox.dev.clover.com/v3/merchants/{mId}/categories/{categoryId}/items?filter=modifiedTime%3E%3D1611643817000&limit=100"
}

See Applying filters for more information on working with the filter parameter. See the API reference for more information about available filters.