GraphQL API

Effortlessly integrate and retrieve all your Related Products data with our GraphQL API.
This API makes it simple for developers to build custom recommendations, personalized product displays, and track user interactions across headless storefronts or third-party applications.

For comprehensive information about GraphQL, refer to the GraphQL developer guide on the Magento DevDocs page.

---

Queries

mstRelatedBlocks

Description: returns a list of related product blocks for the specified entity (product, category, order, or customer).

Response: returns an array of mstRelatedBlock

Arguments:

Name	Data Type	Description
entity_type	mstSelectionEntityType!	Entity type (PRODUCT, CATEGORY, ORDER, CUSTOMER)
entity_id	Int!	The ID of the entity
position	String	(Optional) Filter by block position on the page (e.g. content.bottom)
only_active	Boolean	(Optional) If true, returns only active blocks

Example:

Query:

query {
  mstRelatedBlocks(
    entity_type: PRODUCT,
    entity_id: 123,
    position: "content.bottom",
    only_active: true
  ) {
    block_id
    display_title
    priority
    position
    products {
      sku
      name
      price_range {
        minimum_price {
          regular_price {
            value
            currency
          }
        }
      }
    }
  }
}

Response:

{
  "data": {
    "mstRelatedBlocks": [
      {
        "block_id": "5",
        "display_title": "You May Also Like",
        "priority": 10,
        "position": "content.bottom",
        "products": [
          {
            "sku": "24-MB01",
            "name": "Joust Duffle Bag",
            "price_range": {
              "minimum_price": {
                "regular_price": {
                  "value": 34,
                  "currency": "USD"
                }
              }
            }
          }
        ]
      }
    ]
  }
}

---

mstRelatedBlock

Description: returns a single related products block by its ID.

Response: returns a mstRelatedBlock

Arguments:

Name	Data Type	Description
entity_type	mstSelectionEntityType!	Entity type (PRODUCT, CATEGORY, ORDER, CUSTOMER)
entity_id	Int!	The ID of the entity
block_id	Int!	The ID of the related block
only_active	Boolean	(Optional) If true, returns only active blocks

Example:

Query:

query {
  mstRelatedBlock(
    entity_type: PRODUCT,
    entity_id: 123,
    block_id: 5,
    only_active: true
  ) {
    block_id
    display_title
    position
    products {
      sku
      name
    }
  }
}

Response:

{
  "data": {
    "mstRelatedBlock": {
      "block_id": "5",
      "display_title": "Cross-sell Products",
      "position": "cart.crosssell",
      "products": [
        {
          "sku": "24-WG03",
          "name": "Overnight Duffle"
        }
      ]
    }
  }
}

---

Mutations

mstRelatedTrack

Description: tracks a user interaction (click or impression) with a related block.

Response: returns a confirmation string.

Arguments:

Name	Data Type	Description
type	mstRelatedTrackAction!	Type of interaction (CLICK or IMPRESSION)
block_id	Int!	Related block ID
session_id	String!	Unique session identifier

Example:

Mutation:

mutation {
  mstRelatedTrack(
    type: CLICK,
    block_id: 5,
    session_id: "abc123"
  )
}

Response:

{
  "data": {
    "mstRelatedTrack": "ok"
  }
}

---

Objects & Enums

mstRelatedBlock object

Represents a related products block.

Attribute	Data Type	Description
block_id	String	Unique block identifier
display_title	String	Block title shown on storefront
priority	Int	Block priority order
position	String	Position of the block on the page
products	[ProductInterface]	Array of Magento products in the block

---

mstSelectionEntityType enum

Defines the entity type used when requesting related products.

Value	Description
CATEGORY	Related products based on category
CUSTOMER	Related products based on customer activity
PRODUCT	Related products for a specific product
ORDER	Related products from an order

---

mstRelatedTrackAction enum

Defines tracking actions for recommendation performance.

Value	Description
CLICK	Track when a product in the block is clicked
IMPRESSION	Track when the block is displayed (viewed)