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.
- 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
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.
How to use it
- For a single resource, send TagOrder with its GID and the tags to add.
- For many, write tags.jsonl with one {"id", "tags"} object per line.
- Upload the file as in the staged upload recipe and keep the key.
- Send TagOrdersInBulk with the tagsAdd mutation string and the key, then check the results file for userErrors per line.
Code
tags-add.graphqlmutation TagOrder($id: ID!, $tags: [String!]!) {
tagsAdd(id: $id, tags: $tags) {
node {
id
}
userErrors {
field
message
}
}
}
tags-add.variables.json{
"id": "gid://shopify/Order/1234567890",
"tags": ["wholesale", "priority"]
}
tags-add.response.json{
"data": {
"tagsAdd": {
"node": {
"id": "gid://shopify/Order/1234567890"
},
"userErrors": []
}
}
}
tags.jsonl{"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.graphqlmutation TagOrdersInBulk($mutation: String!, $stagedUploadPath: String!) {
bulkOperationRunMutation(mutation: $mutation, stagedUploadPath: $stagedUploadPath) {
bulkOperation {
id
status
}
userErrors {
code
field
message
}
}
}
bulk-operation-run-mutation.variables.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{
"data": {
"bulkOperationRunMutation": {
"bulkOperation": {
"id": "gid://shopify/BulkOperation/1234567892",
"status": "CREATED"
},
"userErrors": []
}
}
}
Written by Lintel. MIT license: free to use in your own store and in client work.
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
- Validated against the Admin or Storefront API schema for version 2026-10 on the date shown. Check the version in your request URL.
- IDs and store addresses in the examples are placeholders. Replace them with your own.
- Admin API calls need an access token from your app. Never put an Admin API token in a storefront or theme.
- MIT license. Use the code in your own store or in client work.
Need this built, tested and maintained for your store? See API integrations.
