# Tagging resources

[Most of Commerce Layer's resources](/core-api-reference/tags.md#taggable-resources) can be tagged using one or more existing [tags](/core-api-reference/tags.md). To do that, you need to update the resource setting the relationship with the desired tag(s).

{% content-ref url="/pages/-LgSrGVm5cxz3IGx3doV" %}
[Updating resources](/core/updating-resources.md)
{% endcontent-ref %}

{% hint style="info" %}
A maximum of **10 tags** is allowed for each single resource object.
{% endhint %}

## Example

{% tabs %}
{% tab title="Request" %}
The following request tags the resource identified by the "xYZkjABcde" ID with the two tags identified by the "geJmexflJQ" and "mWJAPvfBaV" IDs:

<pre class="language-shell"><code class="lang-shell">curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/skus/xYZkjABcde' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "skus",
      "id": "xYZkjABcde",
      "relationships": {
<strong>        "tags": {
</strong><strong>          "data": [
</strong><strong>            {
</strong><strong>              "type": "tags",
</strong><strong>              "id": "geJmexflJQ"
</strong><strong>            },
</strong><strong>            {
</strong><strong>              "type": "tags",
</strong><strong>              "id": "mWJAPvfBaV"
</strong><strong>            }
</strong><strong>          ]
</strong><strong>        }
</strong>      }
    }
  }'
</code></pre>

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning the updated resource object:

<pre class="language-json"><code class="lang-json">{
  "data": {
    "id": "xYZkjABcde",
    "type": "skus",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/skus/xYZkjABcde"
    },
    "attributes": {
      "code": "TSHIRTMS000000FFFFFFLXXX",
      "name": "Men's Black T-Shirt with White Logo (L)",
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
      "image_url": "https://img.yourdomain.com/skus/xYZkjABcde.png",
      "pieces_per_pack": null,
      "weight": null,
      "unit_of_weight": null,
      "hs_tariff_number": null,
      "do_not_ship": false,
      "do_not_track": false,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "reference_origin": "ANYREFEFERNCEORIGIN",
      "metadata": {}
    },
    "relationships": {
      "shipping_category": { ... },
      "prices": { ... },
      "stock_items": { ... },
      "delivery_lead_times": { ... },
      "sku_options": { ... },
      "attachments": { ... },
      "events": { ... },
<strong>      "tags": {
</strong><strong>        "links": {
</strong><strong>          "self": "https://yourdomain.commercelayer.io/api/skus/xYZkjABcde/relationships/tags",
</strong><strong>          "related": "https://yourdomain.commercelayer.io/api/skus/xYZkjABcde/tags"
</strong><strong>        }
</strong><strong>      }
</strong>    },
    "meta": {
      "mode": "test",
      "organization_id": "YyrQYFzERk"
    }
}
}
</code></pre>

{% endtab %}
{% endtabs %}

## Removing tags

To remove one or more tags from a resource you need to update the resource setting the relationship with the updated list of tags. To remove all the tags from a resource, just set the tags relationship as an empty array.

{% hint style="info" %}
[Deleting a tag](/core-api-reference/tags/delete.md) automatically removes any existing association.
{% endhint %}

### Example

{% tabs %}
{% tab title="Request" %}
The following request removes all the tags associated with the resource identified by the "xYZkjABcde" ID:

<pre class="language-shell"><code class="lang-shell">curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/skus/xYZkjABcde' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "skus",
      "id": "xYZkjABcde",
      "relationships": {
<strong>        "tags": {
</strong><strong>          "data": []
</strong><strong>        }
</strong>      }
    }
  }'
</code></pre>

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning the updated resource object:

```json
{
  "data": {
    "id": "xYZkjABcde",
    "type": "skus",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/skus/xYZkjABcde"
    },
    "attributes": {
      "code": "TSHIRTMS000000FFFFFFLXXX",
      "name": "Men's Black T-Shirt with White Logo (L)",
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
      "image_url": "https://img.yourdomain.com/skus/xYZkjABcde.png",
      "pieces_per_pack": null,
      "weight": null,
      "unit_of_weight": null,
      "hs_tariff_number": null,
      "do_not_ship": false,
      "do_not_track": false,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "reference_origin": "ANYREFEFERNCEORIGIN",
      "metadata": {}
    },
    "relationships": {
      "shipping_category": { ... },
      "prices": { ... },
      "stock_items": { ... },
      "delivery_lead_times": { ... },
      "sku_options": { ... },
      "attachments": { ... },
      "events": { ... },
      "tags": { ... }
    },
    "meta": {
      "mode": "test",
      "organization_id": "YyrQYFzERk"
    }
  }
}
```

{% endtab %}
{% endtabs %}

## Updating the list of tags

If a resource is already associated with one or more tags, tagging the resource by [updating the relationship](#example) will remove all the currently associated tags and replace them with the new list of tags. If you just need to change the list of the tags currently associated with a resource, you can patch the taggable resource and send the trigger attributes `_add_tags` and/or `_remove_tags` specifying the comma-separated list of tag names that you want to add and/or remove.

{% hint style="warning" %}
The specified names must belong to existing tags, meaning that the related tags must be previously [created](/core-api-reference/tags/create.md). The provided tags are automatically [validated](/core-api-reference/tags.md#validations) and non-existing ones are ignored and not associated with the resource without returning any errors.
{% endhint %}

{% hint style="info" %}
The two trigger attributes can be sent within the same `PATCH` request (i.e. adding some tags and removing some others in just one API call — [see example](#example-2)). In that case, remember that tag removal is always performed **after** tag addition.
{% endhint %}

### Example

{% tabs %}
{% tab title="Request" %}
The following request changes the list of tags associated with the resource identified by the "xYZkjABcde" ID:

<pre class="language-sh"><code class="lang-sh">curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/skus/xYZkjABcde' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "skus",
      "id": "xYZkjABcde",
      "attributes": {
<strong>        "_add_tags": "out-of-stock,old-collection",
</strong><strong>        "_remove_tags": "new-collection,vip"
</strong>      }
    }
  }'
</code></pre>

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning the updated resource object:

```json
{
  "data": {
    "id": "xYZkjABcde",
    "type": "skus",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/skus/xYZkjABcde"
    },
    "attributes": {
      "code": "TSHIRTMS000000FFFFFFLXXX",
      "name": "Men's Black T-Shirt with White Logo (L)",
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
      "image_url": "https://img.yourdomain.com/skus/xYZkjABcde.png",
      "pieces_per_pack": null,
      "weight": null,
      "unit_of_weight": null,
      "hs_tariff_number": null,
      "do_not_ship": false,
      "do_not_track": false,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "reference_origin": "ANYREFEFERNCEORIGIN",
      "metadata": {}
    },
    "relationships": {
      "shipping_category": { ... },
      "prices": { ... },
      "stock_items": { ... },
      "delivery_lead_times": { ... },
      "sku_options": { ... },
      "attachments": { ... },
      "events": { ... },
      "tags": { ... }
    },
    "meta": {
      "mode": "test",
      "organization_id": "YyrQYFzERk"
    }
  }
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.commercelayer.io/core/tagging-resources.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.