# Tags

In fulfillmenttools there's the possibility to map individual processes and to customize entities according to special needs. One way to impose a certain customization on your processes is through tags.

{% hint style="info" %}
Before using a tag, it must be created via API: [Tag REST API documentation](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#get-/api/tags). If the tag doesn't exist, the request to use it will be rejected.
{% endhint %}

Tags can be attached to several entities at fulfillmenttools, such as orders, order lines, pick jobs, pack jobs, or handover jobs. The usage of tags is indicated by the field `tags`. Usually, tags are added to entities by services that supply data to the platform (external services, middleware, or connectors).

### **Tag inheritance**

Tags are inherited from one entity to another. Multiple tags with the same ID are merged into one tag. This applies to tags on the root level of the entity and the tags on the line item itself. This covers:

* Order inherits tags to pick jobs, pack job, and handover job.
* Listings inherit tags to pick job line items, pack job line items and handover job line items.

### Use cases for tags

* Create routing rules with the [DOMS Toolkit](https://docs.fulfillmenttools.com/documentation/by-pillar/advanced-order-routing/doms-toolkit)
* Define a picking method
* Define which external documents are offered for printing during picking and packing
* Configure the scanner behavior during [picking](https://docs.fulfillmenttools.com/documentation/by-pillar/store-operations/picking)
* Add [sticker](https://docs.fulfillmenttools.com/documentation/getting-started/stickers) to entities

{% hint style="info" %}
For more details about the `tags` endpoint, refer to the [REST API reference](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#get-/api/tags).
{% endhint %}

## Create tags

{% hint style="info" %}
A tag's `allowedValues` can only be extended. Once a value is added, it can't be removed.
{% endhint %}

To create a tag, send a `POST` request to the `/api/tags` endpoint.

```http
POST https://{projectId}.api.fulfillmenttools.com/api/tags
```

```json
{
  "id": "channel",
  "allowedValues": [
    "marketplace",
    "webshop"
  ]
}
```

The field `id` must be unique across all tags.

## Get tags

To retrieve all defined tags, send a `GET` request to the `/api/tags` endpoint.

```http
GET https://{projectId}.api.fulfillmenttools.com/api/tags
```

The response body contains an array of tag objects:

```json
{
    "tags": [
        {
            "id": "channel",
            "allowedValues": [
                "marketplace",
                "webshop"
            ],
            "created": "2020-02-03T08:45:51.525Z",
            "lastModified": "2020-02-03T09:45:51.525Z",
            "version": 1
        }
    ],
    "total": 1
}
```

## Patch tags

Once a tag is created, new values can be added to its `allowedValues` array.

```http
PATCH https://{projectId}.api.fulfillmenttools.com/api/tags/{tagId}
```

```json
{
    "actions": [
        {
            "action": "AddAllowedValueToTag",
            "allowedValue": "amazon"
        }
    ],
    "version": 1
}
```

A successful request returns an `200 OK` response with the updated tag object in the body:

```json
{
    "id": "channel",
    "allowedValues": [
        "marketplace",
        "webshop",
        "amazon"
    ],
    "version": 3,
    ...
}
```

The value `amazon` can now be used for the `channel` tag.