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

# Merge Tags

> Merge one tag into another

Merge the tag in the path into `targetTagId`. Every subscriber that carries the merged tag gets the target tag instead, and the merged tag is deleted. This cannot be undone.

Merging does not start sequences that trigger when the target tag is added, and it records no tag activity: it reorganizes your tags rather than tagging anyone anew.

The merge is refused with `409` while a sequence, segment, campaign, email, sync rule, goal, integration, form, popup or landing page still uses the merged tag. The response lists them in `usage`; remove the tag there first. Campaigns that were already sent or cancelled are not checked. Nothing has to change for the target tag.

System tags cannot be merged, in either direction.

Because the merged tag is deleted, the API key needs the `tags:delete` scope as well as `tags:write`.

## Request

**tagId** `string` *required*

ID of the tag to merge away. It is deleted.

**targetTagId** `string` *required*

ID of the tag to keep.

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/tags/tag_abc123/merge" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"targetTagId": "tag_def456"}'
```

## Responses

`tag` is the tag that was kept. `contactsUpdated` counts the subscribers moved to it.

A merged tag on more than 20,000 subscribers answers `202` with `"status": "processing"` and no count. The subscribers move in the background, usually within minutes, and the merged tag is deleted last. Until then, a rename, merge or delete of any tag in the company answers `409` with code `tag_in_progress`, and [List Tags](https://docs.sequenzy.com/api-reference/tags/list.md) includes `changeInProgress`.

```json 200 theme={null}
{
  "success": true,
  "tag": {
    "id": "tag_def456",
    "name": "motionlens",
    "color": "gray",
    "isSystem": false
  },
  "status": "completed",
  "contactsUpdated": 342
}
```

```json 202 theme={null}
{
  "success": true,
  "tag": {
    "id": "tag_def456",
    "name": "motionlens",
    "color": "gray",
    "isSystem": false
  },
  "status": "processing"
}
```

```json 400 theme={null}
{
  "success": false,
  "error": "Choose a different tag to merge into",
  "code": "tag_same_tag"
}
```

```json 401 theme={null}
{
  "error": "Invalid API key"
}
```

```json 403 theme={null}
{
  "success": false,
  "error": "Cannot merge system tags",
  "code": "tag_system_tag"
}
```

```json 404 theme={null}
{
  "error": "Tag not found"
}
```

```json 409 theme={null}
{
  "success": false,
  "error": "Cannot merge tag: \"motionlens-import\" is used in form \"Lead magnet\". Remove it there first.",
  "code": "tag_in_use",
  "usage": [{ "kind": "form", "name": "Lead magnet" }]
}
```

A `403` without a `code` means the API key lacks the `tags:delete` scope. A `404` is returned when either tag does not exist in your company. A `409` with code `tag_changed` means one of the tags was changed by another request at the same moment: send the request again. A `409` with code `tag_in_progress` means a large rename or merge is still running: try again in a few minutes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.