> ## 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.

# Collection & App Metafields

> Collection metafield for default sort orders and the shop-level metafields Layers uses to power storefront integrations and theme components.

## 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

```json theme={null}
{
  "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:

1. Go to **Products → Collections** in your Shopify admin
2. Select the collection you want to configure
3. Scroll down to the **Metafields** section
4. Find the **Default Sort Order** field
5. 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.

<Note>
  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.
</Note>

## 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.

<Note>
  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.
</Note>

### 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "name": "string",
  "shopDomain": "string"
}
```

#### Example value

```json theme={null}
{
  "name": "My Awesome Store",
  "shopDomain": "my-awesome-store.myshopify.com"
}
```