Manage categories
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
- Send a POST request to
/v3/merchants/{mId}/categories
. - Enter required information—
mId
andname
. - 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
}
Associate items with a category
- Send a POST request to
/v3/merchants/{mId}/category_items
. - Enter required information—
mId
, categoryid
and itemid
. - 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
- Send a POST request to
/v3/merchants/{mId}/category_items?delete=true
. - Enter required information—
mId
, categoryid
and itemid
. - Set the
delete
value astrue
. - 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
- Send a GET request to
/v3/merchants/{mId}/items/{itemId}?expand=categories
. - Enter required information—
mId
and itemid
. - 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
- 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 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 18 days ago