Banner Types

A banner type is a reusable field schema attached to a merchandising banner. It gives a banner named, typed fields — headline, subheadline, product reference, expiration timestamp — that flow through as a structured data object on the browse response. Your storefront reads those fields to render richer promos than a plain image plus link. Every store starts with a built-in Link type. Custom types are additive: existing banners keep working, and each rule can mix banners of different types up to the five-banner-per-rule limit.

The link system type

Every store has a system banner type with slug link and a single field:

link (URL, optional) — the click-through URL for inject banners.

link cannot be edited or deleted. Banners created before custom types shipped are treated as link banners and keep their previous behavior — the storefront still reads banner.link at the top level for those. Create a custom banner type when you want banners with more than an image and a click-through URL — for example, a countdown promo that carries an end_at timestamp, or a spotlight banner that references a specific product and pulls its live handle. A custom banner type has:

Name — human-readable, shown when merchandisers pick a type on a banner (e.g. “Countdown Promo”).
Slug — a lowercase snake_case identifier derived from the name at creation and locked afterward. The slug appears as banner.type on the browse response and is the discriminator your storefront switches on.
Allowed Modes — one or both of inject and overtake. A banner using this type can only be saved in a mode you allow here. This lets you forbid link-only variants on hero placements, for example.
Field Schema — the ordered list of fields merchandisers fill in when they attach a banner of this type. Each field has a key, label, type, required flag, and per-field validations.

Field types

Field types match Shopify’s metafield type taxonomy so the shape of the data you get is predictable and portable.

Group	Type	Value shape	Validations
General	`single_line_text_field`	string	Pattern, Allowed values
General	`multi_line_text_field`	string	—
General	`rich_text_field`	Shopify rich-text JSON AST object	—
General	`number_integer`	integer	Minimum, Maximum
General	`number_decimal`	decimal string	Minimum, Maximum, Maximum decimal places
General	`boolean`	boolean	—
General	`date`	`YYYY-MM-DD` string	Minimum, Maximum
General	`date_time`	ISO-8601 string	Minimum, Maximum
General	`url`	string, `http`/`https` only	—
General	`color`	`#RRGGBB` or `#RRGGBBAA` hex string	—
General	`money`	`{ "amount": "12.50", "currency_code": "USD" }`	—
General	`rating`	`{ "value": 4.5, "scale_min": 1, "scale_max": 5 }`	Minimum, Maximum (both required)
General	`json`	arbitrary JSON value	—
General	`link`	`{ "url": "https://…", "text": "Shop now" }`	—
General	`id`	string	—
General	`language`	ISO 639-1 code string	—
Measurement	`dimension`	`{ "value": <number>, "unit": <unit> }`	Minimum, Maximum
Measurement	`weight`	`{ "value": <number>, "unit": <unit> }`	Minimum, Maximum
Measurement	`volume`	`{ "value": <number>, "unit": <unit> }`	Minimum, Maximum
Reference	`product_reference`	local product id string	—
Reference	`collection_reference`	local collection id string	—
Reference	`variant_reference`	local variant id string	—
Reference	`file_reference`	`{ "id": …, "url": …, "alt": … }`	Accepted files (images, videos, or both)

Measurement units:

dimension: mm, cm, m, in, ft, yd
weight: g, kg, oz, lb
volume: ml, cl, l, m3, us_fl_oz, us_pt, us_qt, us_gal, imp_fl_oz, imp_pt, imp_qt, imp_gal

Any general/measurement/reference type except the JSON, rich text, multi-line text, boolean, money, ID, and language types can be turned into a list with a minimum and maximum number of list items.

Reference resolution

When a field is product_reference, collection_reference, or variant_reference (or a list of those), merchandisers pick a resource in the dashboard and Layers stores its local ID. On the browse response, Layers resolves each ID to a stable payload before shipping it:

{
  "id": "8123456789012",
  "handle": "canvas-tote-bag"
}

Unpublished references (product/variant not published on the surface serving the request) are dropped — the field is either omitted (single reference) or filtered out of the list (list of references). This means the storefront never has to guard against dead handles or 404s.

Payload shape

Every banner in the browse response carries the same envelope regardless of type:

{
  "id": "01KWD5S5R50690NXFW32PXM0V2",
  "name": "Fall promo",
  "mode": "inject",
  "link": "https://shop.example.com/collections/fall",
  "type": "countdown_promo",
  "data": {
    "headline": "Fall drop is live",
    "cta_label": "Shop the drop",
    "end_at": "2026-10-31T23:59:59Z",
    "spotlight_product": { "id": "8123456789012", "handle": "canvas-tote-bag" }
  },
  "sort_index": 0,
  "web_media": { /* ... */ },
  "mobile_media": { /* ... */ },
  "web_layout":    { "placement": "inline", "width": 1, "height": 1, "position": 1 },
  "mobile_layout": { "placement": "inline", "width": 1, "height": 1, "position": 1 }
}

The two type-driven fields are:

Field	Type	Description
`type`	string	Banner type slug — either `link` (system) or the slug of one of your custom types. Storefronts switch renderers on this.
`data`	object	The saved values for that type’s field schema. Keys match the schema’s `key` values. Only keys defined in the current schema are returned — retyped or removed fields are dropped.

link banners still carry a top-level link on the envelope so existing storefront code keeps working. Custom types can define their own link field inside data if they want a click-through URL that lives in structured data. Renaming a type or reordering its fields is safe. Two changes are destructive because they invalidate stored banner values:

Removing a field — the value stored on every banner of this type is dropped.
Retyping a field (single_line_text_field → url, or removing/adding the list. prefix) — the value stored on every banner of this type is dropped, since Layers cannot safely coerce between shapes.

The dashboard surfaces a warning listing the affected banners before you save. There is no automatic migration — write the new schema to accept the old values first (for example, keep both the old and new field on the type until you have rewritten each banner), then remove the old field in a follow-up save. Banner types can only be deleted when no banner references them. If any rule still has a banner of that type, the dashboard rejects the delete and lists the specific banners so you can retype or remove them first. The system link type cannot be deleted.

Limits and behavior

One system type per store (link). Custom types are unlimited.
Slug is locked at creation. The slug is the storefront’s payload discriminator, so Layers derives it from the name once and never re-derives it. Rename the type freely; the slug does not change.
Cache invalidation runs on any banner-type change. Editing a type flushes every rule that uses it so the new schema takes effect on the next browse response.
Config history captures banner-type create/update/delete alongside rule and banner changes.

Overview

Core Concepts

Merchandising

Search & Discovery

Catalog & Data

LayersQL

Shopify Integration

Legal

The link system type

Custom banner types

Field types

Reference resolution

Payload shape

Editing a banner type

Deleting a banner type

Limits and behavior

See also

​The link system type

​Custom banner types

​Field types

​Reference resolution

​Payload shape

​Editing a banner type

​Deleting a banner type

​Limits and behavior

​See also

The link system type

Custom banner types

Field types

Reference resolution

Payload shape

Editing a banner type

Deleting a banner type

Limits and behavior

See also