Manage modifier groups and modifiers
In restaurants and online ordering services, merchants use modifier groups and modifiers for customizing orders. These modifiers help restaurant kitchens to receive all the required details for an order. Clover Register, Counter Service, and Table Service apps in the US and Canada all support modifiers, modifier groups, and variants.
For example, in a Salad Add-in
modifier group, you can have modifiers like Tofu
and Avocado
. In the Clover Register app, merchants can customize a Caesar Salad
item with two Tofu
modifier and three Avocado
modifier additions.
With the REST API, you can build custom solutions for creating, managing, and querying modifier groups.
Creating a modifier group
To create a modifier group, send a POST
request to /v3/merchants/{mId}/modifier_groups
. The name
value is required. You can set additional values like minRequired
and maxAllowed
for modifier limits that can be associated with order line items in the Clover Register app.
curl --request POST \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/modifier_groups' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}'
--data '{"name":"Salad Add-on"}'
{
"id": "QZ587JT76N80Y", // modifier group ID
"name": "Salad Add-in",
"showByDefault": true
}
In response, a unique modifier group id
is generated. The showByDefault
value is set to true
by default for prompting merchants to add modifiers in the Clover Register app.
Creating a modifier
To create a modifier, send a POST
request to /v3/merchants/{mId}/modifier_groups/{modifierGroupId}/modifiers
. The modifier name
and price
values are required.
curl --request POST \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/modifier_groups/{modifierGroupId}/modifiers' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{"price":100,"name":"Tofu"}'
{
"id":"S47VGYX913K4T" // modifier ID
"name":"Tofu"
"price":100
"modifierGroup":{
"id":"QZ587JT76N80Y" // modifier group ID
}
}
In response, a unique modifier id
is generated.
Managing items in a modifier group
Associating items with a modifier group
To associate items with a modifier group, send a POST
request to /v3/merchants/{mId}/item_modifier_groups
. The modifier group id
and item id
values are required.
curl --request POST \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/item_modifier_groups' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{"elements":[{"modifierGroup":{"id":"{modifierGroupId}"},"item":{"id":"{item1Id}"}},{"modifierGroup":{"id":"{modifierGroupId}"},"item":{"id":"{item2Id}"}}]}'
Querying modifier groups associated with an item
To query modifier groups associated with an item, send a GET
request to /v3/merchants/{mId}/items/{itemId}?expand=modifierGroups
. The item id
value is required.
curl --request GET \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/items/{itemId}?expand=modifierGroups' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}'
{
"id": "N2WWSQBTAADZC", // item ID
"hidden": false,
"name": "Greek Salad",
...
"modifierGroups": { // expansion
"elements": [
{
"id": "QZ587JT76N80Y",
"name": "Salad Add-in",
"showByDefault": true,
"modifierIds": "S47VGYX913K4T,JRMCKCQK1XCGT",
"items": {
"elements": [
{
"id": "N2WWSQBTAADZC"
}
]
}
}
]
},
"modifiedTime": 1611643817000
}
In response, the modifierGroups
expansion shows groups 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 modifier group, 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}/item_modifier_groups?delete=true' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{"elements":[{"modifierGroup":{"id":"{modifierGroupId}"},"item":{"id":"{itemId}"}}]}'
Querying items in a modifier group
To query items in a modifier group, send a GET
request to /v3/merchants/{mId}/modifier_groups/{modifierGroupId}/items
. You can use filters and expansions to fine-tune responses.
In the following example, the filter
parameter is used to filter by price and the expand
parameter is used to provide more information about categories.
curl --request GET \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/modifier_groups/{modifierGroupId}/items?filter=price>=1000&expand=categories' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}'
{
"elements": [
{
"id": "N2WWSQBTAADZC", //item matches filter
"hidden": false,
"name": "Greek Salad",
"price": 1200
...
"categories": { // expansion
"elements": [
{
"id": "AN7WTGHSKE9XG",
"name": "Salads",
...
}
]
},
"modifiedTime": 1611643817000
}
],
"href": "http://sandbox.dev.clover.com/v3/merchants/{mId}/modifier_groups/{modifierGroupId}/items?filter=price%3E%3D1000&limit=100"
}
In response, items that match the filter are displayed.
See Applying filters and Expanding fields for more information on working with filter
and expand
parameters in your requests. See the API reference for more information about available filters.
Updated 2 months ago