> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pazy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tag Value Update API

> Enable or disable one or more values of an existing dropdown tag

## Authentication

All requests require an API key in the request headers.

**Headers:**

```
Authorization: Api-Key YOUR_API_KEY
Content-Type: application/json
```

## Request

**Content-Type:** `application/json`

This endpoint updates the state of one or more values of an existing **dropdown** tag. Use the tag's slug (from the [Tag List API](/apis/tag-list)) as the `tagId` path parameter, and the value ids (from the [Tag Detail API](/apis/tag-detail) or [Tag Value Creation API](/apis/tag-value-creation)) in the body.

Every id in the payload must belong to the tag identified by `tagId` — if any id does not, the entire request is rejected and no value is updated.

### Path Parameters

| Parameter | Type   | Required | Description                                                                          |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------ |
| `tagId`   | string | Yes      | Slug identifier of the dropdown tag whose values are being updated (1–64 characters) |

### Body Parameters

| Parameter      | Type    | Required | Description                                                                                         |
| -------------- | ------- | -------- | --------------------------------------------------------------------------------------------------- |
| `tags`         | array   | Yes      | Tag values to update. Min 1, Max 100 items.                                                         |
| `tags[].id`    | integer | Yes      | Id of the tag value to update (minimum 1). Obtain this from the [Tag Detail API](/apis/tag-detail). |
| `tags[].state` | string  | Yes      | The state to set on the tag value. Allowed values: `ENABLED`, `DISABLED`.                           |

### Tag Value State Values

| Value      | Description                                                            |
| ---------- | ---------------------------------------------------------------------- |
| `ENABLED`  | The value is active and can be selected on new transactions            |
| `DISABLED` | The value is retired and can no longer be selected on new transactions |

<Note>
  When a value is disabled, Pazy checks whether it is still in use on any open transaction (invoices, reimbursements, expenses, purchase orders, and similar). If it is in use, the value is kept as `DEPRECATED` so existing records stay intact. If it is not in use anywhere, the value is fully retired to `DISABLED` and is also cleared from any vendor it was mapped to as a default. Either way the request succeeds — the state reported by the [Tag Detail API](/apis/tag-detail) afterwards reflects the outcome.
</Note>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH https://api.pazy.io/v1.0/tag/cost-center/value \
    -H "Authorization: Api-Key YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "tags": [
        { "id": 1024, "state": "DISABLED" },
        { "id": 1025, "state": "ENABLED" }
      ]
    }'
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  const response = await fetch('https://api.pazy.io/v1.0/tag/cost-center/value', {
    method: 'PATCH',
    headers: {
      'Authorization': 'Api-Key YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      tags: [
        { id: 1024, state: 'DISABLED' },
        { id: 1025, state: 'ENABLED' }
      ]
    })
  });

  const result = await response.json();
  ```

  ```python Python (requests) theme={null}
  import requests

  url = "https://api.pazy.io/v1.0/tag/cost-center/value"
  headers = {
      "Authorization": "Api-Key YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  payload = {
      "tags": [
          { "id": 1024, "state": "DISABLED" },
          { "id": 1025, "state": "ENABLED" }
      ]
  }

  response = requests.patch(url, headers=headers, json=payload)
  result = response.json()
  ```
</CodeGroup>

## Success Response

**HTTP Status:** `200 OK`

**Response Fields:**

| Field     | Type    | Description                                   |
| --------- | ------- | --------------------------------------------- |
| `ok`      | boolean | Indicates whether the request was successful  |
| `updated` | boolean | Indicates whether the tag values were updated |

### Response Example

```json theme={null}
{
  "ok": true,
  "updated": true
}
```

## Error Responses

### Tag Is Not a Dropdown

Returned when the target tag is not a dropdown tag (only dropdown tag values can be updated).

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Tag should be dropdown"
  }
}
```

### Tag Value Does Not Belong to the Tag

Returned when one or more ids in the payload do not exist under the tag given in the path. No value is updated in this case. The same error is returned when the tag slug itself does not exist.

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Tag value id 2048, 2049 does not belong to the tag cost-center"
  }
}
```

### Validation Error

Returned when the required `tags` array is missing, empty, contains more than 100 items, or an item has an unsupported `state`.

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: /body: must have required property 'tags'"
  }
}
```

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: /body/tags/0/state: must be equal to one of the allowed values"
  }
}
```

### Access Denied

**HTTP Status:** `403 Forbidden`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "Access denied: Only admin and bookkeeper can update this resources"
  }
}
```

### Authentication Errors

**HTTP Status:** `401 Unauthorized`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "Missing Credentials"
  }
}
```

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API Key"
  }
}
```

### Permission Errors

**HTTP Status:** `403 Forbidden`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Permission check failed - PERMISSION_CHECK_FAILED"
  }
}
```

### Tag Value Update Failed

In the rare case the values could not be persisted, the response is returned with an HTTP `200 OK` status, `ok: false`, and `updated: false`.

**HTTP Status:** `200 OK`

```json theme={null}
{
  "ok": false,
  "updated": false
}
```

## Best Practices

* Only `DROPDOWN` tag values can be updated — use the [Tag List API](/apis/tag-list) to confirm the tag's `dataType` before calling
* Fetch the value ids with the [Tag Detail API](/apis/tag-detail); passing an id that belongs to a different tag rejects the whole request
* Batch related changes into a single call — up to 100 values can be updated at once
* Always check the `updated` flag in addition to the HTTP status; a failure is returned with `ok: false` and `updated: false` under a `200 OK` status
* Disabling a value does not alter transactions that already carry it — it only stops the value from being selected going forward
* Access is limited to users with tag update permission and an admin or bookkeeper role