Collection & App Metafields

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--278936322049--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--278936322049--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:

Go 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

Layers automatically applies the selected sort order when browsing this collection through the Layers Browse API without 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.

Shop and app installation metafields

Layers stores configuration data on both the shop and the app installation so that storefront integrations, the tracking pixel, theme app extensions, and Liquid templates can all read it. Every metafield in this section is written to both owners and stays in sync — read whichever one your context supports.

Context	Recommended owner	Liquid path
Theme Liquid (`shop.metafields…`)	Shop	`shop.metafields.layers.embed_settings.value`
Theme app extensions / blocks	Shop	`shop.metafields.commerce_blocks.store_config.value`
Shopify Admin API (private apps, server-side)	Shop or app installation	Either GID resolves to the same value

These metafields are automatically managed and should not be edited manually.

Was your store connected before the dual-write rolled out? If you don’t yet see values under shop.metafields.layers.* or shop.metafields.commerce_blocks.*, trigger a resync from Settings → Integrations in the Layers dashboard, or wait for the next scheduled push.

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"
}

Overview

Core Concepts

Merchandising

Search & Discovery

Catalog & Data

LayersQL

Shopify Integration

Legal

Collection & App Metafields

Collection metafield

Default sort order

Metafield definition

How to set a default sort order

Shop and 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

​Collection metafield

​Default sort order

​Metafield definition

​How to set a default sort order

​Shop and 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

Collection metafield

Default sort order

Metafield definition

How to set a default sort order

Shop and 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