What a listing attribute is

A listing attribute is a field you add to the listing form, on top of the title, price and description: a brand, a condition, a colour, a year of manufacture… Each attribute is linked to one or more listing categories, and the form shows the seller the attributes of the category they chose.

The value entered can then show on the listing page, serve as a search filter and be used by your theme. Two of the attribute’s settings decide this, described below: Visibility and Read only.

Create an attribute

  1. In the menu, under Configuration, click Settings, then Catalog, in the Sales & catalog group.
  2. At the top of the General settings for listings screen, click Listing attributes.
  3. Click Add new attribute.
  4. Fill in the form, described below, then click Save.

The attribute list shows each one’s Alias: the name used in the theme and in import files. Drag a row to change the order of the attributes in the form and on the listing page.

The fields of the form

  • Title: the name of the field, shown to the seller and on the listing page.
  • Help message to display in the listing’s form: the text of the tooltip next to the field, in the listing form. Empty, no tooltip.
  • Type: the kind of field.
  • Required: Yes makes the seller fill the field in to publish their listing.
  • Visibility and Read only: described below, in “Who fills it in, where the value shows”.
  • Apply to all categories: Yes links the attribute to every category, including those created later. No shows the list of categories, where you tick those that get it.

The types

Type What the seller enters
Short text One line of text. The Pattern field can enforce a format, as a regular expression.
Long text Several lines of text.
Yes/No choice A choice between Yes and No. The Default value field sets the answer offered.
Number A number.
Dropdown One option, among those you define.
Checkbox One or more options, among those you define.
Date A date.
Link A full web address, shown as a clickable link.
Price An amount.
JSON Structured data, meant for the theme.

For a Dropdown or a Checkbox, enter the options one by one: Add option adds a line. Two settings belong to these types:

  • Use as filter: Yes offers the attribute as a filter in search results (see Filter and search with listing attributes).
  • Display unselected option: Yes shows every option on the listing page, not only those the seller chose; each option carries a CSS class that lets the theme tell them apart.

Who fills it in, where the value shows

Two independent settings:

  • Read only decides who fills in the field: the seller, or the administrator only.
  • Visibility decides where the value shows: in the listing page’s attribute list, in the theme alone, or in the admin panel alone.

Visibility: where the value shows

  • Everyone: the value shows in the listing page’s attribute list. It is also handed to the theme and can serve as a search filter.
  • Theme only: the value is handed to the theme and to search, and can serve as a filter, but it is left out of the listing page’s automatic attribute list. This is the setting for a value the theme shows its own way: a badge, a label, a line in a banner.
  • Only admin: the value stays in the admin panel. It reaches neither the theme nor search, and the attribute is left out of the seller’s form.

In the theme, an attribute’s value is read with listing.attributes. followed by its alias, for instance listing.attributes.verified_listing. The details are on the developers hub.

Read only: who fills in the field

  • No: the seller fills the field in, in their listing form.
  • Yes: only the administrator fills the field in. The seller’s form leaves it out, and the platform discards any value a seller sends for this attribute. To fill it in: in the menu, under Catalog & customers, click Catalog, open the listing and fill the field in, in the Additional attributes card.

A read-only value then shows according to the attribute’s Visibility, like any other.

Combining the two

Need Visibility Read only
A feature the seller enters, shown on the listing: a brand, a condition Everyone No
A “Verified listing” badge your team sets, shown by the theme Theme only Yes
A value the seller enters and the theme styles: a colour swatch Theme only No
An internal note from your team on the listing Only admin Yes or No: the seller does not see the field

Import and export attributes

On the attribute list, Export downloads a CSV file, one line per attribute, and Import loads a file in the same format (.csv, .xls, .xlsx or .ods). A line whose alias already exists updates that attribute; a line with a new alias creates an attribute.

The visibility column takes three values, in English or in French:

Visibility on screen Value in the file
Everyone Everyone or Tout le monde
Theme only Theme only or Thème uniquement
Only admin Admin only or Admin seulement

The Yes/No columns take Yes, No, Oui and Non.

Customize the attribute list’s layout

In Theme › General, the Listing attributes setting chooses the layout of the list on the listing page: Grid or Full width.

To go further, each attribute in the list carries the CSS class listing-attribut- followed by its alias, which your CSS can target (see Modify your theme using custom code).

One page per attribute value

An attribute can serve as a condition of a collection, and a collection model creates one page per value of the attribute, for instance one per brand. See Create a collection and Create collections from a model.

What your users see

Sellers find in their listing form the attributes of the category they chose, with their tooltip; an asterisk marks a required field. Attributes whose Read only is set to Yes, or whose Visibility is Only admin, are not in it.

Visitors see, on the listing page, the list of the attributes whose Visibility is Everyone and that have a value. Attributes with the Theme only visibility show where the theme places them. Attributes with Use as filter set to Yes appear in the filters of the search results, unless their visibility is Only admin.

Edge cases and limits

  • Fixed type: an attribute’s type is chosen at creation and cannot be changed afterwards, neither in the form nor by import.
  • Attribute linked to no category: it appears in no form.
  • Category change: a listing shows only the attributes of its current category. The values of the previous category’s attributes disappear from the listing page and from search, but stay stored: if the listing returns to its original category, they come back, with nothing to enter again. Attributes linked to all categories always show.
  • Required attribute missing from the seller’s form: with Required set to Yes, an attribute whose Read only is set to Yes, or whose Visibility is Only admin, is not required from the seller, who has no field for it.
  • Webhooks: they send every value to your own systems, including those of the attributes whose Visibility is Only admin.
  • Import: a visibility value outside the table above is refused for a new attribute, and gives an existing attribute the Everyone visibility. The file does not carry Read only: set it in the attribute’s form.