Use object associations

United States

Canada

Europe

Latin America

Many-to-many associations between objects require their own endpoints. If you want to add an item to a category, for example, we require that you create the item, create the category, and then use an object association call to link the two. We support object associations with the following calls:

/v3/merchants/{mId}/category_items: category to an item
/v3/merchants/{mId}/item_modifier_groups: modifier group to an item
/v3/merchants/{mId}/option_items: option to an item
/v3/merchants/{mId}/tax_rate_items: tax rate to an item
/v3/merchants/{mId}/tag_items: label to an item

See the API Reference for more information.

Example—Associate categories and items

To create an association, POST a tuple of the two object IDs to the association endpoint.

$ cat /tmp/category_items.json
{
  "elements": [
    { "category": {"id": "Y906VJJHTNCVW"}, "item": {"id": "7PARQ2Z2G0336"}}
  ]
}

$ curl -s -X POST "https://apisandbox.dev.clover.com/v3/merchants/{mId}/category_items" --header "Authorization: Bearer {API_Token}" -H "Content-Type: application/json" --data "[Content from category_items.json]"

To create multiple associations in one call, POST a list of tuples. The following example associates three items with two categories:

{
  "elements": [
      { "item": {"id": "ABWN2X43EXJN8"}, "category": {"id": "J615DCVPX97JG"} },
      { "item": {"id": "ABWN2X43EXJN8"}, "category": {"id": "PBRT27S9JBSK8"} },
      { "item": {"id": "F1RBG5MKD3SQR"}, "category": {"id": "J615DCVPX97JG"} },
      { "item": {"id": "F1RBG5MKD3SQR"}, "category": {"id": "PBRT27S9JBSK8"} },
      { "item": {"id": "S9230FJR93DFJ"}, "category": {"id": "J615DCVPX97JG"} },
      { "item": {"id": "S9230FJR93DFJ"}, "category": {"id": "PBRT27S9JBSK8"} }
  ]
}

To remove an association, add the ?delete=true query parameter to the URL and send the tuple payload.

$ cat /tmp/category_items.json
{
  "elements": [
    { "category": {"id": "Y906VJJHTNCVW"}, "item": {"id": "7PARQ2Z2G0336"}}
  ]
}

$ curl -s -X POST "https://apisandbox.dev.clover.com/v3/merchants/{mId}/category_items?delete=true" --header "Authorization: Bearer {API_Token}" -H "Content-Type: application/json" --data "[Content from category_items.json]"

To remove all items from a category, use a payload with the category and no items:

$ cat /tmp/category_items.json
{
  "elements": [
    { "category": {"id": "Y906VJJHTNCVW"}}
  ]
}

$ curl -s -X POST "https://apisandbox.dev.clover.com/v3/merchants/{mId}/category_items?delete=true" --header "Authorization: Bearer {API_Token}" -H "Content-Type: application/json" --data "[Content from category_items.json]"

To remove all categories from an item, use a payload with the item and no category:

$ cat /tmp/category_items.json
{
  "elements": [
    { "item": {"id": "7PARQ2Z2G0336"}}
  ]
}

$ curl -s -X POST "https://apisandbox.dev.clover.com/v3/merchants/{mId}/category_items?delete=true" --header "Authorization: Bearer {API_Token}" -H "Content-Type: application/json" --data "[Content from category_items.json]"

Updated 12 months ago