# Add tags to orders, customers or products in bulk

> Tag one resource with tagsAdd without overwriting its tags, or thousands at once by running tagsAdd in a bulk mutation operation.

Page: https://lintelagency.com/resources/graphql/bulk-add-tags

## In short

To tag a resource without touching its existing tags, call tagsAdd with its ID and the new tags; it works on orders, draft orders, customers, products and articles. For thousands of resources, write one line per resource ({"id", "tags"}) to a JSONL file, upload it with stagedUploadsCreate and run tagsAdd through bulkOperationRunMutation. tagsRemove works the same way.

## Facts

- **API:** Admin GraphQL API
- **Operations:** tagsAdd, bulkOperationRunMutation
- **Access scope:** Write access to the tagged resource, such as orders, customers or products
- **Replaces (REST):** PUT /admin/api/orders/{id}.json with the full tags string
- **API version:** 2026-10
- **Last checked:** 2 November 2026

## How to use it

1. For a single resource, send TagOrder with its GID and the tags to add.
2. For many, write tags.jsonl with one {"id", "tags"} object per line.
3. Upload the file as in the staged upload recipe and keep the key.
4. Send TagOrdersInBulk with the tagsAdd mutation string and the key, then check the results file for userErrors per line.

## Code

### tags-add.graphql

```graphql
mutation TagOrder($id: ID!, $tags: [String!]!) {
  tagsAdd(id: $id, tags: $tags) {
    node {
      id
    }
    userErrors {
      field
      message
    }
  }
}
```

### tags-add.variables.json

```json
{
  "id": "gid://shopify/Order/1234567890",
  "tags": ["wholesale", "priority"]
}
```

### tags-add.response.json

```json
{
  "data": {
    "tagsAdd": {
      "node": {
        "id": "gid://shopify/Order/1234567890"
      },
      "userErrors": []
    }
  }
}
```

### tags.jsonl

```text
{"id":"gid://shopify/Order/1111111111","tags":["wholesale"]}
{"id":"gid://shopify/Order/1111111112","tags":["wholesale"]}
{"id":"gid://shopify/Order/1111111113","tags":["wholesale","priority"]}
```

### bulk-operation-run-mutation.graphql

```graphql
mutation TagOrdersInBulk($mutation: String!, $stagedUploadPath: String!) {
  bulkOperationRunMutation(mutation: $mutation, stagedUploadPath: $stagedUploadPath) {
    bulkOperation {
      id
      status
    }
    userErrors {
      code
      field
      message
    }
  }
}
```

### bulk-operation-run-mutation.variables.json

```json
{
  "mutation": "mutation TagOrder($id: ID!, $tags: [String!]!) { tagsAdd(id: $id, tags: $tags) { node { id } userErrors { field message } } }",
  "stagedUploadPath": "tmp/1234567890/bulk/00000000-0000-0000-0000-000000000000/tags.jsonl"
}
```

### bulk-operation-run-mutation.response.json

```json
{
  "data": {
    "bulkOperationRunMutation": {
      "bulkOperation": {
        "id": "gid://shopify/BulkOperation/1234567892",
        "status": "CREATED"
      },
      "userErrors": []
    }
  }
}
```

## Limits and edge cases

- tagsAdd only adds; tags already on the resource stay. Updating tags through orderUpdate or productUpdate replaces the whole list.
- tags accepts a list or one comma-separated string.
- If the ID belongs to a type that can’t be tagged, the mutation returns a not-found error.
- In a bulk run each line is one tagsAdd call, so the results file shows success or userErrors per resource.

## Questions

### How do I bulk tag orders in Shopify?

Run tagsAdd through bulkOperationRunMutation with a JSONL file of order IDs and tags. For a few hundred orders, calling tagsAdd in a loop also works.

### Does tagsAdd remove existing tags?

No. It only adds the tags you send. Use tagsRemove to take tags off.

### Which resources can I tag with tagsAdd?

Orders, draft orders, customers, products and articles, among others listed in the reference.

## Shopify documentation

- [tagsAdd](https://shopify.dev/docs/api/admin-graphql/latest/mutations/tagsAdd)
- [Bulk import data](https://shopify.dev/docs/api/usage/bulk-operations/imports)

## Related

- [Import data with a staged upload and bulkOperationRunMutation](https://lintelagency.com/resources/graphql/bulk-import-with-staged-upload)
- [Export orders for a date range with a bulk operation](https://lintelagency.com/resources/graphql/bulk-export-orders-by-date)

License: MIT. Free to use in your own store and in client work.