Metaobjects

Layers creates three types of metaobjects in your Shopify store to represent key configuration entities. These metaobjects let Shopify reference Layers configurations directly, so you can, for example, assign sort orders to collections 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--278936322049--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--278936322049--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. 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. 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--278936322049--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--278936322049--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.

Marking an attribute as filterable is not enough to create a facet metaobject. You must also enable the Enable as Storefront Facet option in the attribute’s Display settings. This lets you keep filterable attributes that are only used through the Layers API without syncing them to Shopify. Learn more in Attribute options.

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--278936322049--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--278936322049--block",
  "handle": "layers-01j8abcd1234xyz",
  "fields": {
    "label": "Featured Products - Collection",
    "title": "Featured Products",
    "anchor_type": "collection"
  },
  "status": "ACTIVE"
}

Handle format

The metaobject’s system handle is generated as layers-<lowercase block ID> (for example, layers-01j8abcd1234xyz). The raw block ID is not stored in any field; the handle is the only way to recover it. Theme code passing a block to the Blocks API (which looks blocks up by their raw ID) must transform the handle first:

{{ settings.my_layers_block.system.handle | remove_first: 'layers-' | upcase }}

Passing the raw system.handle as blockId silently returns no products, since the prefixed handle never matches a block ID. See Accessing blocks for the full pattern.

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

Overview

Core Concepts

Merchandising

Search & Discovery

Catalog & Data

LayersQL

Shopify Integration

Legal

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

Handle format

Common block examples

Lifecycle

​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

​Handle format

​Common block examples

​Lifecycle

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

Handle format

Common block examples

Lifecycle