# Update user-defined tags for a listing.

`PUT /listings/{listing_id}/tags`

> Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-put-tags · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmPutTags` · Tag: Listing Tags

Adds (or overwrites) tags on a listing. If `overwrite` is false, provided tags are merged with existing tags. If `overwrite` is true, existing tags are replaced and all tags that are not in the list are deleted. A user with *restricted editor* access to a shared listing may read its tags but not change them.

## Request

`PUT https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/tags`

Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). |

### Request body (`application/json`, required)

- `names` (array of string, required): Array of tag names to add (or set if `overwrite` is true).
- `overwrite` (boolean, default: `false`): If true, replaces all existing tags with the provided list. If false (default), merges with existing tags.

### Example request

```bash
curl -X PUT 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/tags?channel=<channel>' \
  -H 'X-Integration-Api-Key: <your RM API key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "names": [
    "string"
  ]
}'
```

Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say.

## Responses

### 200

The listing's updated tags.

Body (`application/json`): array of object `tag_response`

A listing tag.

- `id` (integer): The tag ID.
- `name` (string): The tag name.
- `description` (string, nullable): An optional description of the tag, or `null` when none was set.
- `type` (string): The tag type, `UserTag` or `ImportedTag`.

Example shape (generated from the schema; placeholder values, not a real response):

```json
[
  {
    "id": 0,
    "name": "string",
    "description": "string",
    "type": "string"
  }
]
```

### 401

API key authorization failed.

### 403

Listing authorization failed (including a restricted editor on a shared listing), or the API key is read-only and may not be used with PUT.

### 404

Listing not found.

### 406

The listing is inactive. See the **Inactive Listings** section in the overview.

Body (`application/json`): object

- `error` (string, example: `Listing '12345' is inactive`)

Example shape (generated from the schema; placeholder values, not a real response):

```json
{
  "error": "Listing '12345' is inactive"
}
```

### 409

Another request is already in progress for this listing. Retry after the concurrent request completes.

### 429

Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy.

Body (`application/json`): object

- `error` (string, example: `API token is at rate limit`)

Example shape (generated from the schema; placeholder values, not a real response):

```json
{
  "error": "API token is at rate limit"
}
```
