# Tagging resources

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

{% content-ref url="updating-resources" %}
[updating-resources](https://docs.commercelayer.io/core/updating-resources)
{% 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](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/tags/delete) 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](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/tags/create). The provided tags are automatically [validated](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/tags#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 %}