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 two 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 created when you add a new sort order in Layers, updated when you rename a sort order or change its code, and deleted when you remove a sort order from your configuration. The Facet metaobject represents filterable attributes (facets) configured in Layers. When you mark an attribute as filterable 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 enable filtering on an attribute in Layers, updated when you rename the attribute or change its display name, and deleted when you disable filtering or remove the attribute from your configuration.

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

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 or disable filtering on attributes, facet metaobjects are created or removed accordingly. 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

Core Features

Engine

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

​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

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