Skip to main content

Models

API Compatibility Notice

While we've updated the terminology in the documentation to use "Models" and "Model Types", the API endpoints and GraphQL schema still use pages and pageTypes. This is temporary, and we plan to update the API to match the new terminology soon.

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.

info

You can manage Model Types in the Dashboard's -> Modeling -> Model Types view.

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.

info

You can manage Models in the Dashboard's -> Modeling -> Models view.

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.

info

Creating a model requires the MANAGE_PAGES permission.

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

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
      }
    }
  }
}

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
          }
        }
      }
    }
  }
}

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
    }
  }
}

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.
info

If isPublished is false, only users with the MANAGE_PAGES permission will be able to successfully retrieve it.

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
    }
  }
}

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: