# Tag Shipments

Tags are simple text-based flags or identifiers that you can add to shipments. Adding tags to shipments can help you [query shipments](/list-shipments) later. Tags can be a simple label, like `Guaranteed_Overnight` or `Fragile`, whatever you need to help you in your workflow.

## Create Tags

You can create the tags you wish to use in advance and then [add tags](#add-tags-to-shipments) to your shipments. However, if you tag a shipment with a tag value that doesn't yet exist, we'll make the tag for you at the same time.

### Example Request & Response

In this example, we're creating a tag with the value `east_warehouse`. We could then add this tag to any shipment we know will ship from that warehouse.

**POST /v2/tags/:tag_name**


```http
POST /v2/tags/east_warehouse HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
```

**Response**


```json
{
 "name": "east_warehouse"
}
```

## Add Tags to Shipments

Once you've created the tags you wish to use, you can add those tags to shipments so you can more easily [query those shipments](/list-shipments) later.

### Requirements

- You'll need the `shipment_id` of the shipment you wish to tag.
- You'll need the tag value of the tag you are adding to the shipment.


New Tags
If the tag doesn't exist, we will create it for you. You can also [create tags](#create-tags) in advance manually.

### Example Request & Response

**POST /v2/shipments/:shipment_id/tags/:tag_name**


```http
POST /v2/shipments/se-2102034/tags/east_warehouse HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
```

**Response**


```json
{
 "shipment_id": "se-2102034",
 "tag": {
   "name": "east_warehouse"
 }
}
```

## List All Tags

Once you've [created some tags](#create-tags) you can use this call to list them, which can be useful if you want to, for example, have a user choose from a list of available tags to apply to a shipment.

The response will be an array of the tag names available to your account.

### Example Request & Response

**GET /v2/tags/**


```http
GET /v2/tags HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
```

**Response**


```json
{
 "tags": [
   {
     "name": "east_warehouse"
   },
   {
     "name": "west_warehouse"
   }
 ]
}
```

## Remove a Shipment Tag

Use this call to remove a tag from a shipment. You'll need both the `shipment_id` and `tag_name` to perform this action successfully.

### Example Request & Response

**DELETE /v2/shipments/:shipment_id/tags/:tag_name**


```http
DELETE /v2/shipments/se-2102034/tags/east_warehouse HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
```

If successful, you will receive **HTTP 204, No Content** in the response.