GraphQL API

The Product Kits extension includes a GraphQL module that lets you retrieve kit data and add kit items to cart from headless storefronts or custom frontends.

For general information about GraphQL in Magento 2, refer to the GraphQL developer guide on Adobe DevDocs.

Workflow overview

The typical headless kit flow has two steps:

Fetch kit data for a product using the mstProductKitOfferKits query. This returns available kits, their items, and the pricing combinations. Pick a combination — its hash value becomes selectedCombination in step 2.
Add kit items to cart using addProductsToCart (or addSimpleProductsToCart). Pass one cart item per product in the selected combination, each carrying a kit_options entry with the kit metadata.

Queries

mstProductKitOfferKits

Returns the available kits for a given product.

Arguments:

Name	Type	Description
`product_id`	`Int!`	The ID of the product

Example:

{
  mstProductKitOfferKits(product_id: 1) {
    kit_id
    block_id
    title
    label
    items {
      item_id
      product_id
      is_optional
      qty
      product {
        sku
        name
      }
    }
    combinations {
      hash
      full_price { value currency }
      discounted_price { value currency }
      original_price { value currency }
      items {
        item_id
        product_id
        discount_amount { value }
        discount_type
        position
        full_price { value }
        discounted_price { value }
        regular_price { value }
      }
    }
  }
}

Response:

{
  "data": {
    "mstProductKitOfferKits": [
      {
        "kit_id": 1,
        "block_id": 3,
        "title": "Complete the Look",
        "label": "Save 15%",
        "items": [
          {
            "item_id": 1,
            "product_id": 100,
            "is_optional": false,
            "qty": 1,
            "product": { "sku": "jacket-m-blue", "name": "Blue Jacket" }
          },
          {
            "item_id": 2,
            "product_id": 101,
            "is_optional": false,
            "qty": 1,
            "product": { "sku": "pants-m-grey", "name": "Grey Pants" }
          }
        ],
        "combinations": [
          {
            "hash": "a1b2c3d4",
            "full_price": { "value": 140, "currency": "USD" },
            "discounted_price": { "value": 119, "currency": "USD" },
            "original_price": { "value": 140, "currency": "USD" },
            "items": [
              {
                "item_id": 1,
                "product_id": 100,
                "discount_amount": { "value": 12 },
                "discount_type": "percent",
                "position": 1,
                "full_price": { "value": 80 },
                "discounted_price": { "value": 68 },
                "regular_price": { "value": 80 }
              },
              {
                "item_id": 2,
                "product_id": 101,
                "discount_amount": { "value": 9 },
                "discount_type": "percent",
                "position": 2,
                "full_price": { "value": 60 },
                "discounted_price": { "value": 51 },
                "regular_price": { "value": 60 }
              }
            ]
          }
        ]
      }
    ]
  }
}

Adding kit items to cart

The extension extends the standard CartItemInput type with a kit_options field. This means kit_options is available in any mutation that accepts CartItemInput, including addProductsToCart, addSimpleProductsToCart, and addBundleProductsToCart.

Pass one cart item per product in the selected combination. Set selectedCombination to the hash value returned by mstProductKitOfferKits — use the same hash for every item in a single kit purchase.

addProductsToCart

mutation {
  addProductsToCart(
    cartId: "YOUR_CART_ID"
    cartItems: [
      {
        quantity: 1
        sku: "jacket-m-blue"
        kit_options: [{
          kit_id: 1
          item_id: 1
          product_id: 100
          position: 1
          block_id: 3
          qty: 1
          selectedCombination: "a1b2c3d4"
        }]
      }
      {
        quantity: 1
        sku: "pants-m-grey"
        kit_options: [{
          kit_id: 1
          item_id: 2
          product_id: 101
          position: 2
          block_id: 3
          qty: 1
          selectedCombination: "a1b2c3d4"
        }]
      }
    ]
  ) {
    cart {
      items {
        product { sku }
        quantity
        kit_options {
          is_kit_item
          kit_id
          product_id
          position
        }
      }
    }
    user_errors {
      code
      message
    }
  }
}

addSimpleProductsToCart

When using addSimpleProductsToCart, pass kit_options inside the data field:

mutation {
  addSimpleProductsToCart(
    input: {
      cart_id: "YOUR_CART_ID"
      cart_items: [
        {
          data: {
            quantity: 1
            sku: "jacket-m-blue"
            kit_options: [{
              kit_id: 1
              item_id: 1
              product_id: 100
              position: 1
              block_id: 3
              qty: 1
              selectedCombination: "a1b2c3d4"
            }]
          }
        }
        {
          data: {
            quantity: 1
            sku: "pants-m-grey"
            kit_options: [{
              kit_id: 1
              item_id: 2
              product_id: 101
              position: 2
              block_id: 3
              qty: 1
              selectedCombination: "a1b2c3d4"
            }]
          }
        }
      ]
    }
  ) {
    cart {
      items {
        product { sku }
        quantity
        kit_options {
          is_kit_item
          kit_id
          product_id
        }
      }
    }
  }
}

Types reference

mstProductKitOfferKit

Represents a product kit shown on a product page.

Field	Type	Description
`kit_id`	`Int`	Unique kit identifier
`block_id`	`Int`	Block/widget instance that displays this kit
`title`	`String`	Kit title shown to customers
`label`	`String`	Discount label (e.g. "Save 15%")
`items`	`[mstProductKitOfferItem]`	Products available in this kit
`combinations`	`[mstProductKitCombination]`	Pricing combinations for the kit

mstProductKitOfferItem

A single product slot in a kit.

Field	Type	Description
`item_id`	`Int`	Unique item identifier within the kit
`product_id`	`Int`	Magento product ID
`is_optional`	`Boolean`	Whether this item is optional
`qty`	`Int`	Default quantity for this item
`product`	`ProductInterface`	Full Magento product object

mstProductKitCombination

A pricing combination — the set of prices and discounts that apply when specific items are purchased together.

Field	Type	Description
`hash`	`String`	Unique combination identifier — use as `selectedCombination` when adding to cart
`full_price`	`Money`	Total price without kit discount
`discounted_price`	`Money`	Total price with kit discount applied
`original_price`	`Money`	Original price (shown when "Original + Final + Kit price" display mode is active)
`items`	`[mstProductKitCombinationItem]`	Per-item pricing within this combination

mstProductKitCombinationItem

Per-item pricing detail within a combination.

Field	Type	Description
`item_id`	`Int`	Kit item identifier (matches `mstProductKitOfferItem.item_id`)
`product_id`	`Int`	Magento product ID
`discount_amount`	`Money`	Discount applied to this item
`discount_type`	`String`	Discount type: `percent` or `fixed`
`position`	`Int`	Display position in the kit
`full_price`	`Money`	Item price without discount
`discounted_price`	`Money`	Item price after discount
`regular_price`	`Money`	Regular (catalog) price for this item

CartKitInfoInput

Input type for associating a cart item with a kit combination. Passed as an element of kit_options in add-to-cart mutations.

Field	Type	Description
`kit_id`	`Int!`	Kit identifier from `mstProductKitOfferKit.kit_id`
`item_id`	`Int!`	Item identifier from `mstProductKitOfferItem.item_id`
`product_id`	`Int!`	Product ID from `mstProductKitOfferItem.product_id`
`position`	`Int!`	Item position from `mstProductKitCombinationItem.position`
`block_id`	`Int!`	Block identifier from `mstProductKitOfferKit.block_id`
`qty`	`Int!`	Quantity being added
`selectedCombination`	`String!`	Combination hash from `mstProductKitCombination.hash`

mstKitItemInfo

Kit metadata returned on each cart item via CartItemInterface.kit_options.

Field	Type	Description
`is_kit_item`	`Boolean`	`true` if this cart item is part of a kit
`kit_id`	`String`	Identifier of the kit this item belongs to
`product_id`	`Int`	Product ID
`position`	`Int`	Item position in the kit

Workflow overview​

Queries​

mstProductKitOfferKits​

Adding kit items to cart​

addProductsToCart​

addSimpleProductsToCart​

Types reference​

mstProductKitOfferKit​

mstProductKitOfferItem​

mstProductKitCombination​

mstProductKitCombinationItem​

CartKitInfoInput​

mstKitItemInfo​