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.
A daily background job also checks for any 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.
You can view all metaobject definitions from your Shopify store in the Layers dashboard:
- Go to Settings → Metafields & Metaobjects.
- 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.
| Resource | Admin Access | Storefront Access |
|---|
| Sort Order Metaobject | MERCHANT_READ | PUBLIC_READ |
| Facet Metaobject | MERCHANT_READ | PUBLIC_READ |
| Block Metaobject | MERCHANT_READ | PUBLIC_READ |
| Resource | Admin Access | Storefront Access |
|---|
| Collection Default Sort Order | MERCHANT_READ_WRITE | PUBLIC_READ |
| App Installation Metafields | MERCHANT_READ | PUBLIC_READ |
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.
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" }
]
}
]
}
}
}
See also
