United States

Canada

Europe

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.