Banner injection

Banner injection lets a merchandising rule embed promotional media directly into a collection grid. Banners are a rule consequence in the same family as pins: the rule decides when a banner shows up (collection, contextual conditions, schedule), and the banner decides what shows up. A hero banner is a horizontal banner that spans the entire product grid from side to side, above the first row of products. Choose this placement for a full-width promotion. An inline banner sits among products and can span multiple grid columns, not just one or two. Every rule can carry up to 50 banners, each with independent desktop and mobile layouts and media.

Placement	Where it appears	How sizing works
Hero	Above the first row of products	Spans the full width of the product grid, regardless of how many columns it has.
Inline	Among the product cards	Drag the left or right edge to resize across the available columns. The editor keeps the banner one product-card row tall.

Grid spans describe how much space a banner occupies, not required image dimensions in pixels. Hero banners are not limited to product-card sizes. Their displayed height and image cropping depend on your storefront’s styling. Full width means the width of the product grid, not necessarily the entire browser window. To make a hero, drag the banner into the area above the products in the rule editor. You can use different placements on desktop and mobile, such as a hero on desktop and an inline banner on mobile. See Add a banner to a rule. Each banner is stamped with a banner type that defines what structured data the banner carries beyond its images. Every store has a built-in Link type; you can create custom types with your own typed fields (headlines, dates, product references, and so on) that flow through as a data object on the browse response.

Banners are emitted as configuration on the browse response. They’re a passthrough for your storefront to render. Layers does not render banners into your theme directly. See What ships in the browse response for the payload shape.

Every banner has:

A name for internal organization (not shown to shoppers).
A Type — either the built-in Link type or one of your custom banner types. The type controls the extra fields the merchandiser fills in and the data object shipped on the browse response.
Web Media and Mobile Media — independent media per device. A banner only goes live once both are set. Media comes from your Shopify files.
A Mode:
- overtake — the banner takes the place of a product card in the grid.
- inject — the banner is inserted alongside product cards. Only inject banners can carry a click-through link on the built-in Link type.
Custom banner types declare which modes they allow. A rule can only save a banner in a mode the type permits.
A Per-Device Layout controlling placement and size:
- Hero spans the full grid width above the products.
- Inline occupies one or more columns among the products. Resize its width by dragging either side.
- Drag the banner to choose its position. Desktop and mobile layouts are independent.
An optional Schedule with a start and end time, open-ended on either side.
Optional Contextual Conditions — the same shape as rule-level contextual conditions, evaluated per banner.
A Sort Index that controls the order banners are applied when a rule has more than one.

Each banner has its own on/off state. Hero and inline placements can coexist inside the same rule.

How banners combine with pins and expressions

A merchandising rule can carry any combination of pins, sort expressions, variant breakouts, and banners. Banners are layered on top of the underlying product order. They don’t reorder products; they take grid space:

Hero banners render before the first product row. They never push products out of the result.
Inline overtake banners consume the grid cell at their position, displacing the product that would have appeared there.
Inline inject banners occupy their chosen grid space, with products flowing around them.

Pin drag-and-drop and banner layout are independent. Placing a banner doesn’t reshuffle pinned products, and re-pinning a product doesn’t move banners. A rule that carries banners but no pins, expressions, or variant breakouts is still considered to have an effective impact, so banner-only rules are never silently dropped.

Scheduling and targeting

Banners inherit the rule’s own scheduling and contextual conditions implicitly. If the rule isn’t active for the request, the banner isn’t either. On top of that, each banner can carry its own schedule and contextual conditions:

The banner’s Schedule controls when the banner is enabled. Layers checks scheduled banners continuously and toggles the banner’s enabled state to match. Changes typically take effect within about a minute of the configured time. Browse responses ship whatever banners are currently enabled; the schedule window itself isn’t re-checked per request.
The banner’s contextual conditions are evaluated per request and must evaluate true for the banner to ship.

Banner schedules use the same scheduler-driven model as rule scheduling and scheduled pins. In rule preview, every enabled banner is shown regardless of its contextual conditions so you can audit the full set you’re editing. Live browse traffic always applies them.

What ships in the browse response

When at least one merchandising rule matches a request and has enabled banners that pass their own gates, the browse response carries a top-level banners array. The IDs of the rules that produced them are available on _meta.appliedRules. Layers does not render anything into your storefront. Your theme is responsible for placing the banner into the grid based on its placement and position.

{
  "resultsPerPage": 24,
  "totalResults": 41,
  "results": [ /* ... */ ],
  "page": 1,
  "totalPages": 2,
  "facets": { /* ... */ },
  "facetRanges": [],
  "banners": [
    {
      "id": "01KWD5S5R50690NXFW32PXM0V2",
      "name": "Willie Nelson Flannel",
      "mode": "inject",
      "link": null,
      "type": "link",
      "data": {},
      "sort_index": 0,
      "web_media": {
        "id": "gid://shopify/MediaImage/30292299612213",
        "alt": null,
        "src": "https://cdn.shopify.com/.../banner-web.jpg",
        "width": 750,
        "height": 1100,
        "source": "store_file",
        "mediaContentType": "IMAGE"
      },
      "mobile_media": {
        "id": "gid://shopify/MediaImage/30292299612213",
        "alt": null,
        "src": "https://cdn.shopify.com/.../banner-mobile.jpg",
        "width": 750,
        "height": 1100,
        "source": "store_file",
        "mediaContentType": "IMAGE"
      },
      "web_layout":    { "placement": "inline", "width": 1, "height": 1, "position": 1 },
      "mobile_layout": { "placement": "inline", "width": 1, "height": 1, "position": 1 }
    }
  ],
  "attributionToken": "01KWYNX0JWTXY4CM0A7D9GDZCT",
  "_meta": {
    "appliedRules": ["bd2d34eb-0d87-4299-90ee-ffeb572a12f6"],
    "appliedSearchRules": []
  }
}

Each banner entry carries the following fields:

Field	Type	Description
`id`	string	Banner ULID.
`name`	string	Internal name (not shown to shoppers).
`mode`	`"inject"` \| `"overtake"`	How the banner sits in the grid. `inject` inserts and shifts trailing products; `overtake` replaces the product at `position`.
`link`	string \| null	Click-through URL. Only honored on `inject` banners, and only meaningful on the built-in `link` type. Custom types put their click-through URL inside `data` instead.
`type`	string	Banner type slug — `link` for the built-in type, or the slug of one of your custom banner types. Switch storefront renderers on this.
`data`	object	Saved values for the 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.
`sort_index`	number	Application order when a rule has multiple banners. Lower wins on conflicting cells.
`web_media`, `mobile_media`	object	Independent per-device media. Both must be present for the banner to ship.
`web_layout`, `mobile_layout`	object	Independent per-device layout. See Layout shape.

Each *_media object contains id, src, alt, width, height, source ("store_file" for Shopify files), and mediaContentType ("IMAGE" for images).

Layout shape

Each *_layout object is:

Field	Type	Description
`placement`	`"hero"` \| `"inline"`	`hero` renders as a full-width row above the grid; `inline` slots into a grid cell.
`width`	number	Inline column span, bounded by the available grid columns, not limited to two. Ignored for heroes, which span the full grid width.
`height`	number	Inline row span. The editor uses one row; saved layouts can contain one or two. Not an image height in pixels and ignored for hero sizing.
`position`	number	Row-major grid cell index. For `hero` placement, `position` is not meaningful. Render heroes above the grid regardless of the value.

Pick the layout for the current device (web_layout or mobile_layout), then:

For placement: "hero", render above the grid before the first product cell.
For placement: "inline", place at position (row-major) with the banner spanning width × height cells. If multiple banners target the same cell, the lower sort_index wins.
If a banner’s mode is inject and a link is set, wrap the banner in an anchor.

Mirrored metaobjects

Each enabled banner is also mirrored to a $app:banner metaobject in your Shopify store, linked back to the rule. Storefront code that prefers reading from metaobjects (e.g. a fully Liquid-rendered grid) can use those alongside the browse-response payload. See Metaobjects.

Limits and behavior

Max 50 banners per rule.
Both Web and Mobile media required to go live. A banner without both slots filled is treated as disabled, even if it’s toggled on.
Per-device layout is independent. A hero on web can be an inline tile on mobile, or vice versa.
Config history covers banners. Banner add/edit/remove/reorder is captured in rule config history snapshots and restored when you roll a rule back.
Cache invalidation runs on any banner change (not just pin/expression changes), so a banners-only edit goes live immediately.

Overview

Core Concepts

Merchandising

Search & Discovery

Catalog & Data

LayersQL

Shopify Integration

Legal

Banner injection

Banner sizes and placement

Banner anatomy

How banners combine with pins and expressions

Scheduling and targeting

What ships in the browse response

Layout shape

Mirrored metaobjects

Limits and behavior

See also

​Banner sizes and placement

​Banner anatomy

​How banners combine with pins and expressions

​Scheduling and targeting

​What ships in the browse response

​Layout shape

​Mirrored metaobjects

​Limits and behavior

​See also

Banner sizes and placement

Banner anatomy

How banners combine with pins and expressions

Scheduling and targeting

What ships in the browse response

Layout shape

Mirrored metaobjects

Limits and behavior

See also