Manage dimensions

Dimensions are the contextual fields Layers records with every browse and search event, such as country, channel, device type, sign-in state, or a custom parameter your storefront sends. Layers uses them everywhere shopper context appears in the dashboard: contextual conditions on merchandising rules, sort order segmentation, and metric segment labels. Use the Dimensions page under Customers → Dimensions to:

• Rename a dimension so its label matches how your team talks about it.
• Add a description that appears next to the field in condition and metric builders.
• See which dimensions are populated, how many distinct values each one has, and when it was last seen.
• Browse the recorded values for any dimension.

Renaming a dimension changes only its display label. The underlying code shown under each name on the Dimensions page (for example, geo_state) stays the same, so existing rules, metrics, sort orders, and stored events keep working without changes.

​

Prerequisites

• The Manage store settings permission. See Manage roles and permissions.
• Your storefront must be forwarding events to the Beacon API so coverage numbers have data to report against. See Contextual information for the shape of the payload.

​

Open the Dimensions page

1. In the Layers dashboard, open Customers in the main navigation.
2. Select Dimensions.

The page lists every dimension Layers knows about for your store, with columns for Name, Group, Source, Values (distinct values recorded), Coverage (percent of events that carry a non-empty value), and Last seen.

​

Sources

Each dimension is labeled with one of three sources:

• Built-in — Dimensions Layers ships with, such as Shopping Channel (shopping_channel), Currency (currency), or Customer Type (customer_returning). These are always available on new stores.
• Analytics — Dimensions Layers derives from the raw event stream, such as Country (geo_country), State/Province (geo_state), or Device Type (device_type).
• Custom — Parameters your storefront sends under custom on the contextual payload. Custom dimensions appear automatically the first time Layers sees them in traffic. You don’t register them anywhere.

​

Built-in labels for common URL parameters

URL parameters your storefront records under custom.query often come from ad platforms, affiliate networks, and email tools. Layers ships with friendly labels, descriptions, and groups for the most common ones (for example Google Ads, Meta Ads, TikTok Ads, Pinterest Ads, affiliate, and email parameters), so a parameter like gad_source appears as Google Ads Source grouped under Google Ads instead of a raw parameter name. Parameters without a built-in label appear under the URL Parameter group, and you can always rename them yourself.

​

Parameter filtering for privacy

Layers filters custom.query parameters before they can become dimensions. A parameter is never recorded (and never appears on the Dimensions page or in coverage) when its name looks like a credential or personal identifier, when it is a per-click or per-person ID from an ad or email platform, when it is pagination or storefront state already modeled elsewhere, or when its value looks sensitive (an email address, a signed token, a phone or tracking number, or a long random string). See Usage & privacy for the full filtering behavior.

​

Rename a dimension

1. Click a row to open the dimension detail sheet.
2. Edit the Name field. The placeholder shows the current default, and the label under the field tells you what that default is.
3. Optionally edit the Description. Use this to explain to teammates what the dimension represents or how it’s populated.
4. Click Save.

The new label appears immediately anywhere the dimension is shown:

• The field picker for contextual conditions on merchandising rules, banners, sort orders, request transforms, and blocks.
• Segment labels on segmented metrics and metric charts.
• The Dimensions page itself.

To go back to the built-in name or description, click Reset to default above the field and save. Layers deletes the override so future changes to the built-in copy flow through.

​

Review coverage for a dimension

The detail sheet shows the coverage numbers for the selected dimension:

• Events — total events counted in the last coverage pass.
• Empty values — events where this dimension was missing or empty.
• Coverage — percent of events that carry a non-empty value.
• Unique values — number of distinct values recorded.
• Last seen — most recent event that carried a value.

Use the coverage numbers to spot dimensions your storefront is not sending consistently. A custom dimension with 5% coverage usually means the storefront only sets it on some pages.

​

Browse recorded values

Below the coverage stats, the detail sheet shows the actual values Layers has recorded for the dimension, with search and pagination. Use this to check that a custom field is arriving in the format you expect, or to find the exact value to use when writing a contextual condition.

​

Refresh coverage

Coverage numbers are computed by a background job that runs on a schedule. To trigger a fresh pass, click Refresh in the top right. The Refresh button requires the Run operations permission. If analytics is paused for your store, the refresh is skipped and a message explains why.

​

Next steps

• Configure contextual conditions to target rules and banners with dimensions.
• Use segmented metrics in sort orders to personalize rankings by dimension.
• Contextual information explains the payload your storefront sends and how each dimension is derived.