> For the complete documentation index, see [llms.txt](https://help.accentuate.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.accentuate.io/use-case-guides/other-mixed-catalog/tags-controlled.md).
# Tags (Controlled)
OVERVIEW
The Tags (Controlled) field provides a managed, governed list of tags applied to products for the purpose of Shopify-native filtering, collection automation, and search. Unlike Shopify's free-text tag field — which is unstructured and frequently polluted with inconsistent values — this field enforces a defined taxonomy of approved tag values, ensuring consistent, filterable, and machine-readable product classification.
Controlled tags are the bridge between Accentuate metafield data and Shopify's native collection and filtering engine. Where Shopify's collection conditions can filter on tags, controlled tags allow the richness of structured metafield data to power native Shopify features without requiring custom storefront development. They also ensure that when products are exported, synced to marketplaces, or ingested by AI systems, the tag data is clean, consistent, and parseable.
BUSINESS VALUE
Why this field matters
* Controlled tags power Shopify automated collection logic — clean, consistent tag values create reliable, self-maintaining collections
* Shopify's storefront filter (Search & Discovery app) uses tags as filter options — inconsistent tags create broken or unusable filters
* Marketplace and channel integrations (Google Shopping, Meta Catalogue) consume tag data for categorisation — dirty tags create miscategorisation
* AI training and recommendation systems require consistent vocabulary — 'Waterproof', 'waterproof', and 'water proof' are three different values to a machine
* Controlled tag governance reduces the long-term data debt of an unmanaged tag taxonomy — cleaning up 10,000 products with inconsistent tags is an expensive operation
* Editorial and content teams use tags to curate product selections for editorial features, email campaigns, and seasonal promotions — controlled tags make this programmatic rather than manual
ACF SETUP
How to configure this field in Accentuate Custom Fields
| Where | ACF dashboard → Templates tab → Product scope → Add new field |
| ----------- | ------------------------------------------------------------- |
| Label | Tags (Controlled) |
| Name / Key | tags\_controlled |
| Namespace | accentuate (default) |
| Field type | Shopify >> Single-line text (List) |
| Multi-value | Yes — multiple controlled tags apply to each product |
| Implementation note: Tags in this field are managed and governed separately from Shopify's native product tags. The values in this field should be defined in a brand tag taxonomy document and communicated to all team members who populate product data. Consider using ACF's dropdown or predefined values configuration to restrict entries to approved taxonomy values only. |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
STEP-BY-STEP IN ACF
* Open ACF, go to Templates tab and select the Product scope
* Click 'Add new field'
* Label: 'Tags (Controlled)' — Key auto-fills as 'tags\_controlled'
* Namespace: leave as 'accentuate'
* Field type: Shopify >> Single-line text (List)
* Enable 'Allow multiple selections' — each product carries multiple tags
* Click Done, then Save
* Define your approved tag taxonomy before populating — document it and distribute it to all data entry team members
| Governance is mandatory: Tags (Controlled) has no value without a defined and enforced taxonomy. Before populating this field across your catalogue, define your approved tag list, document it, and assign ownership for maintaining it. A controlled tag field populated without governance will become as polluted as an uncontrolled one — just more slowly. |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
REFERENCE VALUES
Example controlled tag categories — define your own taxonomy based on your catalogue and business needs
| Tag category / Value | When to use |
| -------------------- | ----------------------------------------------------------------------------------------------------------- |
| new-arrival | Recently launched products — used for 'New In' collections and homepage feature slots |
| bestseller | Top-selling products by category — driven by sales data, not editorial opinion |
| sale | Products currently in a sale or promotional price event — removed when sale ends |
| clearance | End-of-line or excess stock products — distinct from temporary sale pricing |
| gift-idea | Products suitable for gifting — used for gift guide collections and seasonal campaigns |
| eco-friendly | Products meeting a defined sustainability standard — not a self-declared claim; must meet internal criteria |
| award-winner | Products that have received a named award — specify the award in Key Attributes |
| limited-edition | Products in a defined limited production run — removed when stock is exhausted |
| bundle-eligible | Products available as part of a bundle promotion — used by bundle logic in the storefront |
| staff-pick | Products selected by the buying or editorial team as standout recommendations |
| seasonal:\[season] | Seasonal relevance tags — e.g. 'seasonal:winter', 'seasonal:summer'; replaced each season |
| collection:\[name] | Campaign or editorial collection membership — e.g. 'collection:base-camp-essentials' |
BEST PRACTICES
* Define your complete tag taxonomy before any data entry — the taxonomy should be a living document with version history
* Use lowercase and hyphens for tag values to ensure compatibility with Shopify's handleize filter and URL generation
* Assign tag governance ownership — one person or team should be responsible for approving new tags and auditing existing ones
* Conduct a quarterly tag audit — remove expired tags (sale, seasonal, limited-edition) and check for taxonomy drift
* Mirror the most important metafield values as controlled tags where Shopify collection logic requires them — this bridges ACF's structured data with Shopify's native filtering
* Document what each tag means and when it should be applied — prevent ambiguous tag usage through explicit governance documentation
COMMON MISTAKES
* Creating tags ad hoc as products are added — without a taxonomy, each new team member adds their own tag variants
* Mixing formats: 'Bestseller', 'best-seller', 'BESTSELLER', and 'best seller' are four different tags; standardise on one format
* Not removing time-sensitive tags when their trigger condition ends — a product tagged 'sale' after its sale ends appears incorrectly in sale collections
* Using tags as a substitute for structured metafields — 'waterproof' as a tag is less powerful than 'Waterproof' as a Weather Suitability value; use both where appropriate
* Failing to document the tag taxonomy — undocumented tags are indistinguishable from uncontrolled tags within six months
IN CONTEXT
| Merino Base Layer — Long Sleeve |
|
| ------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Tags (controlled) | new-arrival, bestseller, gift-idea, eco-friendly, staff-pick, seasonal:winter, collection:layering-system |
| Key attributes | Odour-resistant, Quick-dry, Sustainably sourced |
| Target audience | Men, Women |
| Activity | Hiking, Skiing, Trail running, Mountaineering |
DEVELOPER IMPLEMENTATION
| Liquid note: Shopify >> List — use .value for the array. Controlled tags in this metafield can also be synced to Shopify's native product.tags via a bulk operation or integration script, enabling Shopify's native collection automation to consume them. |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Liquid — Storefront Rendering
\| {% comment %}
Tags (Controlled) — Shopify >> Single-line text (List)
Namespace: accentuate | Key: tags\_controlled
Use for badge rendering and collection membership signals
{% endcomment %}
{% assign ctrl\_tags = product.metafields.accentuate.tags\_controlled.value %}
{% if ctrl\_tags != blank %}
\
{% if ctrl\_tags contains 'bestseller' %}
\Bestseller\
{% endif %}
{% if ctrl\_tags contains 'new-arrival' %}
\New\
{% endif %}
{% if ctrl\_tags contains 'sale' %}
\Sale\
{% endif %}
\
{% endif %}
|
\| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Pro tip: Mirror controlled tags to Shopify's native product.tags field using a bulk operation whenever tags are updated. This ensures Shopify's automated collection conditions (which read native tags) stay in sync with your ACF-managed taxonomy — without requiring all collection logic to be rebuilt in Liquid. |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
SEE ALSO
* Key attributes — key attributes and controlled tags serve different purposes; key attributes describe the product, controlled tags classify it within catalogue and campaign logic
* Relationships — for products that belong to product families or sets, relationships provide a more structured version of collection membership
* All category-specific metafields — the most important values from specific fields are often mirrored as controlled tags for Shopify-native filtering
| Full ACF documentation: help.accentuate.io \| Metafield Definitions → Fields → Field data type → Shopify field types |
| -------------------------------------------------------------------------------------------------------------------- |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://help.accentuate.io/use-case-guides/other-mixed-catalog/tags-controlled.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.