Skip to main content

GraphQL Reference

This section describes the GraphQL schema provided by the Improved Sorting extension for managing pinned products functionality.

For general information about GraphQL in Magento, refer to the GraphQL Developer Guide.

Extended Magento Objects​

The extension adds new fields to standard Magento GraphQL types.

ProductInterface​

The ProductInterface is extended with the following fields:

FieldDescriptionData Type
pinned_category_idsArray of category IDs where the product is pinned to top.[Int]
pin_to_topIndicates if the product is pinned to top in the current category context. Returns null if no category context is available.Boolean

CategoryInterface / CategoryTree​

The CategoryInterface and CategoryTree types are extended with the following field:

FieldDescriptionData Type
pinned_product_idsArray of product IDs that are pinned to top in the category.[Int]

Sorting Input​

The extension adds sorting options to the ProductAttributeSortInput type:

FieldDescriptionData Type
mst_sortApply a custom sorting criterion by code.MstSortCriteria
mst_pinWhen set to true, pinned products are returned first.Boolean

MstSortCriteria​

InputDescriptionData Type
codeThe code of the sorting criterion to apply.String
dirSort direction: ASC or DESC.SortEnum

Mutations​

The extension provides two mutations for managing pinned products. Both mutations require admin authorization with the Mirasvit_Sorting::sorting ACL resource.

setPinnedCategories​

Sets the categories where a product should be pinned to top.

Input:

FieldDescriptionData Type
product_idThe product ID.Int!
category_idsArray of category IDs where the product should be pinned.[Int!]!

Output (PinnedCategoriesOutput):

FieldDescriptionData Type
successIndicates if the operation was successful.Boolean!
messageResult message.String
product_idThe product ID.Int
category_idsUpdated array of category IDs where the product is pinned.[Int]

setPinnedProducts​

Sets the products that should be pinned to top in a category.

Input:

FieldDescriptionData Type
category_idThe category ID.Int!
product_idsArray of product IDs to pin in the category.[Int!]!

Output (PinnedProductsOutput):

FieldDescriptionData Type
successIndicates if the operation was successful.Boolean!
messageResult message.String
category_idThe category ID.Int
product_idsUpdated array of pinned product IDs.[Int]

Usage Examples​

Query pinned products in a category​

Retrieve a category with its pinned product IDs:

query {
  category(id: 10) {
    id
    name
    pinned_product_ids
  }
}

Response:

{
  "data": {
    "category": {
      "id": 10,
      "name": "Gear",
      "pinned_product_ids": [42, 58, 103]
    }
  }
}

Query product with pinned categories​

Retrieve a product and see which categories it is pinned in:

query {
  products(filter: { sku: { eq: "24-MB01" } }) {
    items {
      id
      name
      sku
      pinned_category_ids
    }
  }
}

Response:

{
  "data": {
    "products": {
      "items": [
        {
          "id": 1,
          "name": "Joust Duffle Bag",
          "sku": "24-MB01",
          "pinned_category_ids": [3, 10]
        }
      ]
    }
  }
}

Query products with pin_to_top status​

When querying products within a category context, the pin_to_top field indicates if each product is pinned:

query {
  products(
    filter: { category_id: { eq: "10" } }
    sort: { mst_pin: true }
  ) {
    items {
      id
      name
      pin_to_top
    }
  }
}

Response:

{
  "data": {
    "products": {
      "items": [
        {
          "id": 42,
          "name": "Affirm Water Bottle",
          "pin_to_top": true
        },
        {
          "id": 58,
          "name": "Sprite Yoga Strap",
          "pin_to_top": true
        },
        {
          "id": 15,
          "name": "Compete Track Tote",
          "pin_to_top": false
        }
      ]
    }
  }
}

Pin a product to categories​

Pin product ID 42 to categories 3 and 10:

mutation {
  setPinnedCategories(
    input: {
      product_id: 42
      category_ids: [3, 10]
    }
  ) {
    success
    message
    product_id
    category_ids
  }
}

Response:

{
  "data": {
    "setPinnedCategories": {
      "success": true,
      "message": "Pinned categories updated successfully.",
      "product_id": 42,
      "category_ids": [3, 10]
    }
  }
}

Pin products to a category​

Pin products 42, 58, and 103 to category ID 10:

mutation {
  setPinnedProducts(
    input: {
      category_id: 10
      product_ids: [42, 58, 103]
    }
  ) {
    success
    message
    category_id
    product_ids
  }
}

Response:

{
  "data": {
    "setPinnedProducts": {
      "success": true,
      "message": "Pinned products updated successfully.",
      "category_id": 10,
      "product_ids": [42, 58, 103]
    }
  }
}

Remove all pins from a product​

To unpin a product from all categories, pass an empty array:

mutation {
  setPinnedCategories(
    input: {
      product_id: 42
      category_ids: []
    }
  ) {
    success
    message
    category_ids
  }
}

Authorization​

The setPinnedCategories and setPinnedProducts mutations require:

  • An authenticated admin user (integration token)
  • The Mirasvit_Sorting::sorting ACL resource permission

Attempting to execute these mutations without proper authorization returns an error:

{
  "errors": [
    {
      "message": "The current user is not authorized to manage pinned products."
    }
  ]
}

Query operations (pinned_category_ids, pinned_product_ids, pin_to_top) do not require authentication and can be used in storefront applications.