Manage modifier groups and modifiers

United States

Canada

Europe

In restaurants and online ordering services, merchants use modifier groups and modifier for customizing orders. 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 to create, manage, and query modifier groups.

Prerequisite

Generate a merchant-specific test API token in sandbox.

Create a modifier group

Send a POST request to /v3/merchants/{mId}/modifier_groups.
Enter required information—mId and name value.
Enter additional values—minRequired and maxAllowed for modifier limits that can be associated with order line items in the Clover Register app.
Set the Authorization header as Bearer token type, and enter the test API token.

In response, a unique modifier group id is generated. By default, the showByDefault value is set to true for prompting merchants to add modifiers in the Clover Register app.

Request and Response example—Create a modifier group

curl --request POST \
--url 'https://apisandbox.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
}

Create a modifier

Send a POST request to /v3/merchants/{mId}/modifier_groups/{modifierGroupId}/modifiers.
Enter required information—mId, modifier name and price.
Set the Authorization header as Bearer token type, and enter the test API token.

In response, a unique modifier id is generated.

Request and Response example—Create a modifier

curl --request POST \
--url 'https://apisandbox.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
    }
}

Manage items in a modifier group

Associate items with a modifier group

Send a POST request to /v3/merchants/{mId}/item_modifier_groups.
Enter required information—mId, modifier group id and item id.
Set the Authorization header as Bearer token type, and enter the test API token.

Request example—Associate items with a modifier group

curl --request POST \
  --url 'https://apisandbox.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}"}
      }
    ]
  }'

Search modifier groups associated with an item

Send a GET request to /v3/merchants/{mId}/items/{itemId}?expand=modifierGroups.
Enter required information—mId and item id.

In response, the modifierGroups expansion displays groups associated with the item. See Expanding fields for more information on working with expand parameters in your requests.

Request and Response example—Search modifier groups associated with an item

curl --request GET \
--url 'https://apisandbox.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
}

Delete item association between item and modifier group

To delete an association between an item and a modifier group:

Send a POST request to /v3/merchants/{mId}/category_items?delete=true.
Enter required information—mId, category id and item id.
Set the delete value as true.

Request example—Delete item associations

curl --request POST \
  --url 'https://apisandbox.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}"}
      }
    ]
  }'

Search items in a modifier group

Send a GET request to /v3/merchants/{mId}/modifier_groups/{modifierGroupId}/items.
Use filters and expansions to indicate the search parameters.
Set the Authorization header as Bearer token type, and enter the test API token.

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.

Request example—Search items in a modifier group

curl --request GET \
--url 'https://apisandbox.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://apisandbox.dev.clover.com/v3/merchants/{mId}/modifier_groups/{modifierGroupId}/items?filter=price%3E%3D1000&limit=100"
}

In response, items that match the search filters are displayed.

See Apply filters and Use expandable fields for more information on working with filter and expand parameters in your requests. See the API reference for more information about available filters.