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.

With the REST API, you can build custom solutions to create, manage, and query item categories.

Prerequisite

Generate a merchant-specific test API token in sandbox.

Create a category

Send a POST request to /v3/merchants/{mId}/categories.
Enter required information—mId and name .
Assign a colorCode to a category using the hex values.
Set the Authorization header as Bearer token type, and enter the test API token.

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.

Request and Response example—Create a category

curl --request POST \
--url 'https://apisandbox.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
}

Manage items in a category

Associate items with a category

Send a POST request to /v3/merchants/{mId}/category_items.
Enter required information—mId, category id and item id.
Set the Authorization header as Bearer token type, and enter the test API token.

Request and Response example—Associate items with a category

curl --request POST \
  --url 'https://apisandbox.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—mId and item id.

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.

Request and Response example—Search categories associated with an item

curl --request GET \
--url 'https://apisandbox.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
}

Delete association between an item and a category

Send a POST request to /v3/merchants/{mId}/category_items?delete=true.
Enter required information—mId, category id and item id.
Set the delete value as true.

Request and Response example—Delete item association

curl --request POST \
  --url 'https://apisandbox.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.
Set the Authorization header as Bearer token type, and enter the test API token.

Request and Response example—Search items in a category

curl --request GET \
--url 'https://apisandbox.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://apisandbox.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.