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.
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.
Updated 2 months ago