Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Metaobject cache and nested resolution

Layers maintains a local cache of all metaobjects in your Shopify store. This cache enables fast, deep resolution of nested metaobject references within product metafields — without making additional Shopify GraphQL calls at query time.

​
How it works

When your store is connected, Layers performs a bulk import of all metaobjects across every metaobject definition type. The cache is then kept up to date through per-type Shopify webhooks (metaobjects/create, metaobjects/update, metaobjects/delete) that fire whenever a metaobject is created, updated, or deleted. Layers also checks daily for new metaobject definition types added to your store and automatically registers webhooks for them.

​
Nested resolution

When a product metafield references a metaobject (via metaobject_reference or list.metaobject_reference), Layers resolves the full metaobject data from its local cache. If any field within that metaobject itself references another metaobject, Layers resolves that reference too — recursively up to 5 levels deep. This means your API responses contain fully expanded metaobject data without you needing to make follow-up requests. Circular references are automatically detected and prevented. For details on the resolved data structure and examples, see Metaobject & Reference Handling in the Product Schema documentation.

​
Metaobject definitions tab

You can view all metaobject definitions from your Shopify store in the Layers dashboard:
  1. Go to Settings → Metafields & Metaobjects.
  2. Select the Metaobject Definitions tab.
This read-only view shows each metaobject definition’s name, type, field definitions, and entry count. It provides visibility into what metaobject types exist in your store without needing to check the Shopify admin.

​
Required access scope

Layers requires the read_metaobjects Shopify access scope to fetch and cache metaobject data. This scope is automatically requested during app installation. If your store was connected before this feature was available, you may need to re-authorize the app to grant this scope.

​
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

ResourceAdmin AccessStorefront Access
Sort Order MetaobjectMERCHANT_READPUBLIC_READ
Facet MetaobjectMERCHANT_READPUBLIC_READ
Block MetaobjectMERCHANT_READPUBLIC_READ
You 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

ResourceAdmin AccessStorefront Access
Collection Default Sort OrderMERCHANT_READ_WRITEPUBLIC_READ
App Installation MetafieldsMERCHANT_READPUBLIC_READ
The collection default sort order metafield allows you to select a sort order from the Shopify admin. App installation metafields are read-only 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--278936322049--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" }
          ]
        }
      ]
    }
  }
}

​
Accessing metaobjects with Liquid

You can access Layers metaobjects directly in your Shopify theme using Liquid. See the Liquid Integration documentation for detailed examples and implementation patterns.

​
See also