Attributes API guide

Permissions

To edit and create attributes, a user needs to have the following permissions:

MANAGE_PRODUCT_TYPES_AND_ATTRIBUTES
MANAGE_PAGE_TYPES_AND_ATTRIBUTES

To assign attributes to products and pages, a user needs only the following permissions: MANAGE_PRODUCTS and MANAGE_PAGES.

Each attribute has an input type defined upon attribute creation. Input types determine the data type you can enter as the attribute values in the dashboard. Available input types are defined in the AttributeInputTypeEnum enum. Below is the list of available input types:

Name	Description	Example
`DROPDOWN`	List of predefined choices; rendered as a single-select dropdown.	Store a color of a variant with predefined choices: orange, black, blue, etc.
`MULTISELECT`	List of predefined choices; rendered as a multi-select dropdown.	Add multiple tags to a product or a page.
`FILE`	Allows to store a file as an attribute value; rendered as a file input.	Store a product manual as a PDF file; store a hero image for a page.
`REFERENCE`	Values are references to other entities such as products, variants, pages, categories or collections.	Render a list of related products on a product page.
`SINGLE_REFERENCE`	Stores a reference to other entity such as product, variant, page, collection or category.	Render a related collection on a product page.
`NUMERIC`	Values are numbers; optionally, a unit can be provided to represent measures and dimensions.	Dimensions of a product represented with three numeric attributes: length, width, depth.
`RICH_TEXT`	Value is stored as rich-text content; rendered as a rich-text editor.	Additional content blocks for a page or product.
`PLAIN_TEXT`	Value is stored as plain text; rendered as a text input.	Stores unformatted text for simple labels, e.g., “Material: 100% Cotton”
`SWATCH`	Stores a color code or an image.	Stores a color or an image to visually represent options like colors or patterns.
`BOOLEAN`	Allows storing boolean values.	Yes/no properties, e.g. “Product is fair trade certified: yes/no”.
`DATE`	Allows storing date values.	Store release date of a product.
`DATE_TIME`	Allows storing date time values.	Store release date with time of a product.

Fetching Attributes

To fetch the list of attributes, use the attributes query:

query Attributes($first: Int, $where: AttributeWhereInput) {
  attributes(first: $first, where: $where) {
    totalCount
    edges {
      node {
        name
        slug
        inputType
        entityType
        referenceTypes {
          ... on ProductType {
            id
            slug
          }
          ... on PageType {
            id
            slug
          }
        }
        unit
        choices(first: $first) {
          edges {
            node {
              name
            }
          }
        }
      }
    }
  }
}

{
  "first": 5,
  "where": {}
}

{
  "data": {
    "attributes": {
      "totalCount": 20,
      "edges": [
        {
          "node": {
            "name": "Allegations",
            "slug": "allegations",
            "inputType": "MULTISELECT",
            "entityType": null,
            "referenceTypes": [],
            "unit": null,
            "choices": {
              "edges": [
                {
                  "node": {
                    "name": "Halal certified"
                  }
                },
                {
                  "node": {
                    "name": "Suitable for vegetarians"
                  }
                }
              ]
            }
          }
        },
        {
          "node": {
            "name": "Unit weight sold",
            "slug": "unit-weight-sold",
            "inputType": "DROPDOWN",
            "entityType": null,
            "referenceTypes": [],
            "unit": null,
            "choices": {
              "edges": [
                {
                  "node": {
                    "name": "80 g"
                  }
                },
                {
                  "node": {
                    "name": "55 g"
                  }
                }
              ]
            }
          }
        },
        {
          "node": {
            "name": "Storage conditions",
            "slug": "storage-conditions",
            "inputType": "PLAIN_TEXT",
            "entityType": null,
            "referenceTypes": [],
            "unit": null,
            "choices": {
              "edges": []
            }
          }
        },
        {
          "node": {
            "name": "Servings",
            "slug": "servings",
            "inputType": "NUMERIC",
            "entityType": null,
            "referenceTypes": [],
            "unit": null,
            "choices": {
              "edges": []
            }
          }
        },
        {
          "node": {
            "name": "Recipies",
            "slug": "recipies",
            "inputType": "REFERENCE",
            "entityType": "PAGE",
            "referenceTypes": [],
            "unit": null,
            "choices": {
              "edges": []
            }
          }
        }
      ]
    }
  }
}

The attributes field supports pagination and filtering, e.g., searching attributes by name. For each attribute, we fetch the following properties, some of which are used only with specific input types:

name - Name of the attribute, use it to render attribute in the frontend.
slug - A unique attribute handle you can use to fetch an attribute or reference it in filters.
inputType - Represents the input type.
entityType - Used only with REFERENCE and SINGLE_REFERENCE input types; represents the type of entities associated as references, e.g., PAGE or PRODUCT.
referenceTypes - Allowed target types for reference attributes. For attributes with the PRODUCT or PRODUCT_VARIANT entity type, this lists allowed product types; for attributes with the PAGE entity type, this lists allowed page types. Not supported for CATEGORY or COLLECTION reference attributes.
unit - Used only with NUMERIC input types; represents the optional measurement unit.
choices - Used only with DROPDOWN, MULTISELECT and SWATCH; a list of predefined choices you can use as values. The choices field supports pagination and filtering, e.g., searching choices by name.

Fetching Product Assigned Attributes

Attributes assigned to an object are represented by the AssignedAttribute GraphQL interface. Below is an example of fetching the material attribute (of single-choice type) and single references to pages connected to the product.

query Product($productSlug: String, $channel: String, $languageCode: LanguageCodeEnum!) {
  product(slug: $productSlug, channel: $channel) {
    name
    material: assignedAttribute(slug: "material") {
      ... on AssignedSingleChoiceAttribute {
        value {
          slug
          translation(languageCode:$languageCode)
        }
      }
    }
    brandReferences: assignedAttribute(slug: "brand") {
      ... on AssignedSinglePageReferenceAttribute {
        value {
          title
          translation(languageCode: $languageCode){
            title
          }
        }
      }
    }
  }
}

{
  "productSlug": "cubes-fountain-tee",
  "channel": "default-channel",
  "languageCode": "FR"
}

{
  "data": {
    "product": {
      "name": "Cubes Fountain Tee",
      "material": {
        "value": {
          "slug": "wool",
          "translation": "Laine"
        }
      },
      "brandReferences": {
        "value": {
          "title": "Saleor Loom",
          "translation": null
        }
      }
    }
  }
}

Similarly, you can fetch assigned attributes for ProductVariant and Page types.

Fetching Product With All Types of Assigned Attributes

To fetch all attributes assigned to products or variant with values use the ObjectWithAttributes interface.

query Product($productSlug: String, $channel: String) {
  product(slug: $productSlug, channel: $channel) {
    name
    ...Attributes
  }
}

fragment Attributes on ObjectWithAttributes {
  assignedAttributes(limit: 50) {
    attribute {
      id
      slug
    }
    ... on AssignedNumericAttribute {
      number: value
    }
    ... on AssignedTextAttribute {
      text: value
    }
    ... on AssignedPlainTextAttribute {
      plain_text: value
    }
    ... on AssignedFileAttribute {
      file: value {
        contentType
      }
    }
    ... on AssignedSingleChoiceAttribute {
      choice: value {
        name
        slug
      }
    }
    ... on AssignedMultiChoiceAttribute {
      choices: value(limit: 10) {
        name
        slug
      }
    }
    ... on AssignedSwatchAttribute {
      swatch: value {
        name
        slug
        hexColor
        file {
          url
          contentType
        }
      }
    }
    ... on AssignedBooleanAttribute {
      bool: value
    }
    ... on AssignedDateAttribute {
      date: value
    }
    ... on AssignedDateTimeAttribute {
      datetime: value
    }
    ... on AssignedSinglePageReferenceAttribute {
      page_ref: value {
        __typename
        slug
      }
    }
    ... on AssignedSingleProductReferenceAttribute {
      product_ref: value {
        __typename
        slug
      }
    }
    ... on AssignedSingleProductVariantReferenceAttribute {
      variant_ref: value {
        __typename
        sku
      }
    }
    ... on AssignedSingleCategoryReferenceAttribute {
      category_ref: value {
        __typename
        slug
      }
    }
    ... on AssignedSingleCollectionReferenceAttribute {
      collection_ref: value {
        __typename
        slug
      }
    }
    ... on AssignedMultiPageReferenceAttribute {
      pages: value(limit: 10) {
        __typename
        slug
      }
    }
    ... on AssignedMultiProductReferenceAttribute {
      products: value(limit: 10) {
        __typename
        slug
      }
    }
    ... on AssignedMultiProductVariantReferenceAttribute {
      variants: value(limit: 10) {
        __typename
        sku
      }
    }
    ... on AssignedMultiCategoryReferenceAttribute {
      categories: value(limit: 10) {
        __typename
        slug
      }
    }
    ... on AssignedMultiCollectionReferenceAttribute {
      collections: value(limit: 10) {
        __typename
        slug
      }
    }
  }
}

{
  "productSlug": "croissant",
  "channel": "fr"
}

{
  "data": {
    "product": {
      "name": "Croissant",
      "assignedAttributes": [
        {
          "attribute": {
            "id": "QXR0cmlidXRlOjI=",
            "slug": "date-of-minimum-durability"
          },
          "choice": {
            "name": "12 months",
            "slug": "12-months"
          }
        },
        {
          "attribute": {
            "id": "QXR0cmlidXRlOjM=",
            "slug": "ingredients"
          },
          "plain_text": "WHEAT flour, water, fine butter (MILK) 18%, yeast, sugar, EGGS, salt, WHEAT gluten, flour treatment agents (alpha-amylases, ascorbic acid, hemicellulases).Barn laid EGGS. May contain traces of: sesame seeds, soya, nuts."
        },
        {
          "attribute": {
            "id": "QXR0cmlidXRlOjEx",
            "slug": "recipies"
          },
          "pages": [
            {
              "__typename": "Page",
              "slug": "croque-madame-style-croissant"
            }
          ]
        },
        {
          "attribute": {
            "id": "QXR0cmlidXRlOjEw",
            "slug": "preparation"
          },
          "text": {
            "time": 1763646632526,
            "blocks": [
              {
                "id": "vEeXLCcGsW",
                "data": {
                  "text": "1. Tray arrangement: 9 items on a tray"
                },
                "type": "paragraph"
              },
              {
                "id": "uNLl6ltoo-",
                "data": {
                  "text": "2. Defrosting: approximately 30-45 min at room temperature."
                },
                "type": "paragraph"
              },
              {
                "id": "5VS-cD3n2k",
                "data": {
                  "text": "3. Preheating: 190°C"
                },
                "type": "paragraph"
              },
              {
                "id": "ZTgGuqCC-X",
                "data": {
                  "text": "4. Backing: approximately 15-18 min at 165-170°C, open damper"
                },
                "type": "paragraph"
              },
              {
                "id": "4LBhvtNCOR",
                "data": {
                  "text": "5. Rack in a temperature: 15 min at room temperature"
                },
                "type": "paragraph"
              }
            ],
            "version": "2.30.7"
          }
        },
        {
          "attribute": {
            "id": "QXR0cmlidXRlOjE=",
            "slug": "storage-conditions"
          },
          "plain_text": "Store at -18°C or below before use. DO NOT REFREEZE ONCE THAWED."
        }
      ]
    }
  }
}

Filtering Products by Attributes

A user can use a slug to filter products by attributes. The query parameters can be encoded in URL and will be the same in all languages.

An example of a products query:

query Products($first: Int, $channel: String, $where: ProductWhereInput) {
  products(first: $first, where: $where, channel: $channel) {
    edges {
      node {
        name
      }
    }
  }
}

{
  "first": 5,
  "channel": "default-channel",
  "where": {
    "attributes": [
      {
        "slug": "material",
        "value": {
          "name": {
            "oneOf": [
              "Cotton",
              "Wool"
            ]
          }
        }
      }
    ]
  }
}

{
  "data": {
    "products": {
      "edges": [
        {
          "node": {
            "name": "Monospace Tee"
          }
        },
        {
          "node": {
            "name": "Blue Polygon Shirt"
          }
        },
        {
          "node": {
            "name": "Cubes Fountain Tee"
          }
        },
        {
          "node": {
            "name": "Dark Polygon Tee"
          }
        },
        {
          "node": {
            "name": "Darko Polo"
          }
        }
      ]
    }
  }
}

Setting Allowed Reference Types

The attribute’s inputType must be REFERENCE or SINGLE_REFERENCE, and entityType must be PRODUCT, PRODUCT_VARIANT, or PAGE to use referenceTypes.

Creating an Attribute with Allowed Reference Types

Create a PRODUCT reference attribute with restricted product types with the use of attributeCreate mutation:

mutation attributeCreate($input: AttributeCreateInput!) {
  attributeCreate(input: $input) {
    attribute {
      id
      referenceTypes {
        ... on ProductType {
          __typename
          id
          slug
        }
      }
    }
    errors {
      field
      code
      message
    }
  }
}

{
  "input": {
    "name": "Related Products",
    "slug": "related-products",
    "type": "PRODUCT_TYPE",
    "inputType": "REFERENCE",
    "entityType": "PRODUCT",
    "referenceTypes": [
      "UHJvZHVjdFR5cGU6MQ=="
    ]
  }
}

{
  "data": {
    "attributeCreate": {
      "attribute": {
        "id": "QXR0cmlidXRlOjQ3",
        "referenceTypes": [
          {
            "__typename": "ProductType",
            "id": "UHJvZHVjdFR5cGU6MQ==",
            "slug": "default-type"
          }
        ]
      },
      "errors": []
    }
  }
}

Create a PAGE single-reference attribute with restricted page types:

mutation attributeCreate($input: AttributeCreateInput!) {
  attributeCreate(input: $input) {
    attribute {
      id
      referenceTypes {
        ... on PageType {
          __typename
          id
          slug
        }
      }
    }
    errors {
      field
      code
      message
    }
  }
}

{
  "input": {
    "name": "Related Page",
    "slug": "related-page",
    "type": "PAGE_TYPE",
    "inputType": "SINGLE_REFERENCE",
    "entityType": "PAGE",
    "referenceTypes": [
      "UGFnZVR5cGU6MQ=="
    ]
  }
}

{
  "data": {
    "attributeCreate": {
      "attribute": {
        "id": "QXR0cmlidXRlOjQ4",
        "referenceTypes": [
          {
            "__typename": "PageType",
            "id": "UGFnZVR5cGU6MQ==",
            "slug": "default-type"
          }
        ]
      },
      "errors": []
    }
  }
}

Update Allowed Reference Types

Adjust the allowed product types for a PRODUCT reference attribute with the use of attributeUpdate mutation:

mutation attributeUpdate($id: ID, $input: AttributeUpdateInput!) {
  attributeUpdate(id: $id, input: $input) {
    attribute {
      id
      referenceTypes {
        ... on ProductType {
          id
          slug
        }
      }
    }
    errors {
      field
      code
      message
    }
  }
}

{
  "id": "QXR0cmlidXRlOjQ3",
  "input": {
    "referenceTypes": [
      "UHJvZHVjdFR5cGU6MQ==",
      "UHJvZHVjdFR5cGU6MjI="
    ]
  }
}

{
  "data": {
    "attributeUpdate": {
      "attribute": {
        "id": "QXR0cmlidXRlOjQ3",
        "referenceTypes": [
          {
            "id": "UHJvZHVjdFR5cGU6MQ==",
            "slug": "default-type"
          },
          {
            "id": "UHJvZHVjdFR5cGU6MjI=",
            "slug": "simple"
          }
        ]
      },
      "errors": []
    }
  }
}

Clear restrictions (disables type validation for future updates/new values; existing references are not modified):

mutation attributeUpdate($id: ID, $input: AttributeUpdateInput!) {
  attributeUpdate(id: $id, input: $input) {
    attribute {
      id
      referenceTypes {
        ... on ProductType {
          id
          slug
        }
      }
    }
    errors {
      field
      code
      message
    }
  }
}

{
  "id": "QXR0cmlidXRlOjQ3",
  "input": {
    "referenceTypes": []
  }
}

{
  "data": {
    "attributeUpdate": {
      "attribute": {
        "id": "QXR0cmlidXRlOjQ3",
        "referenceTypes": []
      },
      "errors": []
    }
  }
}