Skip to main content
A banner type defines the fields a merchandiser fills in when they attach a banner to a rule. Every store starts with a built-in Link type (image + click-through URL). Create a custom type when you want merchandisers to fill in richer promos — a countdown with an end_at date, a spotlight card that references a product, a card that carries a headline and CTA label. The saved field values ship on the browse response as a data object alongside the banner’s images. Your storefront switches renderers on banner.type and reads out of banner.data.

​
Before you start

  • Sketch the fields you want on the banner before opening the dashboard. Give each one a snake_case key, a human label, and a type. The type is fixed on save — changing it later drops the stored value from every banner of this type.
  • The storefront needs to render the new type before merchandisers can rely on it. Coordinate the theme change first. See Rendering banners in Liquid or Rendering banners with the SDK.

​
Steps

  1. Go to Configure → Banner Types.
  2. Click Create Banner Type. You land on the builder.
  3. Fill in the header:
    • Name — human-readable label shown to merchandisers when they pick a type on a banner (e.g. “Countdown Promo”). The slug is derived from the name automatically and locked at save time. The slug is what your storefront switches on, so pick a name whose slug you’re happy to commit to.
    • Allowed Modes — one or both of Inject and Overtake. A banner using this type can only be saved in a mode you allow here. Restricting this is useful when a type only makes sense in one placement (e.g. a hero-only promo you don’t want anyone dropping into an inline cell).
  4. Add fields under Fields. For each field:
    • Label — what merchandisers see next to the input.
    • Key — snake_case identifier that becomes the key on banner.data. Must start with a lowercase letter and be unique within the type.
    • Type — pick from the taxonomy (text, number, date, URL, color, money, rating, product/collection/variant/file reference, and more). See the full type list.
    • Required — when on, merchandisers can’t save the banner without a value.
    • List — toggle on to accept multiple values of this type (e.g. a list of product references). Supported for most types; a few (JSON, rich text, multi-line text, boolean, money, ID, language) can’t be lists.
    • Validations — depend on the selected type. Text can use a pattern or a list of allowed values; numbers and dates can have a minimum and maximum; decimals can have a maximum number of decimal places; file references can restrict accepted files to images, videos, or both. Ratings require a minimum and maximum.
  5. Reorder fields by dragging. The order controls how fields appear in the banner editor when merchandisers add a banner of this type.
  6. Click Save. Layers derives the slug from the name and takes you to the edit view.

​
Edit a banner type

Open the type from Configure → Banner Types and change what you need. Two edits 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 turning list. on/off) — the value stored on every banner of this type is dropped.
Before you save a destructive edit, Layers warns you and lists the specific banners (and their rules) that would lose data. Cancel, roll each affected banner over to a new field first, then come back and remove the old one in a follow-up save. Renaming the type or reordering fields is always safe. The slug never changes.

​
Delete a banner type

Open the type and click Delete. Layers rejects the delete if any rule still has a banner of this type and lists the banners so you can retype or remove them first. The built-in Link type cannot be deleted.

​
What the storefront sees

Once a merchandiser attaches a banner of your new type to a rule, the browse response carries the banner’s type slug and a data object with the saved field values. Reference fields are pre-resolved to { id, handle }, unpublished references are dropped, and only keys defined in the current schema are shipped. See Payload shape for the full envelope.

​
See also