# Tags

One or more tags (max **10** per resource) can be associated with most of the other resources to group them under predefined labels that can be used as anchors to build custom logic and processes on top of our APIs.

Tags can be [included as associations](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/tagging-resources) of the related resource and leveraged to [filter](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/filtering-data) a list of a specific resource type (e.g. a list of SKUs, a list of customers, etc.). Tags can be also [exported](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/exporting-resources) and [imported](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/importing-resources) in JSON or CSV format, both standalone and together with the related resources.

When a resource is tagged (or the list of the associated tags changes) the `tagged` event is triggered, the related [webhook](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/real-time-webhooks) is fired, and the associated tag(s) are automatically included in the callback's payload.

## Taggable resources

At the moment tags are available for the following resources:

* [Addresses](https://docs.commercelayer.io/core-api-reference/addresses)
* [Bundles](https://docs.commercelayer.io/core-api-reference/bundles)
* [Coupons](https://docs.commercelayer.io/core-api-reference/coupons)
* [Customers](https://docs.commercelayer.io/core-api-reference/customers)
* [Gift cards](https://docs.commercelayer.io/core-api-reference/gift_cards)
* [Line items](https://docs.commercelayer.io/core-api-reference/line_items)
* [Line item options](https://docs.commercelayer.io/core-api-reference/line_item_options)
* [Order subscriptions](https://docs.commercelayer.io/core-api-reference/order_subscriptions)
* [Orders](https://docs.commercelayer.io/core-api-reference/orders)
* [Returns](https://docs.commercelayer.io/core-api-reference/returns)
* [Shipments](https://docs.commercelayer.io/core-api-reference/shipments)
* [Shipping methods](https://docs.commercelayer.io/core-api-reference/shipping_methods)
* [SKUs](https://docs.commercelayer.io/core-api-reference/skus)
* [SKU options](https://docs.commercelayer.io/core-api-reference/sku_options)
* All [promotions](https://docs.commercelayer.io/core-api-reference/promotions) types:
  * [Buy X pay Y](https://docs.commercelayer.io/core-api-reference/buy_x_pay_y_promotions)
  * [External promotions](https://docs.commercelayer.io/core-api-reference/external_promotions)
  * [Flex promotions](https://docs.commercelayer.io/core-api-reference/flex_promotions)
  * [Fixed amount promotions](https://docs.commercelayer.io/core-api-reference/fixed_amount_promotions)
  * [Fixed price promotions](https://docs.commercelayer.io/core-api-reference/fixed_price_promotions)
  * [Free gift promotions](https://docs.commercelayer.io/core-api-reference/free_gift_promotions)
  * [Free shipping promotions](https://docs.commercelayer.io/core-api-reference/free_shipping_promotions)
  * [Percentage discount promotions](https://docs.commercelayer.io/core-api-reference/percentage_discount_promotions)

If a resource is already associated with one or more tags, tagging the resource by [updating the relationship](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/tagging-resources#example) will remove all the currently associated tags and replace it with the new list of tags. If you just need to [change the list of the tags](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/tagging-resources#updating-the-list-of-tags) currently associated with a resource you can patch the taggable resource and send the trigger attributes `_add_tags` and `_remove_tags`.

{% hint style="success" %}
The two triggers above can be leveraged to add or remove tags from resources also directly when importing them ([see example](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/importing-resources#importing-a-list-of-customers-removing-the-associated-tags-csv)).
{% endhint %}

{% hint style="info" %}
You can still tag orders that are no longer [editable](https://docs.commercelayer.io/core-api-reference/orders#order-editing), just make sure to pass in your `PATCH` request only the tag relationship, without changing any other attribute.
{% endhint %}

## Validations

The use of tags is subject to specific restrictions and validations:

* A maximum of **10 tags** is allowed for each single resource object.
* Each tag's `name` must be unique within a specific organization.
* Each tag's `name` can have a maximum length of **25 chars**.
* Each tag's `name` must be alphanumeric and can contain underscores, hyphens, and colons (i.e. the allowed list of characters is: `a—z`, `A—Z`, `0—9`, `_`, `-`, `:`). Spaces are not allowed.

{% hint style="info" %}
Tags names aren't case-sensitive. If you use uppercase letters they will be converted to lowercase, so we recommend directly choosing lowercase names.
{% endhint %}

## Sales channel abilities

Tags can be managed using [integration](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/api-credentials#integration) API credentials. [Sales channels](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/api-credentials#sales-channel) are allowed to read tags associated with a small subset of the [taggable resources](#taggable-resources):

* [Bundles](https://docs.commercelayer.io/core-api-reference/bundles)
* [SKUs](https://docs.commercelayer.io/core-api-reference/skus)
* [SKU options](https://docs.commercelayer.io/core-api-reference/sku_options)
* All [promotions](https://docs.commercelayer.io/core-api-reference/promotions) types:
  * [Buy X pay Y](https://docs.commercelayer.io/core-api-reference/buy_x_pay_y_promotions)
  * [External promotions](https://docs.commercelayer.io/core-api-reference/external_promotions)
  * [Flex promotions](https://docs.commercelayer.io/core-api-reference/flex_promotions)
  * [Fixed amount promotions](https://docs.commercelayer.io/core-api-reference/fixed_amount_promotions)
  * [Fixed price promotions](https://docs.commercelayer.io/core-api-reference/fixed_price_promotions)
  * [Free gift promotions](https://docs.commercelayer.io/core-api-reference/free_gift_promotions)
  * [Free shipping promotions](https://docs.commercelayer.io/core-api-reference/free_shipping_promotions)
  * [Percentage discount promotions](https://docs.commercelayer.io/core-api-reference/percentage_discount_promotions)

Specifically:

* Can retrieve the single tag associated with one of the resources above by querying the `/api/tags/:id` endpoint.
* Can [include](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/including-associations) tags when reading one of the resources above (e.g. `/api/skus/:id?include=tags`).
* **Cannot** list tags by querying the `/api/tags` endpoint for **any** resource.

{% hint style="warning" %}
If a tag is associated both with one (or more) of the resources above and one (or more) of the prohibited resources (e.g. SKUs and orders), the tag will still be readable by sales channels and includable when fetching the allowed resource (e.g. SKUs).
{% endhint %}

<details>

<summary>How-to</summary>

Check the related [guide](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/tagging-resources) for all the information on how to tag a resource. See these examples — [CSV](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/exporting-resources#exporting-all-the-tags-csv) / [JSON](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/exporting-resources#exporting-all-the-skus-tagged-with-at-least-one-of-two-tags-json) — to learn how to export tags and these examples — [CSV](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/importing-resources#importing-a-list-of-tags-csv) / [JSON](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/importing-resources#importing-a-list-of-skus-with-tags-json) — to learn how to import tags.

</details>