Metaobjects & Metafields

Overview

Layers automatically creates and manages metaobjects and metafields in your Shopify store to synchronize configuration data between the two platforms. This enables features like setting default sort orders on collections directly from Shopify and provides the necessary tokens for storefront integrations. These resources are created automatically when you install Layers and are kept in sync as you make changes in the Layers dashboard.

Metaobjects

Layers creates three types of metaobjects in your Shopify store to represent key configuration entities. These metaobjects allow Shopify to reference Layers configurations natively, enabling features like assigning sort orders to collections directly from the Shopify admin.

Sort Order Metaobject

The Sort Order metaobject represents sort orders configured in Layers. Each sort order you create in the Layers dashboard is automatically synced to Shopify as a metaobject. Type: $app:sort_order Definition Name: Layers Sort Order Description: Sort orders managed by Layers for product sorting

Field Definitions

Field	Type	Required	Description
name	single_line_text_field	Yes	The display name of the sort order
code	single_line_text_field	Yes	The unique code identifier for the sort order
scope	list.single_line_text_field	No	The contexts where this sort order is available (search, collection)
order	number_integer	No	The display order of the sort order

Example Metaobject

{
  "type": "$app:sort_order",
  "handle": "layers-sort-order-abc123",
  "fields": {
    "name": "Best Selling",
    "code": "best_selling",
    "scope": ["collection", "search"],
    "order": 1
  }
}

Common Sort Order Examples

Name	Code	Description
Best Selling	`best_selling`	Products ranked by sales volume
Newest	`newest`	Products sorted by creation date, newest first
Price: Low to High	`price_asc`	Products sorted by price ascending
Price: High to Low	`price_desc`	Products sorted by price descending
Relevance	`relevance`	Products ranked by search relevance score
Trending	`trending`	Products ranked by recent popularity metrics

Lifecycle

Sort order metaobjects are only synced to Shopify when the Enable as Storefront Sort option is enabled for the sort order. This option is enabled by default for regular sort orders but disabled for variant sort orders (used in experiments). When you create a new sort order with Enable as Storefront Sort enabled, a metaobject is created in Shopify. When you update the sort order’s name or code, the metaobject is updated. When you disable Enable as Storefront Sort or delete the sort order, the metaobject is removed from Shopify.

Variant sort orders used in experiments are not synced to Shopify by default. These sort orders are only used internally by the Layers API for A/B testing and do not need to be available as metaobjects in Shopify. If you toggle a sort order to be used as a variation, the Enable as Storefront Sort option is automatically disabled and any existing metaobject is deleted from Shopify.

The Facet metaobject represents filterable attributes (facets) configured in Layers. When you mark an attribute as filterable and enable the Enable as Storefront Facet option in the Layers dashboard, it is synced to Shopify as a facet metaobject. Type: $app:facet Definition Name: Layers Facet Description: Facets (filterable attributes) managed by Layers

Field Definitions

Field	Type	Required	Description
name	single_line_text_field	Yes	The display name of the facet
code	single_line_text_field	Yes	The unique code identifier for the facet

Example Metaobject

{
  "type": "$app:facet",
  "handle": "layers-facet-def456",
  "fields": {
    "name": "Color",
    "code": "options.color"
  }
}

Name	Code	Description
Color	`options.color`	Filter by product color option
Size	`options.size`	Filter by product size option
Brand	`vendor`	Filter by product vendor
Product Type	`product_type`	Filter by Shopify product type
Tags	`tags`	Filter by product tags
Price	`variants.price`	Filter by product price
Availability	`available`	Filter by in-stock status

Lifecycle

Facet metaobjects are created when you mark an attribute as filterable and enable the Enable as Storefront Facet toggle in Layers. They are updated when you rename the attribute or change its display name, and deleted when you disable the Enable as Storefront Facet toggle or remove the attribute from your configuration.

Simply marking an attribute as filterable is not sufficient to create a facet metaobject. You must also enable the Enable as Storefront Facet option in the attribute’s Display settings. This allows you to have filterable attributes that are only used through the Layers API without syncing them to Shopify. Learn more in Attributes.

Block Metaobject

The Block metaobject represents recommendation blocks configured in Layers. When you create a block on a managed installation, it is automatically synced to Shopify as a metaobject with publishable status capability. Type: $app:block Definition Name: Layers Recommendation Block Description: Recommendation blocks managed by Layers

Field Definitions

Field	Type	Required	Description
label	single_line_text_field	Yes	The display label of the block (formatted as “Title - AnchorType” or just the anchor type if no title)
title	single_line_text_field	No	The title of the block
anchor_type	single_line_text_field	Yes	The anchor type of the block (product, collection, cart, none)

Example Metaobject

{
  "type": "$app:block",
  "handle": "layers-block-xyz789",
  "fields": {
    "label": "Featured Products - Collection",
    "title": "Featured Products",
    "anchor_type": "collection"
  },
  "status": "ACTIVE"
}

Common Block Examples

Label	Title	Anchor Type	Description
Featured Products - Collection	Featured Products	collection	Recommendations shown on collection pages
You May Also Like - Product	You May Also Like	product	Recommendations shown on product pages
Complete Your Order - Cart	Complete Your Order	cart	Recommendations shown in the cart
Trending Now - None	Trending Now	none	Recommendations shown globally

Lifecycle

Block metaobjects are only synced for managed installations. When you create a block on a managed store, the corresponding metaobject is created in Shopify. When you update the block’s title, anchor type, or status, the metaobject is updated. When you delete the block, the metaobject is removed from Shopify. The block’s status (active or draft) is mapped to Shopify’s publishable status capability:

Active blocks → ACTIVE status in Shopify
Draft blocks → DRAFT status in Shopify

Collection Metafield

Layers creates a metafield definition on collections that allows you to set a default sort order for each collection directly from Shopify.

Default Sort Order

This metafield lets you assign a Layers sort order to a collection. When set, the Browse API will use this sort order as the default when no sort order is specified in the request. Namespace: app--{app_id}--layers (auto-generated by Shopify) Key: default_sort_order Owner Type: COLLECTION Type: metaobject_reference Validation: References $app:sort_order metaobjects only

Metafield Definition

{
  "ownerType": "COLLECTION",
  "key": "default_sort_order",
  "name": "Default Sort Order",
  "description": "The default Layers sort order for this collection",
  "type": "metaobject_reference",
  "validations": [
    {
      "name": "metaobject_definition_type",
      "value": "$app:sort_order"
    }
  ],
  "access": {
    "admin": "MERCHANT_READ_WRITE",
    "storefront": "PUBLIC_READ"
  }
}

How to Set a Default Sort Order

To set a default sort order for a collection:

Navigate to Products > Collections in your Shopify admin
Select the collection you want to configure
Scroll down to the Metafields section
Find the Default Sort Order field
Select from the available Layers sort orders in the dropdown

The selected sort order will be used automatically when browsing this collection through the Layers Browse API without specifying a sort parameter.

The default sort order metafield references the Sort Order metaobjects created by Layers. If you delete a sort order in Layers, any collections using it as the default will need to be updated to select a different sort order.

App Installation Metafields

Layers stores configuration data on the app installation to power storefront integrations, the tracking pixel, and theme app extensions. These metafields are automatically managed and should not be edited manually.

Embed Settings

Contains the API tokens and integration configuration needed for the Layers storefront pixel and SDK. Namespace: layers Key: embed_settings Type: json

Schema

{
  "apiToken": "string",
  "storefrontApiToken": "string",
  "integrations": {
    "[integration_name]": {
      "enabled": true,
      "config": {}
    }
  },
  "sessionCookieFallbacks": ["string"]
}

Field Descriptions

Field	Type	Description
apiToken	string	The analytics tracking token for event collection
storefrontApiToken	string	The storefront API token for search and browse requests
integrations	object	Map of enabled integrations with their configurations
sessionCookieFallbacks	array	Cookie names to use as session identifiers (defaults to `["_ga"]`)

Example Value

{
  "apiToken": "trk_abc123def456",
  "storefrontApiToken": "sf_xyz789ghi012",
  "integrations": {
    "klaviyo": {
      "enabled": true,
      "config": {
        "publicApiKey": "pk_abc123"
      }
    },
    "google_analytics": {
      "enabled": true
    }
  },
  "sessionCookieFallbacks": ["_ga", "_fbp"]
}

Additional Injects

Stores any additional scripts or styles configured to be injected into your storefront. Namespace: layers Key: additional_injects Type: json

Schema

{
  "scripts": ["string"],
  "styles": ["string"]
}

Field Descriptions

Field	Type	Description
scripts	array	JavaScript code snippets to inject into the storefront
styles	array	CSS code snippets to inject into the storefront

Example Value

{
  "scripts": [
    "console.log('Layers initialized');"
  ],
  "styles": [
    ".layers-search-results { max-width: 1200px; }"
  ]
}

Commerce Blocks Tokens

These metafields provide the API tokens needed for Layers theme app extensions and blocks. They are stored in a separate namespace to be accessible by Shopify’s theme app extension system. Namespace: commerce_blocks

layers_token

Key: layers_token Type: single_line_text_field Description: The storefront API token for search and browse requests from theme blocks. Example Value: sf_xyz789ghi012

layers_tracking_token

Key: layers_tracking_token Type: single_line_text_field Description: The analytics tracking token for event collection from theme blocks. Example Value: trk_abc123def456

store_config

Key: store_config Type: json Description: Basic store configuration for theme blocks.

Schema

{
  "name": "string",
  "shopDomain": "string"
}

Example Value

{
  "name": "My Awesome Store",
  "shopDomain": "my-awesome-store.myshopify.com"
}

Access Permissions

All metaobjects and metafields created by Layers are configured with appropriate access permissions to enable both admin management and storefront functionality.

Metaobject Access

Resource	Admin Access	Storefront Access
Sort Order Metaobject	MERCHANT_READ	PUBLIC_READ
Facet Metaobject	MERCHANT_READ	PUBLIC_READ
Block Metaobject	MERCHANT_READ	PUBLIC_READ

Merchants can view these metaobjects in the Shopify admin but cannot edit them directly. Changes should be made through the Layers dashboard to ensure proper synchronization.

Metafield Access

Resource	Admin Access	Storefront Access
Collection Default Sort Order	MERCHANT_READ_WRITE	PUBLIC_READ
App Installation Metafields	MERCHANT_READ	PUBLIC_READ

The collection default sort order metafield allows merchants to select a sort order from the Shopify admin. App installation metafields are read-only for merchants and are managed automatically by Layers.

Automatic Synchronization

Layers keeps these resources synchronized automatically as you make changes in the Layers dashboard: Sort Orders: When you create, update, or delete sort orders in Layers, the corresponding metaobjects are created, updated, or deleted in Shopify within seconds. Facets: When you enable the Enable as Storefront Facet toggle on filterable attributes, facet metaobjects are created in Shopify. When you disable this toggle, the metaobjects are removed. Renaming a facet in Layers updates the metaobject’s name field. App Installation Metafields: These are updated whenever relevant store settings change, such as when you generate new API tokens, enable/disable integrations, or modify tracking pixel configuration. You do not need to manually manage these resources. They are created and maintained by Layers as part of the normal integration workflow.

Do not manually delete or modify Layers metaobjects or app installation metafields in Shopify. Doing so may cause synchronization issues and break storefront functionality. If you need to make changes, use the Layers dashboard instead.

Querying Metaobjects via Storefront API

Since Layers metaobjects have public storefront access, you can query them directly from your storefront using Shopify’s Storefront API. This can be useful for building custom sort order selectors or displaying available facets.

Example: Fetching Sort Orders

query GetLayersSortOrders {
  metaobjects(type: "$app:sort_order", first: 50) {
    nodes {
      handle
      fields {
        key
        value
      }
    }
  }
}

Example Response

{
  "data": {
    "metaobjects": {
      "nodes": [
        {
          "handle": "layers-sort-order-abc123",
          "fields": [
            { "key": "name", "value": "Best Selling" },
            { "key": "code", "value": "best_selling" },
            { "key": "scope", "value": "[\"collection\", \"search\"]" },
            { "key": "order", "value": "1" }
          ]
        },
        {
          "handle": "layers-sort-order-def456",
          "fields": [
            { "key": "name", "value": "Newest" },
            { "key": "code", "value": "newest" },
            { "key": "scope", "value": "[\"collection\"]" },
            { "key": "order", "value": "2" }
          ]
        }
      ]
    }
  }
}

Overview

Merchandising

Search & Discovery

Catalog & Data

LayersQL

Shopify Integration

Misc

Legal

​Overview

​Metaobjects

​Sort Order Metaobject

​Field Definitions

​Example Metaobject

​Common Sort Order Examples

​Lifecycle

​Facet Metaobject

​Field Definitions

​Example Metaobject

​Common Facet Examples

​Lifecycle

​Block Metaobject

​Field Definitions

​Example Metaobject

​Common Block Examples

​Lifecycle

​Collection Metafield

​Default Sort Order

​Metafield Definition

​How to Set a Default Sort Order

​App Installation Metafields

​Embed Settings

​Schema

​Field Descriptions

​Example Value

​Additional Injects

​Schema

​Field Descriptions

​Example Value

​Commerce Blocks Tokens

​layers_token

​layers_tracking_token

​store_config

​Schema

​Example Value

​Access Permissions

​Metaobject Access

​Metafield Access

​Automatic Synchronization

​Querying Metaobjects via Storefront API

​Example: Fetching Sort Orders

​Example Response

​See Also

Overview

Metaobjects

Sort Order Metaobject

Field Definitions

Example Metaobject

Common Sort Order Examples

Lifecycle

Facet Metaobject

Field Definitions

Example Metaobject

Common Facet Examples

Lifecycle

Block Metaobject

Field Definitions

Example Metaobject

Common Block Examples

Lifecycle

Collection Metafield

Default Sort Order

Metafield Definition

How to Set a Default Sort Order

App Installation Metafields

Embed Settings

Schema

Field Descriptions

Example Value

Additional Injects

Schema

Field Descriptions

Example Value

Commerce Blocks Tokens

layers_token

layers_tracking_token

store_config

Schema

Example Value

Access Permissions

Metaobject Access

Metafield Access

Automatic Synchronization

Querying Metaobjects via Storefront API

Example: Fetching Sort Orders

Example Response

See Also