Manage categories

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 to create, manage, and query categories.

Create a category

Send a POST request to /v3/merchants/{mId}/categories.
Enter required information—name .
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. By default, the sortOrder value is set as the last category in the Clover Register and Dining apps. For example, if you already have five categories, the new category is sixth in the sort order.

Manage items in a category

Associate items with a category

Send a POST request to /v3/merchants/{mId}/category_items.
Enter required information—category id and item id.

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}"}}]}'

Search categories associated with an item

Send a GET request to /v3/merchants/{mId}/items/{itemId}?expand=categories.
Enter required information—item id.

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 displays categories associated with the item. See Use expandable fields for more information on working with expand parameters in your requests.

Delete item associations

To delete an association between an item and a category:

Send a POST request to /v3/merchants/{mId}/category_items?delete=true.
Enter required information—category id and item id.
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}"}}]}'

Search items in a category

Send a GET request to /v3/merchants/{mId}/categories/{categoryId}/items.
Use filters and expansions to indicate the search parameters.

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 Apply filters for more information on working with the filter parameter. See the API reference for more information about available filters.

Updated about 1 month ago