Catalog Attributes

​

Foundational Architecture

​

Attribute Types

​

Catalog Attributes

{
  "metafields": {
    "custom": {
      "material": "Cotton"
    }
  }
}

​

Nested Metafield Object Keys

{
  "metafields": {
    "algolia": {
      "color_family": {
        "dark orange": "orange",
        "light blue": "blue"
      }
    }
  }
}

• metafields.algolia.color_family.dark orange → accesses the value "orange"
• metafields.algolia.color_family.light blue → accesses the value "blue"

• 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

​

Automatic Metafield Attribute Creation

• Searchable: Disabled
• Filterable: Disabled
• Sortable: Disabled
• Partial Matching: Disabled

​

Calculated Attributes

​

Automatic Product Recalculation

​

Data Access in Calculated Attributes

• Catalog Attributes: Use _attribute:{attribute_code} to reference existing catalog attributes. For example, _attribute:price_range.from or _attribute:published_at.
• Raw Data: Use _raw:raw.{path} to access raw underlying Shopify data before transformation. Use dot notation for nested properties. For example, _raw:raw.variants or _raw:raw.featured_media.

​

AI-Powered Calculated Attributes

Generate with AI

1. Navigate to Attributes → Create new calculated attribute
2. Click the Generate with AI button next to “Value Formula”
3. Enter a natural language description of what you want to calculate (minimum 10 characters)
   • Example: “Calculate the discount percentage from compare_at_price to current price”
   • Example: “Count the total number of variants”
   • Example: “Calculate days since published”
4. Click Generate to start the AI generation process
5. Monitor real-time progress updates as the AI generates and validates the expression
6. Review the generated JSONLogic in the preview
7. Click Apply to Form to use the generated expression

• Attempt 1: Initial generation based on your description
• Attempts 2-3: If validation fails, the AI receives error feedback and attempts to correct the expression
• Real-time updates: WebSocket events broadcast progress (generating → retrying → completed/failed)
• Validation: Each generated expression is validated for correct JSONLogic syntax and proper dependency prefixes

Explain with AI

1. Create or edit a calculated attribute with JSONLogic
2. Scroll to the “What does this formula do?” section below the formula builder
3. Click Explain with AI
4. Review the plain-language explanation of your formula

• JSONLogic: {"/": [{"-": [{"var": "_attribute:compare_at_price"}, {"var": "_attribute:price"}]}, {"var": "_attribute:compare_at_price"}]}
• Explanation: “Calculates the discount percentage by comparing the original price to the current selling price. For example, if a product was $100 and is now$75, this would return 0.25 (25% off).”

​

Platform Default Calculated Attributes

{
  "/": [
    {
      "reduce": [
        {
          "map": [
            { "var": "_raw:raw.variants" },
            { "if": [ { "var": "available" }, 1, 0 ] }
          ]
        },
        { "+": [ { "var": "accumulator" }, { "var": "current" } ] },
        0
      ]
    },
    { "count": { "var": "_raw:raw.variants" } }
  ]
}

{
  "daysSince": {
    "parseDate": {
      "or": [
        { "var": ["_attribute:published_at", null] },
        { "var": ["_attribute:created_at", null] }
      ]
    }
  }
}

{
  "!!": {
    "var": "_raw:raw.featured_media"
  }
}

{
  "daysSince": {
    "reduce": [
      {
        "map": [
          {
            "var": "_raw:raw.variants"
          },
          {
            "parseDate": {
              "var": "created_at"
            }
          }
        ]
      },
      {
        "if": [
          {
            "or": [
              {
                "==": [
                  {
                    "var": "accumulator"
                  },
                  null
                ]
              },
              {
                ">": [
                  {
                    "var": "current"
                  },
                  {
                    "var": "accumulator"
                  }
                ]
              }
            ]
          },
          {
            "var": "current"
          },
          {
            "var": "accumulator"
          }
        ]
      },
      null
    ]
  }
}

{
  "!==": [
    {
      "var": "_attribute:price_range.from"
    },
    {
      "var": "_attribute:price_range.to"
    }
  ]
}

​

Additional Calculated Attribute Recipes

{
  "if": [
    {
      "and": [
        { "var": "_attribute:price_range.to" },
        {
          ">": [
            { "var": "_attribute:price_range.to" },
            { "var": "_attribute:price_range.from" }
          ]
        }
      ]
    },
    {
      "*": [
        {
          "/": [
            {
              "-": [
                { "var": "_attribute:price_range.to" },
                { "var": "_attribute:price_range.from" }
              ]
            },
            { "var": "_attribute:price_range.to" }
          ]
        },
        100
      ]
    },
    0
  ]
}

{
  "count": [{ "var": "_raw:raw.variants" }]
}

​

Attribute Options

​

Searchable Attributes

​

Partial Matching

​

High-Signal Attributes

​

Filterable Attributes

​

Sortable Attributes

​

Groupable Attributes

• What it does: Treat all products with the same group value as one group (e.g., group by style_code) for ranking and reporting.
• When to use: When you want to rank or measure product families together (styles, sets, or kits).
• Where to enable: Edit an attribute and toggle “Groupable.”
• Works with: Metrics and Sort Orders.

​

Visible in API Responses

• Prevents the attribute from being used in request-level filters
• Blocks the attribute from being requested in the attributes parameter
• Excludes the attribute from API responses
• Filters nested properties from JSON response data (e.g., if a nested property is marked as non-visible, it will be stripped from the parent object in responses)

• For internal-only attributes like calculated fields used for merchandising rules
• For sensitive data that should not be exposed to the storefront

• All attributes default to visible in API responses
• Calculated attributes automatically default to not visible in API responses

​

Enable as Storefront Facet

• When enabled, creates and syncs a metaobject in Shopify for the filterable attribute
• When disabled, deletes the metaobject from Shopify (if it exists)
• Controls whether the attribute can be used for native Shopify storefront filtering

• Enable for filterable attributes that should be available for Shopify storefront filtering
• Disable for filterable attributes that are only used internally or through the Layers API

• All filterable attributes default to enabled as storefront facets
• Non-filterable attributes cannot be enabled as storefront facets

• Visible in API Responses: Controls whether the attribute appears in Layers API responses
• Enable as Storefront Facet: Controls whether the attribute is synced to Shopify metaobjects

• Visible in API responses but not enabled as a storefront facet (available through Layers API only)
• Enabled as a storefront facet but not visible in API responses (available for Shopify filtering only)
• Both enabled (available through both Layers API and Shopify filtering)

​

Attribute Classes

​

Categorical Attributes

​

Feature Attributes

​

Price Attributes

​

AI Attribute Suggestions

​

How It Works

• Data type and structure: Whether values are numeric, categorical, or text-based
• Value distribution: How many unique values exist and their patterns
• Search relevance: Which attributes customers are likely to search for
• Filter utility: Which attributes make useful facets for product filtering
• Sort potential: Whether values can be meaningfully ordered

• Searchable: Whether the attribute should be included in text search
• Filterable: Whether the attribute should appear as a facet
• Sortable: Whether products can be sorted by this attribute
• Groupable: Whether products should be grouped by this attribute
• Partial Matching: Whether partial text matches should be allowed
• Value Type: Whether values should be treated as strings or numbers

​

Accessing AI Suggestions

​

1. AI Suggestions Button (Attributes List Page)

​

2. Suggestion Panel (Individual Attribute Page)

• The suggested setting changes
• AI reasoning explaining why these settings are recommended
• Accept and Dismiss buttons to apply or ignore the suggestions

​

3. Suggestions List Page

​

Reviewing and Applying Suggestions

​

Managing Suggestions

​

Automatic Suggestion Generation

1. Generates suggestions for all catalog attributes (excluding system attributes like id, title, handle)
2. Skips attributes that have received suggestions within the last 7 days
3. Runs analysis in the background without impacting store performance
4. Updates the suggestions list as new attributes are added to your catalog

• The feature is first enabled for your store
• New attributes are created in your catalog
• Existing attributes haven’t been analyzed in over 7 days

​

Best Practices

• Use clear, descriptive nicknames for attributes to easily manage and identify them on the dashboard.
• When setting up searchable attributes, consider the search behavior of your customers and which attributes are most relevant to their queries.
• For filterable attributes, think about the facets that are most useful for customers when browsing your product range.
• Regularly review and update your attributes to keep up with changes in your product catalog and customer search behavior.
• Review AI suggestions regularly to optimize your attribute configurations based on actual product data.
• Accept AI suggestions for attributes you’re unsure about, but verify they align with your merchandising strategy.

​

See also

• Configure search behavior
• Test collections and similar products