Skip to main content
Catalog attributes come directly from your Shopify product data. Their code corresponds to your product schema using dot notation, which allows for the targeting of attributes or nested attributes within your data structure. For example, a product with a custom metafield called “material” stored under the “custom” namespace would have the attribute code metafields.custom.material. This dot notation lets you reach into nested product data to create precise, targeted attributes.

​
Nested metafield object keys

When metafield values are JSON objects, you can create attribute codes that access nested object keys. The namespace and key portions must be alphanumeric with underscores, but object keys can contain spaces and special characters. For instance, if you have a “color_family” metafield that maps specific shades to general color groups, you can create an attribute that targets each individual mapping within that metafield. This enables you to:
  • Create filterable attributes for nested metafield values to enable faceted navigation
  • Sort products by nested metafield object values
  • Use nested values in merchandising rules and collection filters
This syntax works for both product metafields and variant metafields.

​
Supported attribute codes

Catalog attribute codes reference product fields using dot notation. The following codes can be made filterable, sortable, or searchable just like any other catalog attribute:
Boolean fields (is_gift_card, published_on_web, published_on_app, has_variants_that_require_components) are indexed as numeric 1 / 0 values, so you can use them in numeric filter expressions and sort orders.

​
Searching on variant barcodes

variants.barcode is provisioned automatically on every store. New stores get it enabled as a searchable attribute, so shoppers and staff can look up products by scanning or typing a barcode. Existing stores get the attribute record with search disabled. To opt in, go to Attributes in the dashboard, open variants.barcode, and turn on Searchable or set a keyword search weight. Barcodes are indexed as exact-match values, which makes them ideal for autocomplete and full search but not useful as a storefront facet.

​
On-sale attributes

Every store gets two system boolean attributes for on-sale status. They are evaluated at query time from each variant’s compare_at_price and price, so they always reflect the current state of the catalog without a separate sync:
  • on_sale — product-level. True when at least one of the product’s variants has a compare-at price higher than its price.
  • variants.on_sale — variant-level. True when that specific variant has a compare-at price higher than its price.
Use these attributes anywhere you would use a boolean field: in filter expressions on Search and Browse requests, as priority rule or weighted group conditions in a sort order, or as merchandising rule conditions. They are more accurate than checking compare_at_price is not null, because a variant only counts as on sale when its compare-at price is actually greater than its price.
on_sale and variants.on_sale are seeded with Filterable, Searchable, and storefront facet options turned off by default. Open the attribute on the Attributes page to enable it as a facet or filter for your storefront.

​
Filtering by Shopify Market

When markets sync is on, every product carries an available_market_ids array of the Shopify Markets it is published to. Create a filterable attribute with code available_market_ids and value type number to expose this as a facet. Use it to let merchandisers segment a collection by region or to power per-market sort orders. The relation index is refreshed automatically whenever a product’s market availability changes, so filters stay in sync with Shopify without a full catalog re-sync.

​
Automatic metafield attribute creation

When your catalog is synced, the system automatically creates attributes for metafields that exist on your products but don’t have formal metafield definitions in Shopify. The system creates these attributes with conservative defaults (all search/filter settings disabled) to ensure they don’t affect your search experience until you explicitly configure them. Default settings for auto-created metafield attributes:
  • Searchable: Disabled
  • Filterable: Disabled
  • Sortable: Disabled
  • Partial Matching: Disabled
You can review and configure these attributes on the Attributes page after they’re created. This ensures that all product data is available for configuration, even if metafield definitions haven’t been set up in Shopify.

​
Creating attributes from metafields

You can create catalog attributes directly from your Shopify metafield definitions on the Metafields & Metaobjects settings page. This is useful when you want to quickly make specific metafields available for search, filtering, or sorting without manually entering attribute codes. How to create a single attribute:
1

Go to the metafields page

Go to Settings → Metafields & Metaobjects in the dashboard.
2

Select the metafield tab

Choose either the Product Metafields or Variant Metafields tab depending on where the metafield is defined.
3

Find the metafield

Locate the metafield you want to create an attribute for. The Attribute column shows whether an attribute already exists for each metafield.
4

Click Create

Click the Create button next to any metafield that does not yet have an attribute. The attribute is created immediately with the correct code and a default nickname derived from the metafield name.
How to create attributes in bulk:
1

Select metafields

Use the checkboxes on the left side of the table to select multiple metafields. You can also use the header checkbox to select all visible metafields at once.
2

Click Create Attributes

Click the Create Attributes button that appears in the top-right corner. The count shown on the button reflects only the selected metafields that do not already have attributes.
Newly created attributes use conservative defaults: searchable, filterable, and sortable are all disabled. After creation, navigate to the Attributes page to configure each attribute’s settings for your use case.
You can create up to 100 attributes at a time using bulk creation. Metafields that already have a matching attribute are automatically skipped.

​
Next steps