Release NotesAnnouncementsBlogFAQSupport
Guides

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.

Manage categories on the Merchant Dashboard

Merchants can manage items and item groups on the Merchant Dashboard. See Clover Help to Use categories to organize items.

Manage categories and items in categories with Clover REST APIs

Prerequisite

Generate a merchant-specific test API token in sandbox.

Create a category

  1. Send a POST request to /v3/merchants/{mId}/categories.
  2. Enter required information—mId and name .
  3. Assign a colorCode to a category using the hex values.
  4. 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
}

Associate items with a category

  1. Send a POST request to /v3/merchants/{mId}/category_items.
  2. Enter required information—mId, category id and item id.
  3. Set the Authorization header as Bearer token type, and enter the merchant's 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}"}
      }
    ]
  }'

Delete association between an item and a category

  1. Send a POST request to /v3/merchants/{mId}/category_items?delete=true.
  2. Enter required information—mId, category id and item id.
  3. Set the delete value as true.
  4. Set the Authorization header as Bearer token type, and enter the merchant's API token.

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

View categories associated with an item

  1. Send a GET request to /v3/merchants/{mId}/items/{itemId}?expand=categories.
  2. Enter required information—mId and item id.
  3. Set the Authorization header as Bearer token type, and enter the merchant's API token.

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—View 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
}

View items in a category

  1. Send a GET request to /v3/merchants/{mId}/categories/{categoryId}/items.
  2. Use filters and expansions to indicate the search parameters.
  3. Set the Authorization header as Bearer token type, and enter the merchant's API token.

Request and Response example—View 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 and Use expandable fields for more information on working with filter and expand parameters in your requests.

Related topics

Updated 7 months ago