Models

Overview

Models provide a flexible mechanism for managing both traditional content and structured data entities that extend your commerce domain beyond the standard Product/Category/Collection model. Think of them as structured documents within Saleor.

Core Concepts

Model Types

A Model Type defines the schema for a group of models. It determines what attributes a model will have and how the model can be used. Think of Model Types as templates or schemas. For instance, a “Blog Post” model type might have attributes like Author, PublishedDate, and Tags.

You must create a Model Type before you can create any Model.

Attributes

Attributes define typed fields that can be reused across products and models. When creating an attribute, it must be explicitly assigned to either PRODUCT or PAGE type.

Models

A Model is an instance of a Model Type, enriched with specific attribute values and optionally a rich content block. Models can be created, linked to other entities, published, or removed.

Example Use Case

Modeling Scent Profiles in Perfume Store

Consider a specialized perfume store, where each product is a fragrance. Fragrances are complex blends, often composed of multiple scent profiles like “Citrus”, “Woody”, or “Floral”. These profiles are shared across products.

Here’s a breakdown of the entities and relationships:

Product Type: Fragrance
Product Attribute: Scent Profiles
- Type: REFERENCE
- Entity: Page
Model Type: Scent Profile
Model Attributes:
- Scent Family – Dropdown field (e.g., Citrus, Woody, Floral)
- Notes Description – Rich text field (e.g., Bright and zesty with a hint of green bitterness)

For the fragrance Sunlit Grove, the following scent profiles might be selected:

Citrus Zest
Green Woods

Each of these is a Model of type Scent Profile, reused across multiple products and enriched with structured attributes.

In the storefront UI, this structure enables rich product pages that showcase the fragrance’s composition. For example, the Sunlit Grove product page might display its scent profiles in a dedicated section, with each profile (Citrus Zest, Green Woods) showing its family type and detailed notes description.

Lifecycle

Creating a Model

To create a model through API, you must first define the model type and any required attributes.

mutation PageCreate($input: PageCreateInput!) {
  pageCreate(input: $input) {
    page {
      id
      title
    }
    errors {
      field
      message
    }
  }
}

{
  "input": {
    "title": "Citrus Zest",
    "slug": "citrus-zest",
    "isPublished": true,
    "pageType": "UGFnZVR5cGU6NDY="
  }
}

Getting Models

You can get individual model details using the page query:

query GetPage($id: ID!) {
  page(id: $id) {
    id
    title
    content
    attributes {
      attribute {
        name
        slug
      }
      values {
        name
      }
    }
  }
}

{
  "id": "UGFnZToz"
}

or you can get multiple models using the pages query:

query GetPages($first: Int, $filter: PageFilterInput) {
  pages(first: $first, filter: $filter) {
    totalCount
    edges {
      node {
        id
        title
        attributes {
          attribute {
            name
            slug
          }
          values {
            name
          }
        }
      }
    }
  }
}

{
  "first": 5,
  "filter": {
    "ids": ["UGFnZToz", "UGFnZTo0"]
  }
}

Linking Models

Models can reference or be referenced by other entities through attribute of type REFERENCE. The selection of referenceable entities is determined by AttributeEntityTypeEnum and currently includes PAGE, PRODUCT and PRODUCT_VARIANT.

mutation ProductUpdate($id: ID, $input: ProductInput!) {
  productUpdate(id: $id, input: $input) {
    product {
      id
      name
    }
    errors {
      field
      message
    }
  }
}

{
  "id": "UHJvZHVjdElE",
  "input": {
    "attributes": [
      {
        "id": "QXR0cmlidXRlSWQ=",   # Product Attribute of type REFERENCE for scent profiles
        "references": [
          "UGFnZUlE"   # ID of the Citrus Zest model
        ]
      }
    ]
  }
}

You can also model relationships between Models using a reference attribute or by embedding slugs/IDs in the model metadata.

Querying Linked Entities

Below is an example of how to query the linked entities using the product query:

query GetProductWithScentProfiles($productId: ID!) {
  product(id: $productId) {
    id
    name
    attributes {
      attribute {
        id
        slug # We are looking for "scent-profiles"
      }
      values {
        reference # This gives the Model ID
      }
    }
  }
}

The response will contain the ids of the linked models. You can then use the page query to get the details of the linked models.

Publishing Models

Models can be visible or hidden. You can control their visibility using:

isPublished (Boolean): Sets current visibility.
publicationDate (Date): Can schedule a future publication. The model won’t appear on the storefront until this date.

You can update the value of those fields using pageUpdate mutation:

mutation PageUpdate($id: ID!, $input: PageInput!) {
  pageUpdate(id: $id, input: $input) {
    page {
      id
      title
      isPublished
    }
    errors {
      field
      message
    }
  }
}

{
  "id": "UGFnZUlE",
  "input": {
    "isPublished": true,
    "publicationDate": "2025-04-15"
  }
}

Deleting Models

Use pageDelete for single models or pageBulkDelete for multiple. Deleting a Model is permanent. Deleting a Model Type might be restricted if Models are using it.

mutation DeletePage($id: ID!) {
  pageDelete(id: $id) {
    page {
      id
    }
    errors {
      field
      code
      message
    }
  }
}

mutation DeleteMultiplePages($ids: [ID!]!) {
  pageBulkDelete(ids: $ids) {
    count
    errors {
      field
      code
      message
    }
  }
}

Webhooks

Here are the webhooks that are available for models: