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 name and a type. Layers generates each field’s snake_case key from its name, so the name you start with sets the key your storefront reads. 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 Settings → Banner Types.
  2. Click Create Banner Type. You land on the builder.
  3. Name the type in the editable title at the top of the page. The name is the human-readable label shown to merchandisers when they select a type on a banner (e.g. “Countdown Promo”). Layers derives the slug from the name and shows it under the title as Type:. The slug is locked at save time and is what your storefront switches on, so pick a name whose slug you’re happy to commit to.
  4. Add fields under Fields. Click Add field for each one, then set:
    • Field name — what merchandisers see next to the input. Layers generates the field’s key (the snake_case identifier that becomes the key on banner.data) from the name. The key is locked once the field is saved, so renaming a field later doesn’t change its key.
    • Required — click the asterisk button next to the name to make the field required. Merchandisers can’t save the banner without a value for a required field.
    • One value or List of values — choose List of values 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.
    • Type — select from the taxonomy (text, number, date, URL, color, money, rating, product/collection/variant/file reference, and more). See the full type list.
    • Options — expand the field to set validations, which 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 Maximum decimal places; lists can have a minimum and maximum number of items; file references can restrict Accepted files to images, videos, or both. Ratings require a minimum and maximum.
  5. Reorder fields by dragging the handle on each row. The order controls how fields appear in the banner editor when merchandisers add a banner of this type. To delete a field, expand it and click Remove field.
  6. Under Placements, turn on Inject, Overtake, or both. A banner using this type can only be saved in a placement 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).
  7. Click Create Banner Type. Layers saves the type, locks the slug, and takes you to the edit view.

​
Edit a banner type

Open the type from Settings → Banner Types, change what you need, and click Save Changes. 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 (for example, from single-line text to URL, or switching between One value and List of values) — the value stored on every banner of this type is dropped.
Layers saves these edits right away. After the save, a Some stored values will be dropped from payloads warning lists the affected fields and the specific banners (and their rules) that lost data. To keep the data, add the new field first, roll each affected banner over to it, then remove or retype the old field in a follow-up save. Renaming the type or reordering fields is always safe. The slug never changes.

​
Delete a banner type

On Settings → Banner Types, open the row’s actions menu, select Delete, and confirm with Delete Banner Type. Deleting can’t be undone. Layers rejects the delete if any rule still has a banner of this type so you can retype or remove those banners 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