@doswiftly/storefront-operations 7.0.0 → 7.1.0

package/fragments.graphql

@@ -4,9 +4,10 @@
 # ============================================
 
 # ============================================
-# Common Fragments
+# Common
 # ============================================
 
+# Standard Relay Connection page metadata. Spread on every paginated query's `pageInfo`.
 fragment PageInfo on PageInfo {
   hasNextPage
   hasPreviousPage
@@ -14,19 +15,21 @@ fragment PageInfo on PageInfo {
   endCursor
 }
 
+# Generic mutation error envelope — included in every mutation's `userErrors[]` field. Always check before consuming the happy-path payload.
 fragment UserError on UserError {
   message
   code
   field
 }
 
+# Non-blocking cart warning (e.g. low stock, partial availability). Cart mutations succeed but surface these for UI hints.
 fragment CartWarning on CartWarning {
   message
   code
   target
 }
 
-# Base Image — no transform (for logos, favicons, branding assets that are already small)
+# Base image — original size, no transform. Use for logos, favicons, branding assets that are already sized correctly. ~few KB.
 fragment Image on Image {
   id
   url
@@ -35,8 +38,7 @@ fragment Image on Image {
   height
 }
 
-# Thumbnail — cart items, variant swatches, author avatars (rendered at ~96px, 300px covers 3x DPI)
-# No preferredContentType — imgproxy auto-negotiates AVIF/WEBP from Accept header
+# Thumbnail — cart line items, variant swatches, author avatars (rendered ~96px on screen, transform delivers up to 300px for 3x DPI). Includes `thumbhash` for blurred placeholder. Format auto-negotiated from the `Accept` header.
 fragment ImageThumbnail on Image {
   id
   url(transform: { maxWidth: 300 })
@@ -46,7 +48,7 @@ fragment ImageThumbnail on Image {
   thumbhash
 }
 
-# Card — product cards, collection/category cards, blog posts (rendered at ~400px, 800px covers 2x DPI)
+# Card — product cards, collection / category tiles, blog post previews (rendered ~400px, transform delivers up to 800px for 2x DPI). Includes `thumbhash` placeholder.
 fragment ImageCard on Image {
   id
   url(transform: { maxWidth: 800 })
@@ -56,7 +58,7 @@ fragment ImageCard on Image {
   thumbhash
 }
 
-# Full — product detail gallery, hero images (rendered at ~800px, 1600px covers 2x DPI)
+# Full — product detail gallery, hero banners (rendered ~800px, transform delivers up to 1600px for 2x DPI). Includes `thumbhash` placeholder.
 fragment ImageFull on Image {
   id
   url(transform: { maxWidth: 1600 })
@@ -66,19 +68,19 @@ fragment ImageFull on Image {
   thumbhash
 }
 
-# Simple money (for originalPrice fields and non-converted prices)
+# Plain `{ amount, currencyCode }` price. Use for `compareAtPrice`, totals, and any field where currency conversion transparency is not needed. `amount` is a String.
 fragment Money on Money {
   amount
   currencyCode
 }
 
-# Lightweight price for listing views (cards, grids, search results)
+# Lightweight price for listing views (cards, grids, search results) — same shape as `Money`. Spread when full conversion metadata is overkill.
 fragment Price on PriceMoney {
   amount
   currencyCode
 }
 
-# Full price with conversion transparency (for price fields that support currency conversion)
+# Full price with currency-conversion transparency — adds `baseAmount`, `baseCurrencyCode`, `exchangeRate`, `marginApplied`, `rateTimestamp`, `isConverted`. Spread on PDP / cart / checkout where the customer needs to see the original price + applied conversion.
 fragment PriceMoney on PriceMoney {
   ...Price
   baseAmount
@@ -89,15 +91,17 @@ fragment PriceMoney on PriceMoney {
   isConverted
 }
 
+# Selected variant option (e.g. `{ name: "Color", value: "Red" }`) on a `ProductVariant`. Use to render variant labels in cart / order summaries.
 fragment SelectedOption on SelectedOption {
   name
   value
 }
 
 # ============================================
-# Product Fragments
+# Products
 # ============================================
 
+# Single variant of a product — price, compare-at, stock flags, sort, image, selected options. Spread on cart line items, PDP variant selectors, search result rows that need price.
 fragment ProductVariant on ProductVariant {
   id
   title
@@ -124,8 +128,7 @@ fragment ProductVariant on ProductVariant {
   sortOrder
 }
 
-# Minimal product data for listing views (cards, grids, search results).
-# Matches template-local ProductCardFields for consistent typing.
+# Minimal product shape for listing views (collection grids, search results, "you may also like"). Includes price range, featured image (card size), rating + review count, vendor, tags. Use for any list of products where you don't need variants/description.
 fragment ProductCard on Product {
   id
   handle
@@ -157,7 +160,7 @@ fragment ProductCard on Product {
   }
 }
 
-# Full product data for detail views and pages that need all fields.
+# `ProductCard` plus textual content (description, descriptionHtml), stock total, type, visibility flags, and timestamps. Use when you need full product copy but not the heavy variants/images lists. Sweet spot for blog post embeds, related-product cards with description.
 fragment ProductBase on Product {
   ...ProductCard
   description
@@ -165,13 +168,13 @@ fragment ProductBase on Product {
   stockTotal
   type
   requiresRecipientInfo
-  # Faza 1.5 (Decision D-A v3 + D-B)
   visibility
   attributeSetId
   createdAt
   updatedAt
 }
 
+# Full product shape for the PDP — `ProductBase` plus the full image gallery (up to 20, full-size) and all variants (up to 100) with their pricing/stock. Spread on the product detail page.
 fragment ProductFull on Product {
   ...ProductBase
   images(first: 20) {
@@ -211,9 +214,10 @@ fragment ProductFull on Product {
 }
 
 # ============================================
-# Collection Fragments
+# Collections
 # ============================================
 
+# Collection (manual or rule-based product grouping) — title, description, hero image, SEO. Spread on collection landing pages and collection cards. Does NOT include products — query `collection(id, handle).products` separately for those.
 fragment Collection on Collection {
   id
   handle
@@ -232,9 +236,10 @@ fragment Collection on Collection {
 }
 
 # ============================================
-# Category Fragments
+# Categories
 # ============================================
 
+# Category node in the shop's taxonomy — name, slug, hero image, depth `level`, materialized `path`, product count, sort order. Spread on category cards and breadcrumb segments. Does NOT include parent / children — query those fields separately and let the server batch them.
 fragment Category on Category {
   id
   name
@@ -250,9 +255,10 @@ fragment Category on Category {
 }
 
 # ============================================
-# Customer Fragments
+# Customer
 # ============================================
 
+# Customer mailing address — full street/city/state/country/postal code with names and phone. `isDefault` flips when this address is the default for shipping. Spread on the address book UI and order summaries.
 fragment MailingAddress on MailingAddress {
   id
   streetLine1
@@ -270,11 +276,13 @@ fragment MailingAddress on MailingAddress {
   isDefault
 }
 
+# Customer access token returned by `customerLogin` / `customerSignup` / `customerActivate` / `customerResetPassword` / `customerRefreshToken`. The token's JWT TTL is 24h; cookie max-age is 30d.
 fragment CustomerAccessToken on CustomerAccessToken {
   accessToken
   expiresAt
 }
 
+# Customer profile — basic info plus B2B fields (`taxId`, `vatNumber`, `regon`, `companyName`), default address, lifetime stats (`orderCount`, `totalSpent`), marketing preferences. Use on profile / settings pages.
 fragment Customer on Customer {
   id
   email
@@ -301,6 +309,7 @@ fragment Customer on Customer {
   updatedAt
 }
 
+# Order summary — number, totals (cost / tax / shipping), payment + fulfillment status, shipping address, item count, lifecycle timestamps. Spread on the order list and order detail pages. Line items are not included here.
 fragment Order on Order {
   id
   orderNumber
@@ -332,9 +341,10 @@ fragment Order on Order {
 }
 
 # ============================================
-# Cart Fragments
+# Cart
 # ============================================
 
+# Cart-level totals — subtotal, total, tax, duty, checkout charge. Spread inside the `Cart` fragment.
 fragment CartCost on CartCost {
   total {
     ...Money
@@ -353,6 +363,7 @@ fragment CartCost on CartCost {
   }
 }
 
+# Per-line cost breakdown — unit price, line subtotal/total, compare-at unit price (for showing strikethroughs). Spread inside `CartLine`.
 fragment CartLineCost on CartLineCost {
   pricePerUnit {
     ...Money
@@ -368,8 +379,7 @@ fragment CartLineCost on CartLineCost {
   }
 }
 
-# Typed customer-filled attribute snapshot (Faza 1 R5 + Decision D-A v3 + D-I).
-# Distinct from CartLine.attributes (raw KV line item properties).
+# Typed snapshot of a customer-filled product attribute (configurator selection) on a cart line. Includes the chosen option / text value, fillingMode, billingMode, surcharge, tax class, and any linked variant. Distinct from `CartLine.attributes` which holds raw key-value line item properties (free-form, untyped).
 fragment AttributeSelection on AttributeSelection {
   attributeDefinitionId
   attributeName
@@ -386,6 +396,7 @@ fragment AttributeSelection on AttributeSelection {
   linkedVariantId
 }
 
+# A single line in the cart — variant + quantity + per-line cost, plus dual attribute storage: `attributes[]` for free-form key-value properties (gift wrap, engraving notes), `attributeSelections[]` for typed configurator answers.
 fragment CartLine on CartLine {
   id
   quantity
@@ -408,17 +419,20 @@ fragment CartLine on CartLine {
   productType
 }
 
+# Buyer identity associated with the cart. Note: only `customerId` is currently persisted server-side; `email`, `phone`, `countryCode` are accepted in the input but ignored.
 fragment CartBuyerIdentity on CartBuyerIdentity {
   email
   phone
   countryCode
 }
 
+# Discount code applied to the cart with its `isApplicable` flag — false means the code was kept on the cart but does not currently qualify (e.g. minimum spend not reached).
 fragment CartDiscountCode on CartDiscountCode {
   code
   isApplicable
 }
 
+# Allocation of a discount code to the cart total — pairs the code with the actual money discounted. Use to show "saved X with code Y" in cart UI.
 fragment CartDiscountAllocation on CartDiscountAllocation {
   discountCode
   amount {
@@ -426,6 +440,7 @@ fragment CartDiscountAllocation on CartDiscountAllocation {
   }
 }
 
+# Full cart shape — totals, line items (paginated up to 100), buyer identity, applied discount codes + allocations, note, custom attributes. Spread on the cart drawer / cart page; refetch after every cart mutation.
 fragment Cart on Cart {
   id
   checkoutUrl
@@ -471,9 +486,10 @@ fragment Cart on Cart {
 }
 
 # ============================================
-# Shop Fragments
+# Shop
 # ============================================
 
+# Shop branding colors — primary, secondary, accent, background, text. Use to theme the storefront from server-side config.
 fragment ShopColors on ShopColors {
   primary
   secondary
@@ -482,11 +498,13 @@ fragment ShopColors on ShopColors {
   text
 }
 
+# Shop branding fonts — body (`primary`) and `heading` font families.
 fragment ShopFonts on ShopFonts {
   primary
   heading
 }
 
+# Social media links configured for the shop. Spread on the footer.
 fragment SocialLinks on SocialLinks {
   facebook
   instagram
@@ -497,6 +515,7 @@ fragment SocialLinks on SocialLinks {
   pinterest
 }
 
+# Shop's physical / business address. Use on the contact page and footer.
 fragment ShopAddress on ShopAddress {
   streetLine1
   streetLine2
@@ -506,6 +525,7 @@ fragment ShopAddress on ShopAddress {
   country
 }
 
+# One day's business hours window. Spread inside `Shop.businessHours[]`.
 fragment BusinessHour on BusinessHour {
   day
   openTime
@@ -513,6 +533,7 @@ fragment BusinessHour on BusinessHour {
   isClosed
 }
 
+# Full shop branding bundle — logo + favicon + colors + fonts + social links. Spread inside the `Shop` fragment.
 fragment ShopBranding on ShopBranding {
   logo {
     ...Image
@@ -531,12 +552,14 @@ fragment ShopBranding on ShopBranding {
   }
 }
 
+# Bot-protection provider config (provider name, site key, script URL) for storefront-side challenge widgets.
 fragment BotProtectionProvider on BotProtectionProviderInfo {
   provider
   siteKey
   scriptUrl
 }
 
+# Bot-protection setup for the shop — primary + fallback provider, and the list of `protectedOperations` (mutation names that require a challenge token). Spread inside `Shop`.
 fragment BotProtection on BotProtectionInfo {
   primary {
     ...BotProtectionProvider
@@ -547,6 +570,7 @@ fragment BotProtection on BotProtectionInfo {
   protectedOperations
 }
 
+# The shop itself — name, primary domain, currencies + locales, branding, contact info, business hours, bot-protection config. Spread on the root `shop` query; cache for the session.
 fragment Shop on Shop {
   id
   name
@@ -581,9 +605,10 @@ fragment Shop on Shop {
 }
 
 # ============================================
-# Payment Method Fragments (R23 - Payment Methods)
+# Payment Methods
 # ============================================
 
+# Single payment method enabled for the shop — type (CARD / BANK_TRANSFER / BLIK / PAYPAL / APPLE_PAY / GOOGLE_PAY / CASH_ON_DELIVERY / OTHER), provider, icon, supported currencies, default flag, sort position. Spread on the checkout payment step.
 fragment PaymentMethod on PaymentMethod {
   id
   name
@@ -596,6 +621,7 @@ fragment PaymentMethod on PaymentMethod {
   position
 }
 
+# Active payment methods list with the merchant's `defaultMethod`. Returned by the `availablePaymentMethods` query.
 fragment AvailablePaymentMethods on AvailablePaymentMethods {
   methods {
     ...PaymentMethod
@@ -606,9 +632,10 @@ fragment AvailablePaymentMethods on AvailablePaymentMethods {
 }
 
 # ============================================
-# Checkout Fragments
+# Checkout
 # ============================================
 
+# Single shipping rate option — `handle` is the stable id you pass to `checkoutShippingLineUpdate`, plus title and price.
 fragment ShippingRate on ShippingRate {
   handle
   title
@@ -617,6 +644,7 @@ fragment ShippingRate on ShippingRate {
   }
 }
 
+# One tax line on the checkout — title, rate (decimal, e.g. 0.23 for 23%), computed amount. Spread on the order summary.
 fragment TaxLine on TaxLine {
   title
   rate
@@ -625,6 +653,7 @@ fragment TaxLine on TaxLine {
   }
 }
 
+# Item affected by a discount — the discounted product/variant with original + discounted prices and savings. Used on Buy-X-Get-Y promotions to highlight which items the discount applies to.
 fragment DiscountAffectedItem on DiscountAffectedItem {
   productId
   variantId
@@ -642,6 +671,7 @@ fragment DiscountAffectedItem on DiscountAffectedItem {
   isFreeItem
 }
 
+# A discount currently applied to the checkout — code, type, value, plus BXGY (Buy X Get Y) metadata when applicable (`buyQuantity`, `getQuantity`, `getDiscountPercent`, `affectedItems`). Use to render a "Discounts applied" panel.
 fragment DiscountApplication on DiscountApplication {
   code
   isApplicable
@@ -650,7 +680,6 @@ fragment DiscountApplication on DiscountApplication {
     ...Money
   }
   title
-  # BXGY (Buy X Get Y) specific fields
   affectedItems {
     ...DiscountAffectedItem
   }
@@ -659,11 +688,13 @@ fragment DiscountApplication on DiscountApplication {
   getDiscountPercent
 }
 
+# Lightweight discount code entry on the checkout — code + applicability flag.
 fragment DiscountCode on DiscountCode {
   code
   isApplicable
 }
 
+# Single line item in the checkout — variant snapshot, quantity, unit + total prices, image. Use on the order summary panel.
 fragment CheckoutLineItem on CheckoutLineItem {
   id
   title
@@ -683,7 +714,7 @@ fragment CheckoutLineItem on CheckoutLineItem {
   }
 }
 
-# GAP-001: Gift Card Checkout Integration
+# Gift card applied to the checkout — `maskedCode` (first + last 4 chars), `lastCharacters` (for display matching), the amount applied to this checkout, and remaining balance after this order would complete.
 fragment AppliedGiftCard on AppliedGiftCard {
   maskedCode
   lastCharacters
@@ -695,6 +726,7 @@ fragment AppliedGiftCard on AppliedGiftCard {
   }
 }
 
+# Full checkout shape — line items, shipping + billing addresses, selected + available shipping rates, available payment methods, applied discounts + gift cards, tax lines, totals (`cost`, `paymentDue`, `totalGiftCardAmount`). Spread on the checkout flow; refetch after every checkout mutation. `isReady` flips to true when the checkout has all required fields to call `checkoutComplete`.
 fragment Checkout on Checkout {
   id
   isReady
@@ -741,7 +773,6 @@ fragment Checkout on Checkout {
   taxLines {
     ...TaxLine
   }
-  # GAP-001: Gift Card Checkout Integration
   appliedGiftCards {
     ...AppliedGiftCard
   }
@@ -758,9 +789,10 @@ fragment Checkout on Checkout {
 }
 
 # ============================================
-# Shipment Fragments (R29 - Shipment Tracking)
+# Shipments / Tracking
 # ============================================
 
+# One tracking event in the shipment timeline — status, description, location, timestamp. Spread on the tracking page timeline.
 fragment ShipmentEvent on ShipmentEvent {
   id
   status
@@ -770,6 +802,7 @@ fragment ShipmentEvent on ShipmentEvent {
   providerEventCode
 }
 
+# Physical package metadata (weight + dimensions). Used in the merchant's label generation; storefronts rarely render this directly.
 fragment ShipmentPackage on ShipmentPackage {
   weight
   length
@@ -777,6 +810,7 @@ fragment ShipmentPackage on ShipmentPackage {
   height
 }
 
+# One item in a shipment — title, variant, sku, quantity, image URL. Spread inside `Shipment.items[]` for the tracking page item list.
 fragment ShipmentItem on ShipmentItem {
   id
   title
@@ -786,6 +820,7 @@ fragment ShipmentItem on ShipmentItem {
   imageUrl
 }
 
+# Full shipment shape — provider, tracking number + URL, label URL, status, ETA, recipient address, packages, items, full event timeline. Spread on the tracking page.
 fragment Shipment on Shipment {
   id
   orderId
@@ -814,6 +849,7 @@ fragment Shipment on Shipment {
   updatedAt
 }
 
+# Lightweight shipment shape — id, tracking number + URL, status, dates. No items / events / address. Use for order summary cards or on the public `shipmentByTrackingNumber` query.
 fragment ShipmentBasic on Shipment {
   id
   orderId
@@ -828,9 +864,10 @@ fragment ShipmentBasic on Shipment {
 }
 
 # ============================================
-# Return Fragments (R30 - Returns/RMA)
+# Returns / RMA
 # ============================================
 
+# Return shipping label generated by the carrier — URL to download, carrier name, tracking number, expiry. Spread on the return detail page.
 fragment ReturnShippingLabel on ReturnShippingLabel {
   url
   carrier
@@ -838,6 +875,7 @@ fragment ReturnShippingLabel on ReturnShippingLabel {
   expiresAt
 }
 
+# Photo evidence attached to a return item (e.g. damage photo). Spread inside `ReturnItem.photos[]`.
 fragment ReturnItemPhoto on ReturnItemPhoto {
   id
   url
@@ -846,6 +884,7 @@ fragment ReturnItemPhoto on ReturnItemPhoto {
   createdAt
 }
 
+# Single line in a return request — variant identity, quantity requested, reason, condition, photos, status, approved quantity (set by merchant after review). Spread inside `Return.items[]`.
 fragment ReturnItem on ReturnItem {
   id
   variantId
@@ -866,6 +905,7 @@ fragment ReturnItem on ReturnItem {
   approvedQuantity
 }
 
+# Full return shape — number, parent order, status, reason, customer note, compensation type (`REFUND` / `STORE_CREDIT`), items, refund amount, shipping label, lifecycle timestamps. Spread on the return detail page.
 fragment Return on Return {
   id
   returnNumber
@@ -893,6 +933,7 @@ fragment Return on Return {
   updatedAt
 }
 
+# Single option in the return reasons dropdown — `value` enum, human-readable `label`, optional `description`. Returned by `returnReasons` query.
 fragment ReturnReasonOption on ReturnReasonOption {
   value
   label
@@ -900,9 +941,10 @@ fragment ReturnReasonOption on ReturnReasonOption {
 }
 
 # ============================================
-# Gift Card Fragments (R32 - Gift Cards)
+# Gift Cards
 # ============================================
 
+# Gift card detail — masked code (first + last 4 chars), status, initial + remaining balance, expiry, recipient/message. Returned by `giftCard($code)` query.
 fragment GiftCard on GiftCard {
   id
   maskedCode
@@ -919,11 +961,13 @@ fragment GiftCard on GiftCard {
   createdAt
 }
 
+# Validation error on a gift card check — code (`NOT_FOUND` / `DISABLED` / `ALREADY_USED` / `EXPIRED` / `INSUFFICIENT_BALANCE`) + human message.
 fragment GiftCardError on GiftCardError {
   code
   message
 }
 
+# Result of `giftCardValidate($code, $amount)` — `isValid` flag, available balance, optional `error` (when invalid), and the matched gift card (when found). Use to inline-validate gift card inputs before applying.
 fragment GiftCardValidation on GiftCardValidation {
   isValid
   availableBalance {
@@ -938,9 +982,10 @@ fragment GiftCardValidation on GiftCardValidation {
 }
 
 # ============================================
-# Shipping Method Fragments (R33 - Shipping Methods)
+# Shipping Methods
 # ============================================
 
+# Carrier offering the shipping method — id, display name, logo URL, internal service code.
 fragment ShippingCarrier on ShippingCarrier {
   id
   name
@@ -948,12 +993,14 @@ fragment ShippingCarrier on ShippingCarrier {
   serviceCode
 }
 
+# Estimated delivery window — `minDays` to `maxDays` plus a human-readable description (e.g. "2-4 business days").
 fragment DeliveryEstimate on DeliveryEstimate {
   minDays
   maxDays
   description
 }
 
+# Free-shipping progress info — `qualifies` flag, current cart amount, threshold, remaining to qualify, percent progress, and a localized message ("Add 20 PLN more for free shipping"). Use to render a free-shipping progress bar in the cart drawer.
 fragment FreeShippingProgress on FreeShippingProgress {
   qualifies
   currentAmount {
@@ -969,6 +1016,7 @@ fragment FreeShippingProgress on FreeShippingProgress {
   message
 }
 
+# One shipping method offered for the destination + cart — id, name, carrier, price, free-shipping progress, estimated delivery, sort order. Spread on the checkout shipping step.
 fragment AvailableShippingMethod on AvailableShippingMethod {
   id
   name
@@ -990,20 +1038,23 @@ fragment AvailableShippingMethod on AvailableShippingMethod {
 }
 
 # ============================================
-# Attribute Filter Fragments (R35 - Dynamic Attributes)
+# Attribute Filters
 # ============================================
 
+# Visual swatch for an attribute filter value — color hex (for color filters) or image URL (for pattern/material swatches).
 fragment AttributeSwatch on AttributeSwatch {
   colorHex
   imageUrl
 }
 
+# Numeric range bounds for slider-style filters — min, max, currency code (when relevant).
 fragment AttributeRangeBounds on AttributeRangeBounds {
   min
   max
   currencyCode
 }
 
+# One discrete value in a filterable attribute (e.g. "Red" for the Color filter). Includes `productCount` in the current listing context (for "(12)" badges next to filter values), optional swatch and price modifier.
 fragment AttributeFilterValue on AttributeFilterValue {
   id
   value
@@ -1018,6 +1069,7 @@ fragment AttributeFilterValue on AttributeFilterValue {
   sortOrder
 }
 
+# Filterable attribute exposed on the storefront — name, type (SELECT / CHECKBOX / SLIDER / etc.), filterability flags, display order, and either discrete `filterValues[]` or numeric `rangeBounds`. Spread inside `availableFilters.attributes[]`.
 fragment AttributeDefinition on AttributeDefinition {
   id
   name
@@ -1034,6 +1086,7 @@ fragment AttributeDefinition on AttributeDefinition {
   }
 }
 
+# Min / max price range across products in the current listing context. Use to bound the price slider.
 fragment PriceRangeFilter on PriceRange {
   min {
     ...Money
@@ -1043,6 +1096,7 @@ fragment PriceRangeFilter on PriceRange {
   }
 }
 
+# One category option in the categories filter — id, name, slug, count of products in this category within the current listing context, level + parentId for tree rendering.
 fragment CategoryFilterOption on CategoryFilterOption {
   id
   name
@@ -1052,6 +1106,7 @@ fragment CategoryFilterOption on CategoryFilterOption {
   parentId
 }
 
+# Full result of the `availableFilters($input)` query — attribute filters, price range, category filters, count of currently active filters, total products matching the context. Spread on listing pages to render filter sidebars.
 fragment AvailableFilters on AvailableFilters {
   attributes {
     ...AttributeDefinition
@@ -1067,9 +1122,10 @@ fragment AvailableFilters on AvailableFilters {
 }
 
 # ============================================
-# Loyalty Program Fragments
+# Loyalty Program
 # ============================================
 
+# Page metadata for the loyalty transactions connection (separate type from generic `PageInfo` for legacy reasons; identical shape).
 fragment LoyaltyPageInfo on LoyaltyPageInfo {
   hasNextPage
   hasPreviousPage
@@ -1077,6 +1133,7 @@ fragment LoyaltyPageInfo on LoyaltyPageInfo {
   endCursor
 }
 
+# Loyalty tier definition — name, type enum (`BRONZE` / `SILVER` / `GOLD` / `PLATINUM` / `DIAMOND`), entry threshold (`minPoints` and/or `minAnnualSpend`), points multiplier, custom benefits list. Returned by `loyaltyTiers` and embedded in member tier data.
 fragment LoyaltyTier on LoyaltyTier {
   id
   name
@@ -1093,6 +1150,7 @@ fragment LoyaltyTier on LoyaltyTier {
   }
 }
 
+# Customer's points breakdown — total earned, currently spendable, pending (not yet vested), redeemed lifetime, expired lifetime, expiring soon, and the next expiry date. Spread inside `LoyaltyMember`.
 fragment LoyaltyPointsSummary on LoyaltyPointsSummary {
   totalPoints
   currentPoints
@@ -1103,6 +1161,7 @@ fragment LoyaltyPointsSummary on LoyaltyPointsSummary {
   nextExpiryDate
 }
 
+# Customer's progress toward the next tier — current tier, next tier, points + spend remaining, percent progress. Use to render the "X points to GOLD" tracker.
 fragment TierProgress on TierProgress {
   currentTier {
     ...LoyaltyTier
@@ -1117,6 +1176,7 @@ fragment TierProgress on TierProgress {
   }
 }
 
+# Customer's loyalty membership — points summary, current tier, tier progress, annual spend, last activity. Returned by `loyaltyMember` (null if not enrolled).
 fragment LoyaltyMember on LoyaltyMember {
   id
   customerId
@@ -1136,6 +1196,7 @@ fragment LoyaltyMember on LoyaltyMember {
   enrolledAt
 }
 
+# One row in the loyalty points history — type (`EARN_PURCHASE` / `EARN_SIGNUP` / `EARN_REFERRAL` / `EARN_REVIEW` / `EARN_BIRTHDAY` / `EARN_BONUS` / `REDEEM` / `EXPIRE` / `ADJUST` / `REFUND_REVERSAL`), points delta, balance after, source order, expiry. Spread on the loyalty dashboard transaction list.
 fragment LoyaltyTransaction on LoyaltyTransaction {
   id
   type
@@ -1147,6 +1208,7 @@ fragment LoyaltyTransaction on LoyaltyTransaction {
   createdAt
 }
 
+# Reward customers can redeem — name, type, points cost, discount value (% or fixed), tier requirement, availability flag, remaining redemptions. Spread on the rewards page.
 fragment LoyaltyReward on LoyaltyReward {
   id
   name
@@ -1168,6 +1230,7 @@ fragment LoyaltyReward on LoyaltyReward {
   redemptionsRemaining
 }
 
+# Estimated points for an order — base points, bonus points (tier multiplier applied), total, multiplier used. Returned by `estimatePoints($orderTotal)` for "Earn X points" UI on cart/checkout.
 fragment PointsEstimate on PointsEstimate {
   basePoints
   bonusPoints
@@ -1175,12 +1238,14 @@ fragment PointsEstimate on PointsEstimate {
   multiplier
 }
 
+# One earn action configured in the loyalty program — type (`PURCHASE` / `SIGNUP` / `REFERRAL` / `REVIEW` / `BIRTHDAY`), enabled flag, points granted.
 fragment LoyaltyAction on LoyaltyAction {
   type
   isEnabled
   points
 }
 
+# Loyalty program configuration — `isEnabled` (use to gate UI rendering), points name (e.g. "stars"), earn rate, expiry policy, available actions, referral settings. Returned by `loyaltySettings`.
 fragment LoyaltySettings on LoyaltySettings {
   isEnabled
   pointsName
@@ -1194,6 +1259,7 @@ fragment LoyaltySettings on LoyaltySettings {
   referralBonusPoints
 }
 
+# Customer referral statistics — code, share URL, counts of referred / completed / pending, lifetime points earned. Returned by `referralStats`.
 fragment ReferralStats on ReferralStats {
   referralCode
   shareUrl
@@ -1203,7 +1269,7 @@ fragment ReferralStats on ReferralStats {
   totalPointsEarned
 }
 
-# GAP-003: PRODUCT and GIFT_CARD Reward Types
+# Result of `redeemLoyaltyReward` — depending on the reward type, exactly one of `discountCode`, `productDiscountCode`, `giftCardCode` is populated. Apply the returned code on cart/checkout.
 fragment RedeemRewardPayload on RedeemRewardPayload {
   success
   discountCode
@@ -1212,6 +1278,7 @@ fragment RedeemRewardPayload on RedeemRewardPayload {
   userErrors
 }
 
+# Result of `generateReferralCode` — the customer's referral code and shareable URL.
 fragment GenerateReferralCodePayload on GenerateReferralCodePayload {
   success
   referralCode
@@ -1220,9 +1287,10 @@ fragment GenerateReferralCodePayload on GenerateReferralCodePayload {
 }
 
 # ============================================
-# Review Fragments
+# Reviews
 # ============================================
 
+# Single product review — rating, title, body, optional pros/cons, image attachments, author, verified-purchase flag, helpful/unhelpful counts, optional merchant response. Only `APPROVED` reviews are exposed to the storefront.
 fragment ProductReview on ProductReview {
   id
   productId
@@ -1241,6 +1309,7 @@ fragment ProductReview on ProductReview {
   createdAt
 }
 
+# Aggregate review stats for a product — average rating, total count, distribution per star (1-5). Returned by `reviewStats($productId)`.
 fragment ReviewStats on ReviewStats {
   averageRating
   totalCount
@@ -1252,9 +1321,10 @@ fragment ReviewStats on ReviewStats {
 }
 
 # ============================================
-# Wishlist Fragments
+# Wishlists
 # ============================================
 
+# One item in a wishlist — references the product and (optionally) a specific variant, snapshots the price at the time it was added, plus notification preferences (`notifyOnSale`, `notifyOnRestock`).
 fragment WishlistItem on WishlistItem {
   id
   productId
@@ -1270,6 +1340,7 @@ fragment WishlistItem on WishlistItem {
   addedAt
 }
 
+# A customer's wishlist — name, public/private flag, share token (when public), items, item count. Spread on the wishlists page.
 fragment Wishlist on Wishlist {
   id
   name
@@ -1284,9 +1355,10 @@ fragment Wishlist on Wishlist {
 }
 
 # ============================================
-# Blog Fragments
+# Blog
 # ============================================
 
+# Blog category — name, slug, description, post count. Spread on category navigation and post category labels.
 fragment BlogCategory on BlogCategory {
   id
   name
@@ -1295,6 +1367,7 @@ fragment BlogCategory on BlogCategory {
   postCount
 }
 
+# Blog tag — name, slug, post count. Spread on tag clouds and post tag labels.
 fragment BlogTag on BlogTag {
   id
   name
@@ -1302,6 +1375,7 @@ fragment BlogTag on BlogTag {
   postCount
 }
 
+# Full blog post — title, slug, excerpt, content (with `contentFormat` indicating HTML/Markdown), featured image, author, category, tags, publish date, reading time, view + comment counts, SEO metadata. Spread on the post detail page.
 fragment BlogPost on BlogPost {
   id
   title
@@ -1342,9 +1416,10 @@ fragment BlogPost on BlogPost {
 }
 
 # ============================================
-# Recommendation Fragments
+# Recommendations
 # ============================================
 
+# One recommended product — the product itself (card-level), recommendation type (e.g. SIMILAR / FREQUENTLY_BOUGHT_TOGETHER), score (0-100), human reason text. Spread on PDP "You may also like" sections.
 fragment ProductRecommendation on ProductRecommendation {
   product {
     ...ProductCard
@@ -1354,6 +1429,7 @@ fragment ProductRecommendation on ProductRecommendation {
   reason
 }
 
+# Recommendations bundle for the cart drawer — `frequentlyBoughtTogether` (cross-sell) and `youMayAlsoLike` (related). Each entry has the same shape as `ProductRecommendation`.
 fragment CartRecommendation on CartRecommendations {
   frequentlyBoughtTogether {
     product {
@@ -1374,14 +1450,15 @@ fragment CartRecommendation on CartRecommendations {
 }
 
 # ============================================
-# Store Availability Fragments (BOPIS / multi-location)
+# Store Availability (BOPIS / multi-location)
 # ============================================
-# Field access:
-# - `available: Boolean!` — always public.
-# - `pickupTime: String` — public, localized merchant-configured string.
-# - `quantityAvailable: Int` — TOKEN-GATED (null for anonymous, Int for authenticated).
-# - `location: Location!` — public, includes coords + businessHours when configured.
+# Field-access notes:
+# - `isAvailable` — always public.
+# - `pickupTime` — public, localized merchant-configured string.
+# - `availableStock` — token-gated (null for anonymous, integer for authenticated customers).
+# - `location` — public, includes coords + business hours when configured.
 
+# Physical location address — street, city, country, state, postal code, phone, lat/lng, formatted single-line representation. Spread inside `Location.address`.
 fragment LocationAddress on LocationAddress {
   streetLine1
   streetLine2
@@ -1397,11 +1474,13 @@ fragment LocationAddress on LocationAddress {
   formatted
 }
 
+# One day's open/close window inside `BusinessHours` (24h clock).
 fragment BusinessHoursWindow on BusinessHoursWindow {
   openHour
   closeHour
 }
 
+# Weekly business hours — one window per day. Spread inside `Location.businessHours`.
 fragment BusinessHours on BusinessHours {
   monday { ...BusinessHoursWindow }
   tuesday { ...BusinessHoursWindow }
@@ -1412,6 +1491,7 @@ fragment BusinessHours on BusinessHours {
   sunday { ...BusinessHoursWindow }
 }
 
+# Physical store / pickup location — name, type (RETAIL / WAREHOUSE / PICKUP_POINT), address, business hours, pickup support flag + instructions, timezone. Spread on the store picker and location detail pages.
 fragment Location on Location {
   id
   name
@@ -1427,6 +1507,7 @@ fragment Location on Location {
   }
 }
 
+# Per-location stock entry for one variant — availability flag, stock quantity (token-gated), pickup time, full location detail. Spread inside `StoreAvailabilityConnection.edges[].node`.
 fragment StoreAvailability on StoreAvailability {
   isAvailable
   availableStock
@@ -1436,6 +1517,7 @@ fragment StoreAvailability on StoreAvailability {
   }
 }
 
+# Relay connection of `StoreAvailability` entries for a variant — used inside the `VariantStoreAvailability` fragment. Pre-paginated to 10 by default.
 fragment StoreAvailabilityConnection on StoreAvailabilityConnection {
   totalCount
   pageInfo {
@@ -1449,6 +1531,7 @@ fragment StoreAvailabilityConnection on StoreAvailabilityConnection {
   }
 }
 
+# Slim variant projection optimized for the store-picker UI — id, title, sku, isAvailable, total `availableStock` plus per-location `storeAvailability` connection. Use in `productStoreAvailability` query.
 fragment VariantStoreAvailability on ProductVariant {
   id
   title
@@ -1461,9 +1544,10 @@ fragment VariantStoreAvailability on ProductVariant {
 }
 
 # ============================================
-# Content: Pages
+# Pages
 # ============================================
 
+# CMS page — handle (URL slug), title, body (HTML), excerpt, SEO metadata, publish date. Spread on About / Privacy / Terms / Returns Policy pages.
 fragment ShopPage on ShopPage {
   id
   handle
@@ -1480,9 +1564,10 @@ fragment ShopPage on ShopPage {
 }
 
 # ============================================
-# Content: Navigation Menus
+# Navigation Menus
 # ============================================
 
+# One menu item with up to 3 levels of nested children — title, URL, type (`HTTP` / `FRONTPAGE` / `SEARCH` / `CATALOG` / `BLOG` / `PRODUCT` / `COLLECTION` / `CATEGORY` / `PAGE`), `resourceId` for typed items, optional image. Switch on `type` to render the right link target.
 fragment MenuItem on MenuItem {
   id
   title
@@ -1508,6 +1593,7 @@ fragment MenuItem on MenuItem {
   }
 }
 
+# Navigation menu — handle (e.g. "main-menu", "footer", "mobile"), title, nested item tree. Returned by `menu($handle)` query.
 fragment Menu on Menu {
   id
   handle
@@ -1518,24 +1604,20 @@ fragment Menu on Menu {
 }
 
 # ============================================
-# Content: URL Redirects
+# URL Redirects
 # ============================================
 
+# Single legacy `path` → new `target` redirect entry. Use on the server / edge to issue 301 redirects for migrated routes.
 fragment UrlRedirect on UrlRedirect {
   path
   target
 }
 
 # ============================================
-# Unified Product Configurator (Faza 1 + Faza 1.5 — Decision D-A v3 + D-I)
+# Product Configurator (per-product attributes)
 # ============================================
-# Hybrid AttributeSet binding:
-#   - Product.attributes returns UNION of set definitions (via Product.attributeSetId)
-#     and per-product scoped definitions (AttributeDefinition.scopeProductId = product.id)
-#   - CUSTOMER fillingMode → rendered in storefront configurator UX
-#   - MERCHANT fillingMode → product metadata (filtering, display)
-#   - BOTH fillingMode → admin default + customer override in cart
 
+# Slim variant snapshot linked from a configurator option — when an attribute option (e.g. "256 GB" storage) maps to a specific variant, this fragment exposes that variant's id, title, sku, stock flags. Spread inside `ProductAttributeOption.linkedVariant`.
 fragment LinkedVariantSummary on LinkedVariantSummary {
   id
   productId
@@ -1546,6 +1628,7 @@ fragment LinkedVariantSummary on LinkedVariantSummary {
   trackQuantity
 }
 
+# One option (choice) within a configurator attribute — value, label, sort order, optional color hex, surcharge (amount + type), default flag, optional linked variant for variant-mapped options.
 fragment ProductAttributeOption on ProductAttributeOption {
   id
   value
@@ -1561,6 +1644,7 @@ fragment ProductAttributeOption on ProductAttributeOption {
   }
 }
 
+# Configurator attribute definition — name, type, fillingMode (CUSTOMER / MERCHANT / BOTH), billingMode, tax class, validation bounds, options (for choice-type attributes), required + visibility flags. Returned by `product.attributes(filter)` for the configurator UI.
 fragment ProductAttributeDefinition on ProductAttributeDefinition {
   id
   name