@doswiftly/storefront-operations 7.0.0 → 7.1.0

package/llms-full.txt

@@ -0,0 +1,4994 @@
+# DoSwiftly Storefront Operations — Full Reference
+
+> Schema version: **7.1.0**
+> 48 queries · 44 mutations · 108 fragments
+
+Auto-generated from `.graphql` source files. Do not edit by hand — this file is
+regenerated on every release to match the published schema.
+
+This file is the deep reference for AI agents and tools that need full operation
+signatures with descriptions, typed variables, and ready-to-execute GraphQL bodies.
+
+Companion files:
+- `AGENTS.md` — entry point with critical conventions and progressive disclosure
+- `schema.graphql` — full GraphQL schema (types, fields, enums)
+- `operations.json` — same operations as structured JSON for programmatic tools
+
+---
+
+## Queries
+
+### Query: `Shop`
+
+**Section**: Shop
+
+**Description**: Returns shop configuration: name, base + supported currencies, supported locales, branding (logo, colors, fonts, social links), contact info, active payment methods, brand metadata, money format template, and the list of countries the shop ships to. Public; no auth required. Call once per session and cache — almost everything else is contextualized by the shop returned here.
+
+**Variables**: none
+
+**Fragments used**: `Shop`
+
+**GraphQL**:
+```graphql
+query Shop {
+  shop {
+    ...Shop
+  }
+}
+```
+
+### Query: `Product`
+
+**Section**: Products
+
+**Description**: Fetches a single product by `id` or `handle` (URL slug). Pass either — whichever is provided wins; if both are missing, returns null. Returns null if the product is not storefront-accessible (must be `ACTIVE` status with `PUBLIC` or `BUNDLE_ONLY` visibility).
+
+**Variables**:
+- `$id`: `ID`
+- `$handle`: `String`
+
+**Fragments used**: `ProductFull`
+
+**GraphQL**:
+```graphql
+query Product($id: ID, $handle: String) {
+  product(id: $id, handle: $handle) {
+    ...ProductFull
+  }
+}
+```
+
+### Query: `ProductConfigurator`
+
+**Section**: Products
+
+**Description**: Fetches a product together with its filtered attribute definitions, optimized for the configurator UI (e.g. customer-facing text fields, finishing options, scoped variants). `fillingMode: "CUSTOMER"` returns only customer-facing attributes; pass `"BOTH"` to also include attributes shared with the merchant admin. Single round-trip — saves a separate `attributes` query.
+
+**Variables**:
+- `$handle`: `String!`
+- `$fillingMode`: `String` *(default: `"CUSTOMER"`)*
+
+**Fragments used**: `ProductAttributeDefinition`, `ProductFull`
+
+**GraphQL**:
+```graphql
+query ProductConfigurator($handle: String!, $fillingMode: String = "CUSTOMER") {
+  product(handle: $handle) {
+    ...ProductFull
+    attributes(filter: {fillingMode: $fillingMode}) {
+      ...ProductAttributeDefinition
+    }
+  }
+}
+```
+
+### Query: `Products`
+
+**Section**: Products
+
+**Description**: Paginated product list (Relay Connection, default page size 20, max 100). The `query` argument supports a structured search syntax — `tag:summer`, `vendor:foo`, `product_type:shirts`, `variants.price:>10`, plus `AND`/`OR`/`NOT` — falling back to free-text title/content search. The `filters[]` array uses multi-filter logic: same field name appears multiple times → OR; different fields → AND. Sort: `RELEVANCE`, `TITLE`, `PRICE`, `NEWEST`, `OLDEST`, `BEST_SELLING`. The response includes a `filters` block for faceted navigation (counts per filterable attribute value).
+
+**Variables**:
+- `$first`: `Int` *(default: `20`)*
+- `$after`: `String`
+- `$query`: `String`
+- `$sortKey`: `ProductSortKeys` *(default: `RELEVANCE`)*
+- `$reverse`: `Boolean` *(default: `false`)*
+- `$filters`: `[ProductFilter!]`
+
+**Fragments used**: `PageInfo`, `ProductCard`
+
+**GraphQL**:
+```graphql
+query Products($first: Int = 20, $after: String, $query: String, $sortKey: ProductSortKeys = RELEVANCE, $reverse: Boolean = false, $filters: [ProductFilter!]) {
+  products(
+    first: $first
+    after: $after
+    query: $query
+    sortKey: $sortKey
+    reverse: $reverse
+    filters: $filters
+  ) {
+    edges {
+      node {
+        ...ProductCard
+      }
+      cursor
+    }
+    nodes {
+      ...ProductCard
+    }
+    pageInfo {
+      ...PageInfo
+    }
+    totalCount
+  }
+}
+```
+
+### Query: `ProductSearch`
+
+**Section**: Products
+
+**Description**: Full-text product search — `$query` is required. Functionally equivalent to `Products` with `$query` set, minus the `sortKey` argument (search defaults to relevance ranking). Use for the search results page; combine with `filters[]` for guided refinement.
+
+**Variables**:
+- `$query`: `String!`
+- `$first`: `Int` *(default: `20`)*
+- `$after`: `String`
+- `$filters`: `[ProductFilter!]`
+
+**Fragments used**: `PageInfo`, `ProductCard`
+
+**GraphQL**:
+```graphql
+query ProductSearch($query: String!, $first: Int = 20, $after: String, $filters: [ProductFilter!]) {
+  products(query: $query, first: $first, after: $after, filters: $filters) {
+    edges {
+      node {
+        ...ProductCard
+      }
+      cursor
+    }
+    nodes {
+      ...ProductCard
+    }
+    pageInfo {
+      ...PageInfo
+    }
+    totalCount
+  }
+}
+```
+
+### Query: `PredictiveSearch`
+
+**Section**: Products
+
+**Description**: Type-ahead suggestions for the storefront search input. Returns up to `$limit` matching products (hard cap 50) plus up to 5 styled query suggestions with `<mark>` tags around matched spans. Polish-language aware (handles morphology in suggestions). Run on each keystroke (debounce 200-300ms). The `$query` is capped at 100 characters server-side.
+
+**Variables**:
+- `$query`: `String!`
+- `$limit`: `Int` *(default: `10`)*
+
+**Fragments used**: `ProductCard`
+
+**GraphQL**:
+```graphql
+query PredictiveSearch($query: String!, $limit: Int = 10) {
+  predictiveSearch(query: $query, limit: $limit) {
+    products {
+      ...ProductCard
+    }
+    queries {
+      text
+      styledText
+    }
+  }
+}
+```
+
+### Query: `Collection`
+
+**Section**: Collections
+
+**Description**: Fetches a single collection by `id` or `handle`, with paginated products. Collections come in two types: **MANUAL** (curated — products explicitly added by the merchant) and **AUTO** (rule-based — products matched dynamically). Both surfaces use the same field selection.
+
+**Variables**:
+- `$id`: `ID`
+- `$handle`: `String`
+- `$productsFirst`: `Int` *(default: `20`)*
+- `$productsAfter`: `String`
+- `$productsFilters`: `[ProductFilter!]`
+
+**Fragments used**: `Collection`, `PageInfo`, `ProductCard`
+
+**GraphQL**:
+```graphql
+query Collection($id: ID, $handle: String, $productsFirst: Int = 20, $productsAfter: String, $productsFilters: [ProductFilter!]) {
+  collection(id: $id, handle: $handle) {
+    ...Collection
+    products(
+      first: $productsFirst
+      after: $productsAfter
+      filters: $productsFilters
+    ) {
+      edges {
+        node {
+          ...ProductCard
+        }
+        cursor
+      }
+      nodes {
+        ...ProductCard
+      }
+      pageInfo {
+        ...PageInfo
+      }
+      totalCount
+    }
+  }
+}
+```
+
+### Query: `Collections`
+
+**Section**: Collections
+
+**Description**: Paginated list of all active collections (default 20, max 100). Sort by `TITLE` or `UPDATED_AT` via `sortKey`. Note: the `query` argument is reserved for future text filtering — it is currently accepted but ignored.
+
+**Variables**:
+- `$first`: `Int` *(default: `20`)*
+- `$after`: `String`
+- `$query`: `String`
+- `$sortKey`: `CollectionSortKeys` *(default: `TITLE`)*
+- `$reverse`: `Boolean` *(default: `false`)*
+
+**Fragments used**: `Collection`, `PageInfo`
+
+**GraphQL**:
+```graphql
+query Collections($first: Int = 20, $after: String, $query: String, $sortKey: CollectionSortKeys = TITLE, $reverse: Boolean = false) {
+  collections(
+    first: $first
+    after: $after
+    query: $query
+    sortKey: $sortKey
+    reverse: $reverse
+  ) {
+    edges {
+      node {
+        ...Collection
+      }
+      cursor
+    }
+    pageInfo {
+      ...PageInfo
+    }
+    totalCount
+  }
+}
+```
+
+### Query: `Category`
+
+**Section**: Categories
+
+**Description**: Fetches a single category by `id` or `slug` with its parent and immediate children. Use for breadcrumbs and sub-navigation. Nested queries on `parent` / `children` are batched server-side — safe to use in lists without N+1 concerns.
+
+**Variables**:
+- `$id`: `ID`
+- `$slug`: `String`
+
+**Fragments used**: `Category`
+
+**GraphQL**:
+```graphql
+query Category($id: ID, $slug: String) {
+  category(id: $id, slug: $slug) {
+    ...Category
+    parent {
+      ...Category
+    }
+    children {
+      ...Category
+    }
+  }
+}
+```
+
+### Query: `Categories`
+
+**Section**: Categories
+
+**Description**: Returns active categories for the shop. Each category exposes its `parent` and `children` — build the tree client-side by walking those fields (server batches the lookups, no N+1). The hierarchy is not depth-capped server-side. Use for nav mega-menus and category pages.
+
+**Variables**: none
+
+**Fragments used**: `Category`
+
+**GraphQL**:
+```graphql
+query Categories {
+  categories {
+    roots {
+      ...Category
+      children {
+        ...Category
+        children {
+          ...Category
+        }
+      }
+    }
+    totalCount
+  }
+}
+```
+
+### Query: `Cart`
+
+**Section**: Cart
+
+**Description**: Fetches a cart by `id` (the value persisted by the SDK in the `cart-id` cookie). The cart query is public — no auth needed to read it — but once a customer logs in and gets associated with the cart, mutations enforce ownership. Returns line items (paginated up to 100), totals, applied discount codes, gift cards, buyer identity, note, attributes, and warnings. Refetch after every cart mutation.
+
+**Variables**:
+- `$id`: `ID!`
+
+**Fragments used**: `Cart`
+
+**GraphQL**:
+```graphql
+query Cart($id: ID!) {
+  cart(id: $id) {
+    ...Cart
+  }
+}
+```
+
+### Query: `Customer`
+
+**Section**: Customer (requires auth)
+
+**Description**: Full customer profile — basic info plus the first 10 addresses and first 10 orders. Heaviest customer query; for narrow use cases prefer `CustomerProfile` (no orders / addresses) or `CustomerOrder` (single order). Returns null if unauthenticated.
+
+**Variables**: none
+
+**Fragments used**: `Customer`, `MailingAddress`, `Order`, `PageInfo`
+
+**GraphQL**:
+```graphql
+query Customer {
+  customer {
+    ...Customer
+    addresses(first: 10) {
+      edges {
+        cursor
+        node {
+          ...MailingAddress
+        }
+      }
+      nodes {
+        ...MailingAddress
+      }
+      pageInfo {
+        ...PageInfo
+      }
+      totalCount
+    }
+    orders(first: 10) {
+      edges {
+        node {
+          ...Order
+        }
+        cursor
+      }
+      pageInfo {
+        ...PageInfo
+      }
+      totalCount
+    }
+  }
+}
+```
+
+### Query: `CustomerProfile`
+
+**Section**: Customer (requires auth)
+
+**Description**: Lightweight customer profile (no orders, no addresses list). Use for settings / profile pages that only need basic customer info — much cheaper than `Customer`. Returns null if unauthenticated.
+
+**Variables**: none
+
+**Fragments used**: `Customer`
+
+**GraphQL**:
+```graphql
+query CustomerProfile {
+  customer {
+    ...Customer
+  }
+}
+```
+
+### Query: `CustomerOrder`
+
+**Section**: Customer (requires auth)
+
+**Description**: Single order by `orderId`. Returns only orders that belong to the authenticated customer (cross-customer access returns null, not an error). Much cheaper than fetching the full `Customer` payload to access one order. Use on the order detail page.
+
+**Variables**:
+- `$orderId`: `ID!`
+
+**Fragments used**: `Order`
+
+**GraphQL**:
+```graphql
+query CustomerOrder($orderId: ID!) {
+  customerOrder(orderId: $orderId) {
+    ...Order
+  }
+}
+```
+
+### Query: `Checkout`
+
+**Section**: Checkout
+
+**Description**: Fetches a checkout session by `id`. **Important**: `checkoutId` and `cartId` are 1:1 — there is no separate "checkout" record, the response is built dynamically from the cart. Returns line items, addresses, selected shipping rate, available shipping rates + payment methods, applied discount/gift cards (gift card codes are masked for security), and totals (`cost`, `tax`, `paymentDue`). Public read; ownership enforced on mutations. Refetch after every checkout mutation.
+
+**Variables**:
+- `$id`: `ID!`
+
+**Fragments used**: `Checkout`
+
+**GraphQL**:
+```graphql
+query Checkout($id: ID!) {
+  checkout(id: $id) {
+    ...Checkout
+  }
+}
+```
+
+### Query: `AvailablePaymentMethods`
+
+**Section**: Payment Methods
+
+**Description**: Returns the active payment methods for the shop, sorted by the merchant-configured display position. Shop-level — does NOT vary by cart amount or currency. Each method exposes `type` (`CARD`, `BANK_TRANSFER`, `BLIK`, `PAYPAL`, `APPLE_PAY`, `GOOGLE_PAY`, `CASH_ON_DELIVERY`, `OTHER`), provider, icon, description, and supported currencies. Use to render the payment step of checkout.
+
+**Variables**: none
+
+**Fragments used**: `AvailablePaymentMethods`
+
+**GraphQL**:
+```graphql
+query AvailablePaymentMethods {
+  availablePaymentMethods {
+    ...AvailablePaymentMethods
+  }
+}
+```
+
+### Query: `Shipment`
+
+**Section**: Shipments / Tracking
+
+**Description**: Fetches a shipment by `id` with status, tracking events, recipient address, and shipped/delivered timestamps. **Auth required** — customer access token plus ownership of the parent order. Wrapped response: `{ shipment, userErrors[] }`. Error codes: `INVALID_TOKEN`, `NOT_FOUND` (also returned on ownership mismatch to prevent enumeration), `FETCH_FAILED`.
+
+**Variables**:
+- `$id`: `ID!`
+
+**Fragments used**: `Shipment`, `UserError`
+
+**GraphQL**:
+```graphql
+query Shipment($id: ID!) {
+  shipment(id: $id) {
+    shipment {
+      ...Shipment
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Query: `ShipmentByTrackingNumber`
+
+**Section**: Shipments / Tracking
+
+**Description**: **Public** shipment lookup by carrier tracking number — no auth required. Designed for "Track my order" landing pages reachable without login. Returns the basic shipment fragment including recipient address. Wrapped response: `{ shipment, userErrors[] }`. Error codes: `INVALID_INPUT`, `NOT_FOUND`, `FETCH_FAILED`.
+
+**Variables**:
+- `$trackingNumber`: `String!`
+
+**Fragments used**: `ShipmentBasic`, `UserError`
+
+**GraphQL**:
+```graphql
+query ShipmentByTrackingNumber($trackingNumber: String!) {
+  shipmentByTrackingNumber(trackingNumber: $trackingNumber) {
+    shipment {
+      ...ShipmentBasic
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Query: `Return`
+
+**Section**: Returns / RMA
+
+**Description**: Fetches a single return (RMA) by `id` with line items, refund/compensation info, and history. **Auth required** — customer access token plus ownership of the return. Wrapped response: `{ return, userErrors[] }`. Error codes: `INVALID_TOKEN`, `NOT_FOUND` (also returned on ownership mismatch), `FETCH_FAILED`.
+
+**Variables**:
+- `$id`: `ID!`
+
+**Fragments used**: `Return`, `UserError`
+
+**GraphQL**:
+```graphql
+query Return($id: ID!) {
+  return(id: $id) {
+    return {
+      ...Return
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Query: `ReturnsByOrder`
+
+**Section**: Returns / RMA
+
+**Description**: Lists returns for a given order (paginated, default page size 20, cursor-based). **Auth required** — customer access token plus ownership of the order; the connection is empty (no explicit error) on auth failure. Use on the order detail page to show return history.
+
+**Variables**:
+- `$orderId`: `ID!`
+
+**Fragments used**: `PageInfo`, `Return`
+
+**GraphQL**:
+```graphql
+query ReturnsByOrder($orderId: ID!) {
+  returnsByOrder(orderId: $orderId) {
+    edges {
+      node {
+        ...Return
+      }
+      cursor
+    }
+    pageInfo {
+      ...PageInfo
+    }
+    totalCount
+  }
+}
+```
+
+### Query: `ReturnReasons`
+
+**Section**: Returns / RMA
+
+**Description**: Returns the standard list of return reasons used by the RMA flow: `DEFECTIVE`, `NOT_AS_DESCRIBED`, `WRONG_ITEM`, `CHANGED_MIND`, `BETTER_PRICE`, `DAMAGED_SHIPPING`, `OTHER`. The list is fixed across all shops — not per-shop configurable. Public; no auth required.
+
+**Variables**: none
+
+**Fragments used**: `ReturnReasonOption`
+
+**GraphQL**:
+```graphql
+query ReturnReasons {
+  returnReasons {
+    ...ReturnReasonOption
+  }
+}
+```
+
+### Query: `GiftCard`
+
+**Section**: Gift Cards
+
+**Description**: Public gift-card lookup by `code`. Returns balance, currency, expiry, and `maskedCode` (first 4 + last 4 chars only — the full code never leaks back). Returns null if the code is unknown (rather than an explicit error, to limit enumeration). **Rate-limited**: 10 requests per 60 seconds per IP.
+
+**Variables**:
+- `$code`: `String!`
+
+**Fragments used**: `GiftCard`
+
+**GraphQL**:
+```graphql
+query GiftCard($code: String!) {
+  giftCard(code: $code) {
+    ...GiftCard
+  }
+}
+```
+
+### Query: `GiftCardValidate`
+
+**Section**: Gift Cards
+
+**Description**: Validates whether a gift card is usable (and optionally for a given `$amount`). Checks status (`DISABLED`, `USED`, `EXPIRED`), expiry date, and — when `$amount` is provided — sufficient balance. Returns `{ validation: { isValid, availableBalance, error: { code, message } }, userErrors[] }`. Validation error codes: `NOT_FOUND`, `DISABLED`, `ALREADY_USED`, `EXPIRED`, `INSUFFICIENT_BALANCE`. **Rate-limited**: 10 / 60s.
+
+**Variables**:
+- `$code`: `String!`
+- `$amount`: `Float`
+
+**Fragments used**: `GiftCardValidation`, `UserError`
+
+**GraphQL**:
+```graphql
+query GiftCardValidate($code: String!, $amount: Float) {
+  giftCardValidate(code: $code, amount: $amount) {
+    validation {
+      ...GiftCardValidation
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Query: `AvailableShippingMethods`
+
+**Section**: Shipping Methods
+
+**Description**: Returns shipping methods for a given destination address and cart shape (subtotal, total weight, currency). The query computes everything from the inputs alone — no existing cart is required, so it can be used for "shipping cost preview" UIs before the customer adds anything to a cart. Each method includes price, free-shipping progress (`{ qualifies, currentAmount, threshold, remaining, progressPercent }`), estimated delivery, and carrier metadata. Sorted by the merchant's `sortOrder`, then by price.
+
+**Variables**:
+- `$address`: `ShippingAddressInput!`
+- `$cart`: `CartShippingInput`
+
+**Fragments used**: `AvailableShippingMethod`, `FreeShippingProgress`, `UserError`
+
+**GraphQL**:
+```graphql
+query AvailableShippingMethods($address: ShippingAddressInput!, $cart: CartShippingInput) {
+  availableShippingMethods(address: $address, cart: $cart) {
+    methods {
+      ...AvailableShippingMethod
+    }
+    freeShippingProgress {
+      ...FreeShippingProgress
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Query: `AvailableFilters`
+
+**Section**: Attribute Filters
+
+**Description**: Returns the dynamic facet filters available for a listing context — pass `collectionId`, `categoryId`, or `searchQuery`. For each visible & filterable attribute, returns either discrete value counts (for `SELECT` / `CHECKBOX` types) or numeric range bounds (for `SLIDER` types). Plus `priceRange`, per-category counts, `activeCount` (length of `currentFilters` input), and `matchCount` (total products in the context). Use to render filter sidebars on listing/search pages.
+
+**Variables**:
+- `$input`: `AvailableFiltersInput`
+
+**Fragments used**: `AvailableFilters`
+
+**GraphQL**:
+```graphql
+query AvailableFilters($input: AvailableFiltersInput) {
+  availableFilters(input: $input) {
+    ...AvailableFilters
+  }
+}
+```
+
+### Query: `LoyaltyMember`
+
+**Section**: Loyalty Program
+
+**Description**: Returns the logged-in customer's loyalty membership: points (current, pending, redeemed, expired, expiring), current tier, tier progress, annual spend, last activity. Returns null if the customer is not enrolled — there is **no auto-enrollment** here (enrollment happens via signup or a first qualifying order). Auth required.
+
+**Variables**: none
+
+**Fragments used**: `LoyaltyMember`
+
+**GraphQL**:
+```graphql
+query LoyaltyMember {
+  loyaltyMember {
+    ...LoyaltyMember
+  }
+}
+```
+
+### Query: `LoyaltyTiers`
+
+**Section**: Loyalty Program
+
+**Description**: Lists the loyalty tiers configured for the shop (`BRONZE`, `SILVER`, `GOLD`, `PLATINUM`, `DIAMOND` etc.) with their `minPoints`, `minAnnualSpend`, `pointsMultiplier`, and custom benefits. Sorted by `minPoints` ASC. Public; no auth required.
+
+**Variables**: none
+
+**Fragments used**: `LoyaltyTier`
+
+**GraphQL**:
+```graphql
+query LoyaltyTiers {
+  loyaltyTiers {
+    ...LoyaltyTier
+  }
+}
+```
+
+### Query: `LoyaltyRewards`
+
+**Section**: Loyalty Program
+
+**Description**: Lists rewards customers can redeem (free shipping, percent off, free product, gift card). Filtered to **active** rewards only (`is_active = true` AND inside their `starts_at`/`ends_at` window). Public; no auth required.
+
+**Variables**: none
+
+**Fragments used**: `LoyaltyReward`
+
+**GraphQL**:
+```graphql
+query LoyaltyRewards {
+  loyaltyRewards {
+    ...LoyaltyReward
+  }
+}
+```
+
+### Query: `LoyaltyTransactions`
+
+**Section**: Loyalty Program
+
+**Description**: Paginated history of loyalty point transactions for the logged-in customer (default 20). Transaction `type` enum: `EARN_PURCHASE`, `EARN_SIGNUP`, `EARN_REFERRAL`, `EARN_REVIEW`, `EARN_BIRTHDAY`, `EARN_BONUS`, `REDEEM`, `EXPIRE`, `ADJUST`, `REFUND_REVERSAL`. Auth required — empty connection if unauthenticated.
+
+**Variables**:
+- `$first`: `Int` *(default: `20`)*
+- `$after`: `String`
+
+**Fragments used**: `LoyaltyPageInfo`, `LoyaltyTransaction`
+
+**GraphQL**:
+```graphql
+query LoyaltyTransactions($first: Int = 20, $after: String) {
+  loyaltyTransactions(first: $first, after: $after) {
+    edges {
+      node {
+        ...LoyaltyTransaction
+      }
+      cursor
+    }
+    pageInfo {
+      ...LoyaltyPageInfo
+    }
+    totalCount
+  }
+}
+```
+
+### Query: `LoyaltySettings`
+
+**Section**: Loyalty Program
+
+**Description**: Returns the loyalty program configuration: `isEnabled`, `pointsName` (e.g. "stars"), `pointsPerCurrency`, `pointsExpiryMonths`, available earn actions, referral settings. Use this at app boot to decide whether to render any loyalty UI at all. Public; no auth required.
+
+**Variables**: none
+
+**Fragments used**: `LoyaltySettings`
+
+**GraphQL**:
+```graphql
+query LoyaltySettings {
+  loyaltySettings {
+    ...LoyaltySettings
+  }
+}
+```
+
+### Query: `EstimatePoints`
+
+**Section**: Loyalty Program
+
+**Description**: Estimates how many loyalty points the customer would earn for an order of `$orderTotal` (in major currency units). When the customer is authenticated, the result accounts for their current tier's points multiplier. Use on cart/checkout to show "Earn X points with this order".
+
+**Variables**:
+- `$orderTotal`: `Float!`
+
+**Fragments used**: `PointsEstimate`
+
+**GraphQL**:
+```graphql
+query EstimatePoints($orderTotal: Float!) {
+  estimatePoints(orderTotal: $orderTotal) {
+    ...PointsEstimate
+  }
+}
+```
+
+### Query: `ReferralStats`
+
+**Section**: Loyalty Program
+
+**Description**: Returns the customer's referral statistics: `referralCode`, `shareUrl`, `totalReferred`, `completedReferrals`, `pendingReferrals`, `totalPointsEarned`. Auth required. Returns null if unauthenticated or if the referral program is disabled for the shop.
+
+**Variables**: none
+
+**Fragments used**: `ReferralStats`
+
+**GraphQL**:
+```graphql
+query ReferralStats {
+  referralStats {
+    ...ReferralStats
+  }
+}
+```
+
+### Query: `ProductReviews`
+
+**Section**: Reviews
+
+**Description**: Paginated list of customer reviews for a product, **filtered to APPROVED reviews only** (PENDING / REJECTED reviews are not exposed to the storefront). Sort by `CREATED_AT` (default), helpfulness, or rating. Public; no auth required.
+
+**Variables**:
+- `$productId`: `ID!`
+- `$first`: `Int` *(default: `10`)*
+- `$after`: `String`
+- `$sortKey`: `ReviewSortKey` *(default: `CREATED_AT`)*
+- `$reverse`: `Boolean` *(default: `true`)*
+
+**Fragments used**: `PageInfo`, `ProductReview`
+
+**GraphQL**:
+```graphql
+query ProductReviews($productId: ID!, $first: Int = 10, $after: String, $sortKey: ReviewSortKey = CREATED_AT, $reverse: Boolean = true) {
+  productReviews(
+    productId: $productId
+    first: $first
+    after: $after
+    sortKey: $sortKey
+    reverse: $reverse
+  ) {
+    edges {
+      node {
+        ...ProductReview
+      }
+      cursor
+    }
+    pageInfo {
+      ...PageInfo
+    }
+    totalCount
+  }
+}
+```
+
+### Query: `ReviewStats`
+
+**Section**: Reviews
+
+**Description**: Aggregate review statistics for a product: average rating, total count, distribution per star (1-5). Computed from APPROVED reviews only. Use for product card review summaries. Public; no auth required.
+
+**Variables**:
+- `$productId`: `ID!`
+
+**Fragments used**: `ReviewStats`
+
+**GraphQL**:
+```graphql
+query ReviewStats($productId: ID!) {
+  reviewStats(productId: $productId) {
+    ...ReviewStats
+  }
+}
+```
+
+### Query: `Wishlists`
+
+**Section**: Wishlists
+
+**Description**: Paginated list of the logged-in customer's wishlists (default 20). Auth required — empty connection if unauthenticated. Customers typically have a small set (<10).
+
+**Variables**:
+- `$first`: `Int` *(default: `20`)*
+- `$after`: `String`
+
+**Fragments used**: `Wishlist`
+
+**GraphQL**:
+```graphql
+query Wishlists($first: Int = 20, $after: String) {
+  wishlists(first: $first, after: $after) {
+    edges {
+      cursor
+      node {
+        ...Wishlist
+      }
+    }
+    nodes {
+      ...Wishlist
+    }
+    pageInfo {
+      hasNextPage
+      hasPreviousPage
+      startCursor
+      endCursor
+    }
+    totalCount
+  }
+}
+```
+
+### Query: `WishlistById`
+
+**Section**: Wishlists
+
+**Description**: Fetches a single wishlist by `id`. Private wishlists are visible only to the owner; public wishlists are visible to anyone. Note: this query supports lookup by `id` only — there is currently no way to fetch a wishlist by its share token.
+
+**Variables**:
+- `$id`: `ID!`
+
+**Fragments used**: `Wishlist`
+
+**GraphQL**:
+```graphql
+query WishlistById($id: ID!) {
+  wishlist(id: $id) {
+    ...Wishlist
+  }
+}
+```
+
+### Query: `BlogPosts`
+
+**Section**: Blog
+
+**Description**: Paginated list of published blog posts. Filter by `categorySlug`, `tagSlug`, or `featured` (boolean flag, not enum). Sort: `PUBLISHED_AT` (default), `TITLE`, `VIEW_COUNT`, or `CREATED_AT`. Public; no auth required.
+
+**Variables**:
+- `$first`: `Int` *(default: `20`)*
+- `$after`: `String`
+- `$categorySlug`: `String`
+- `$tagSlug`: `String`
+- `$featured`: `Boolean`
+- `$sortKey`: `BlogPostSortKey` *(default: `PUBLISHED_AT`)*
+- `$reverse`: `Boolean` *(default: `false`)*
+
+**Fragments used**: `BlogPost`, `PageInfo`
+
+**GraphQL**:
+```graphql
+query BlogPosts($first: Int = 20, $after: String, $categorySlug: String, $tagSlug: String, $featured: Boolean, $sortKey: BlogPostSortKey = PUBLISHED_AT, $reverse: Boolean = false) {
+  blogPosts(
+    first: $first
+    after: $after
+    categorySlug: $categorySlug
+    tagSlug: $tagSlug
+    featured: $featured
+    sortKey: $sortKey
+    reverse: $reverse
+  ) {
+    edges {
+      node {
+        ...BlogPost
+      }
+      cursor
+    }
+    pageInfo {
+      ...PageInfo
+    }
+    totalCount
+  }
+}
+```
+
+### Query: `BlogPost`
+
+**Section**: Blog
+
+**Description**: Fetches a single blog post by `id` or `slug`. Visibility-gated: returns null if the post is not yet `PUBLISHED` or if its publish date is in the future (scheduled posts stay hidden until their publish time). Side effect: fetching a post increments its `view_count` asynchronously (does not block the response).
+
+**Variables**:
+- `$id`: `ID`
+- `$slug`: `String`
+
+**Fragments used**: `BlogPost`
+
+**GraphQL**:
+```graphql
+query BlogPost($id: ID, $slug: String) {
+  blogPost(id: $id, slug: $slug) {
+    ...BlogPost
+  }
+}
+```
+
+### Query: `BlogCategories`
+
+**Section**: Blog
+
+**Description**: Lists all blog categories with per-category `postCount` and SEO metadata. Use to render category navigation on blog pages. Public; no auth required.
+
+**Variables**: none
+
+**Fragments used**: `BlogCategory`
+
+**GraphQL**:
+```graphql
+query BlogCategories {
+  blogCategories {
+    ...BlogCategory
+  }
+}
+```
+
+### Query: `BlogTags`
+
+**Section**: Blog
+
+**Description**: Lists blog tags with usage counts (`postCount` per tag). Use to render a tag cloud. Public; no auth required.
+
+**Variables**: none
+
+**Fragments used**: `BlogTag`
+
+**GraphQL**:
+```graphql
+query BlogTags {
+  blogTags {
+    ...BlogTag
+  }
+}
+```
+
+### Query: `ProductRecommendations`
+
+**Section**: Recommendations
+
+**Description**: Returns up to `$limit` recommended products related to `$productId`. Default `$intent: SIMILAR` — products sharing categories or tags. Use on PDP "You may also like" sections. Public; no auth required.
+
+**Variables**:
+- `$productId`: `ID!`
+- `$limit`: `Int` *(default: `8`)*
+- `$intent`: `RecommendationIntent` *(default: `SIMILAR`)*
+
+**Fragments used**: `ProductCard`
+
+**GraphQL**:
+```graphql
+query ProductRecommendations($productId: ID!, $limit: Int = 8, $intent: RecommendationIntent = SIMILAR) {
+  productRecommendations(productId: $productId, limit: $limit, intent: $intent) {
+    ...ProductCard
+  }
+}
+```
+
+### Query: `Page`
+
+**Section**: Content: Pages
+
+**Description**: Fetches a single CMS page (About, Privacy, Returns Policy, Terms, etc.) by `handle` or `id`. Visibility-gated: returns null if the page is hidden or if its publish date is in the future. Public; no auth required.
+
+**Variables**:
+- `$handle`: `String`
+- `$id`: `ID`
+
+**Fragments used**: `ShopPage`
+
+**GraphQL**:
+```graphql
+query Page($handle: String, $id: ID) {
+  page(handle: $handle, id: $id) {
+    ...ShopPage
+  }
+}
+```
+
+### Query: `Pages`
+
+**Section**: Content: Pages
+
+**Description**: Paginated list of visible, already-published CMS pages. Use for sitemap, footer link list, or page directory. The `query` argument supports text search over the page title/handle. Public; no auth required.
+
+**Variables**:
+- `$first`: `Int` *(default: `20`)*
+- `$after`: `String`
+- `$sortKey`: `PageSortKeys` *(default: `TITLE`)*
+- `$reverse`: `Boolean` *(default: `false`)*
+- `$query`: `String`
+
+**Fragments used**: `PageInfo`, `ShopPage`
+
+**GraphQL**:
+```graphql
+query Pages($first: Int = 20, $after: String, $sortKey: PageSortKeys = TITLE, $reverse: Boolean = false, $query: String) {
+  pages(
+    first: $first
+    after: $after
+    sortKey: $sortKey
+    reverse: $reverse
+    query: $query
+  ) {
+    edges {
+      node {
+        ...ShopPage
+      }
+      cursor
+    }
+    pageInfo {
+      ...PageInfo
+    }
+    totalCount
+  }
+}
+```
+
+### Query: `Menu`
+
+**Section**: Content: Navigation Menus
+
+**Description**: Fetches a navigation menu by `handle` (e.g. `"main-menu"`, `"footer"`, `"mobile"`). Returns the nested item tree. Each item is typed as one of: `HTTP`, `FRONTPAGE`, `SEARCH`, `CATALOG`, `BLOG`, `PRODUCT`, `COLLECTION`, `CATEGORY`, or `PAGE` — switch on the type to render the right link target. Linked resources and URLs are resolved on demand by the field selections in the `Menu` fragment.
+
+**Variables**:
+- `$handle`: `String!`
+
+**Fragments used**: `Menu`
+
+**GraphQL**:
+```graphql
+query Menu($handle: String!) {
+  menu(handle: $handle) {
+    ...Menu
+  }
+}
+```
+
+### Query: `UrlRedirects`
+
+**Section**: Content: URL Redirects
+
+**Description**: Returns the shop's URL redirects (legacy `path` → new `target` mappings). Use server-side at the edge or in SSR to issue 301 redirects for migrated routes (preserves SEO equity). Default page size 250 — most shops fit in a single page.
+
+**Variables**:
+- `$first`: `Int` *(default: `250`)*
+- `$after`: `String`
+
+**Fragments used**: `PageInfo`, `UrlRedirect`
+
+**GraphQL**:
+```graphql
+query UrlRedirects($first: Int = 250, $after: String) {
+  urlRedirects(first: $first, after: $after) {
+    nodes {
+      ...UrlRedirect
+    }
+    pageInfo {
+      ...PageInfo
+    }
+  }
+}
+```
+
+### Query: `ProductStoreAvailability`
+
+**Section**: Store Availability: per-location stock (BOPIS / multi-location)
+
+**Description**: Fetches a product (by `handle` or `id`) along with per-variant availability across the merchant's physical locations — for the BOPIS / multi-location flow. The `storeAvailability` connection lives on each `ProductVariant`; its arguments (`first`, `after`, `near`, `locationType`) are set inside the `VariantStoreAvailability` fragment. The connection returns null for single-location shops (in which case the storefront can skip the store picker entirely). `availableStock` is null for anonymous users and an integer for authenticated customers. Apply `@inContext(preferredLocationId: ...)` on the operation to pin the customer's preferred location to the top of the result.
+
+**Variables**:
+- `$handle`: `String`
+- `$id`: `ID`
+
+**Fragments used**: `VariantStoreAvailability`
+
+**GraphQL**:
+```graphql
+query ProductStoreAvailability($handle: String, $id: ID) {
+  product(handle: $handle, id: $id) {
+    id
+    handle
+    title
+    variants {
+      ...VariantStoreAvailability
+    }
+  }
+}
+```
+
+### Query: `Locations`
+
+**Section**: Locations (store picker UI)
+
+**Description**: Paginated list of active store locations (default 20, max 100). Filters: `near` (`{ latitude, longitude }`) for proximity search — sorts ascending by distance; `hasPickupEnabled` for pickup-only filtering; `locationType` (`RETAIL`, `WAREHOUSE`, `PICKUP_POINT`). When `near` is omitted, results are sorted by the merchant's `priority`, then name. Use for the BOPIS store picker UI. Public; no auth required.
+
+**Variables**:
+- `$first`: `Int` *(default: `20`)*
+- `$after`: `String`
+- `$near`: `GeoCoordinateInput`
+- `$hasPickupEnabled`: `Boolean`
+- `$locationType`: `LocationType`
+
+**Fragments used**: `Location`, `PageInfo`
+
+**GraphQL**:
+```graphql
+query Locations($first: Int = 20, $after: String, $near: GeoCoordinateInput, $hasPickupEnabled: Boolean, $locationType: LocationType) {
+  locations(
+    first: $first
+    after: $after
+    near: $near
+    hasPickupEnabled: $hasPickupEnabled
+    locationType: $locationType
+  ) {
+    totalCount
+    pageInfo {
+      ...PageInfo
+    }
+    edges {
+      cursor
+      node {
+        ...Location
+      }
+    }
+  }
+}
+```
+
+### Query: `Location`
+
+**Section**: Locations (store picker UI)
+
+**Description**: Fetches a single store location by `id` — full address, coordinates, business hours, pickup config (lead time, hours, timezone), and services. Returns null if the location is not found, not active, or owned by another shop. Use on the location detail page. Public; no auth required.
+
+**Variables**:
+- `$id`: `ID!`
+
+**Fragments used**: `Location`
+
+**GraphQL**:
+```graphql
+query Location($id: ID!) {
+  location(id: $id) {
+    ...Location
+  }
+}
+```
+
+---
+
+## Mutations
+
+### Mutation: `CartCreate`
+
+**Section**: Cart Mutations
+
+**Description**: Creates a new cart and optionally pre-populates it with line items. Cart ID is a UUID stored by the SDK in the `cart-id` cookie (30-day TTL); the cart itself expires server-side after 72 hours of inactivity. The `warnings` field is reserved for non-blocking issues — current implementation returns it empty in this path.
+
+**Variables**:
+- `$input`: `CartCreateInput`
+
+**Fragments used**: `Cart`, `CartWarning`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CartCreate($input: CartCreateInput) {
+  cartCreate(input: $input) {
+    cart {
+      ...Cart
+    }
+    userErrors {
+      ...UserError
+    }
+    warnings {
+      ...CartWarning
+    }
+  }
+}
+```
+
+### Mutation: `CartAddLines`
+
+**Section**: Cart Mutations
+
+**Description**: Adds line items to a cart. Each line is `{ merchandiseId, quantity, attributes?, attributeSelections? }`. If the same variant + identical attributes are added twice, quantities merge into one row instead of duplicating. Validates stock (`INSUFFICIENT_STOCK`) and configurator attributes (`ATTRIBUTE_REQUIRED`, `ATTRIBUTE_OPTION_INVALID`). Triggers cart re-pricing including discount recalculation.
+
+**Variables**:
+- `$id`: `ID!`
+- `$lines`: `[CartLineInput!]!`
+
+**Fragments used**: `Cart`, `CartWarning`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CartAddLines($id: ID!, $lines: [CartLineInput!]!) {
+  cartAddLines(id: $id, lines: $lines) {
+    cart {
+      ...Cart
+    }
+    userErrors {
+      ...UserError
+    }
+    warnings {
+      ...CartWarning
+    }
+  }
+}
+```
+
+### Mutation: `CartUpdateLines`
+
+**Section**: Cart Mutations
+
+**Description**: Updates quantity and/or attributes of existing cart lines by `id`. Setting `quantity: 0` auto-deletes the line. Passing `attributes: []` clears them; omitting the field preserves existing values. Re-validates stock and re-prices the cart after each update.
+
+**Variables**:
+- `$id`: `ID!`
+- `$lines`: `[CartLineUpdateInput!]!`
+
+**Fragments used**: `Cart`, `CartWarning`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CartUpdateLines($id: ID!, $lines: [CartLineUpdateInput!]!) {
+  cartUpdateLines(id: $id, lines: $lines) {
+    cart {
+      ...Cart
+    }
+    userErrors {
+      ...UserError
+    }
+    warnings {
+      ...CartWarning
+    }
+  }
+}
+```
+
+### Mutation: `CartRemoveLines`
+
+**Section**: Cart Mutations
+
+**Description**: Removes specific lines from cart by `lineIds[]`. Internally delegates to `cartUpdateLines` with `quantity: 0` — both endpoints are functionally equivalent; this one exists for API ergonomics when intent is explicit removal. Triggers cart re-pricing.
+
+**Variables**:
+- `$id`: `ID!`
+- `$lineIds`: `[ID!]!`
+
+**Fragments used**: `Cart`, `CartWarning`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CartRemoveLines($id: ID!, $lineIds: [ID!]!) {
+  cartRemoveLines(id: $id, lineIds: $lineIds) {
+    cart {
+      ...Cart
+    }
+    userErrors {
+      ...UserError
+    }
+    warnings {
+      ...CartWarning
+    }
+  }
+}
+```
+
+### Mutation: `CartApplyDiscountCodes`
+
+**Section**: Cart Mutations
+
+**Description**: Replaces (NOT appends) the cart's discount codes with the given list. Pass `[]` to clear all codes. Each code is validated against `discounts` table (existence, active status); invalid codes appear in `userErrors[]` as `DISCOUNT_CODE_INVALID`. Triggers cart re-pricing — discount allocations are recomputed and stored in `cart.discountAmount`.
+
+**Variables**:
+- `$id`: `ID!`
+- `$discountCodes`: `[String!]!`
+
+**Fragments used**: `Cart`, `CartWarning`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CartApplyDiscountCodes($id: ID!, $discountCodes: [String!]!) {
+  cartApplyDiscountCodes(id: $id, discountCodes: $discountCodes) {
+    cart {
+      ...Cart
+    }
+    userErrors {
+      ...UserError
+    }
+    warnings {
+      ...CartWarning
+    }
+  }
+}
+```
+
+### Mutation: `CartUpdateBuyerIdentity`
+
+**Section**: Cart Mutations
+
+**Description**: Associates a customer with the cart. Despite the input shape accepting `email`, `phone`, `countryCode`, `languageCode`, only `customerId` is currently persisted — other fields are silently ignored. Does NOT trigger tax / shipping recalculation; pure cart-to-customer linking. Use during login or guest-to-account upgrade.
+
+**Variables**:
+- `$id`: `ID!`
+- `$buyerIdentity`: `CartBuyerIdentityInput!`
+
+**Fragments used**: `Cart`, `CartWarning`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CartUpdateBuyerIdentity($id: ID!, $buyerIdentity: CartBuyerIdentityInput!) {
+  cartUpdateBuyerIdentity(id: $id, buyerIdentity: $buyerIdentity) {
+    cart {
+      ...Cart
+    }
+    userErrors {
+      ...UserError
+    }
+    warnings {
+      ...CartWarning
+    }
+  }
+}
+```
+
+### Mutation: `CartUpdateNote`
+
+**Section**: Cart Mutations
+
+**Description**: Sets a free-text note on the cart (gift message, special instructions). Pass empty string to clear. Stored on the `Cart` row, propagated to the `Order` at checkout completion, visible to merchant in admin.
+
+**Variables**:
+- `$id`: `ID!`
+- `$note`: `String!`
+
+**Fragments used**: `Cart`, `CartWarning`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CartUpdateNote($id: ID!, $note: String!) {
+  cartUpdateNote(id: $id, note: $note) {
+    cart {
+      ...Cart
+    }
+    userErrors {
+      ...UserError
+    }
+    warnings {
+      ...CartWarning
+    }
+  }
+}
+```
+
+### Mutation: `CustomerSignup`
+
+**Section**: Customer Auth Mutations
+
+**Description**: Registers a new customer. Returns `customerAccessToken` immediately — the customer record is created with status `ACTIVE` (no pending state). The activation email containing `customerActivate` token is sent for `emailVerified=true` confirmation, but is NOT required for login. Cookie: `customerAccessToken`, 30-day max-age, httpOnly. JWT TTL: 24h. Bot-protection guarded.
+
+**Variables**:
+- `$input`: `CustomerCreateInput!`
+
+**Fragments used**: `Customer`, `CustomerAccessToken`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CustomerSignup($input: CustomerCreateInput!) {
+  customerSignup(input: $input) {
+    customer {
+      ...Customer
+    }
+    customerAccessToken {
+      ...CustomerAccessToken
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CustomerLogin`
+
+**Section**: Customer Auth Mutations
+
+**Description**: Logs in with email + password. JWT lifetime 24h; cookie max-age 30d (cookie outlives JWT — call `customerRefreshToken` before JWT expiry to extend session). Brute-force protected: 10 failed attempts per email = 15-min Redis-backed lockout. Failed attempts are recorded for non-existent emails too (timing-attack safe).
+
+**Variables**:
+- `$input`: `CustomerAccessTokenCreateInput!`
+
+**Fragments used**: `CustomerAccessToken`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CustomerLogin($input: CustomerAccessTokenCreateInput!) {
+  customerLogin(input: $input) {
+    customerAccessToken {
+      ...CustomerAccessToken
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CustomerLogout`
+
+**Section**: Customer Auth Mutations
+
+**Description**: Clears the `customerAccessToken` cookie. Note: the JWT itself is NOT server-side invalidated — it remains valid until its 24h expiry. Server-side token revocation is on the roadmap. Idempotent.
+
+**Variables**: none
+
+**Fragments used**: `UserError`
+
+**GraphQL**:
+```graphql
+mutation CustomerLogout {
+  customerLogout {
+    deletedAccessToken
+    deletedCustomerAccessTokenId
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CustomerRefreshToken`
+
+**Section**: Customer Auth Mutations
+
+**Description**: Issues a fresh JWT (24h TTL) for the currently-authenticated customer. Reads identity from the current cookie/Bearer token; takes no input. Use proactively before JWT expiry or reactively on a 401 retry. The new token replaces the cookie value.
+
+**Variables**: none
+
+**Fragments used**: `CustomerAccessToken`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CustomerRefreshToken {
+  customerRefreshToken {
+    customerAccessToken {
+      ...CustomerAccessToken
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CustomerUpdate`
+
+**Section**: Customer Profile Mutations
+
+**Description**: Updates the logged-in customer's profile. Supported fields include `firstName`, `lastName`, `phone`, marketing preferences, and B2B identity (`customerType`, `companyName`, `taxId`, `vatNumber`, `regon`). Concurrent updates from the storefront and the merchant admin are reconciled safely — the loser of a race retries against the latest version. Marketing consent changes are recorded separately for audit purposes.
+
+**Variables**:
+- `$customer`: `CustomerUpdateInput!`
+
+**Fragments used**: `Customer`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CustomerUpdate($customer: CustomerUpdateInput!) {
+  customerUpdate(customer: $customer) {
+    customer {
+      ...Customer
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CustomerAddAddress`
+
+**Section**: Customer Address Mutations
+
+**Description**: Adds a new mailing address. If `isDefaultShipping` or `isDefaultBilling` is `true` in the input, the new address is set as default and any other address for this customer holding that flag is atomically cleared in the same transaction.
+
+**Variables**:
+- `$address`: `MailingAddressInput!`
+
+**Fragments used**: `MailingAddress`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CustomerAddAddress($address: MailingAddressInput!) {
+  customerAddAddress(address: $address) {
+    address {
+      ...MailingAddress
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CustomerUpdateAddress`
+
+**Section**: Customer Address Mutations
+
+**Description**: Updates an existing address owned by the logged-in customer. If `isDefaultShipping` or `isDefaultBilling` toggles to `true`, default flag is atomically cleared on all other addresses for this customer.
+
+**Variables**:
+- `$id`: `ID!`
+- `$address`: `MailingAddressInput!`
+
+**Fragments used**: `MailingAddress`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CustomerUpdateAddress($id: ID!, $address: MailingAddressInput!) {
+  customerUpdateAddress(id: $id, address: $address) {
+    address {
+      ...MailingAddress
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CustomerRemoveAddress`
+
+**Section**: Customer Address Mutations
+
+**Description**: Hard-deletes an address row from `customer_addresses`. Historical orders that referenced this address are unaffected (address is snapshotted into the order at checkout completion).
+
+**Variables**:
+- `$id`: `ID!`
+
+**Fragments used**: `UserError`
+
+**GraphQL**:
+```graphql
+mutation CustomerRemoveAddress($id: ID!) {
+  customerRemoveAddress(id: $id) {
+    deletedAddressId
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CustomerSetDefaultAddress`
+
+**Section**: Customer Address Mutations
+
+**Description**: Marks the given address as the customer's default **shipping** address. Atomically clears the shipping-default flag from all other addresses. Note: there is no separate setter for default billing — set `isDefaultBilling: true` via `customerAddAddress` / `customerUpdateAddress` instead.
+
+**Variables**:
+- `$addressId`: `ID!`
+
+**Fragments used**: `Customer`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CustomerSetDefaultAddress($addressId: ID!) {
+  customerSetDefaultAddress(addressId: $addressId) {
+    customer {
+      ...Customer
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CustomerRequestPasswordReset`
+
+**Section**: Customer Password Mutations
+
+**Description**: Sends a password reset email. Always returns success regardless of whether the email exists (no account enumeration). The email is dispatched asynchronously, so a small delay between request and inbox arrival is normal. Rate-limited to 3 requests per 10 minutes.
+
+**Variables**:
+- `$email`: `String!`
+
+**Fragments used**: `UserError`
+
+**GraphQL**:
+```graphql
+mutation CustomerRequestPasswordReset($email: String!) {
+  customerRequestPasswordReset(email: $email) {
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CustomerActivate`
+
+**Section**: Customer Password Mutations
+
+**Description**: Activates a newly-created account using the 64-hex activation token from the welcome email + a chosen password. Token TTL is 24h, single-use (atomically marked `used_at`). On success: sets `email_verified=true`, transitions status `INACTIVE`→`ACTIVE`, returns a fresh JWT for auto-login. Rate-limited.
+
+**Variables**:
+- `$token`: `String!`
+- `$password`: `String!`
+
+**Fragments used**: `Customer`, `CustomerAccessToken`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CustomerActivate($token: String!, $password: String!) {
+  customerActivate(token: $token, password: $password) {
+    customer {
+      ...Customer
+    }
+    customerAccessToken {
+      ...CustomerAccessToken
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CustomerResetPassword`
+
+**Section**: Customer Password Mutations
+
+**Description**: Resets the password using the 64-hex reset token from the password-reset email. Token TTL is 1h, single-use (atomically marked `used_at`). On success: updates the password hash and returns a fresh JWT for auto-login (no second login step needed). Rate-limited.
+
+**Variables**:
+- `$token`: `String!`
+- `$newPassword`: `String!`
+
+**Fragments used**: `Customer`, `CustomerAccessToken`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CustomerResetPassword($token: String!, $newPassword: String!) {
+  customerResetPassword(token: $token, newPassword: $newPassword) {
+    customer {
+      ...Customer
+    }
+    customerAccessToken {
+      ...CustomerAccessToken
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CheckoutCreate`
+
+**Section**: Checkout Mutations
+
+**Description**: Creates a new checkout session for the given cart (or a fresh cart if `cartId` is omitted). Inherits applied discounts and gift cards from the cart by reference (not snapshot). Errors: `CART_NOT_FOUND`, `EMPTY_CART`, `ALREADY_COMPLETED` (cart already converted to order). NOT idempotent — multiple calls create multiple checkouts.
+
+**Variables**:
+- `$input`: `CheckoutCreateInput!`
+
+**Fragments used**: `Checkout`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CheckoutCreate($input: CheckoutCreateInput!) {
+  checkoutCreate(input: $input) {
+    checkout {
+      ...Checkout
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CheckoutShippingAddressUpdate`
+
+**Section**: Checkout Mutations
+
+**Description**: Sets the shipping address (full replace, not patch). Triggers cart re-pricing. Address format is NOT validated here — full validation runs at `checkoutComplete` (`validateOrderReadiness`).
+
+**Variables**:
+- `$checkoutId`: `ID!`
+- `$shippingAddress`: `CheckoutAddressInput!`
+
+**Fragments used**: `Checkout`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CheckoutShippingAddressUpdate($checkoutId: ID!, $shippingAddress: CheckoutAddressInput!) {
+  checkoutShippingAddressUpdate(
+    checkoutId: $checkoutId
+    shippingAddress: $shippingAddress
+  ) {
+    checkout {
+      ...Checkout
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CheckoutBillingAddressUpdate`
+
+**Section**: Checkout Mutations
+
+**Description**: Sets the billing address (full replace). Independent of shipping address — pass it explicitly even when "billing same as shipping".
+
+**Variables**:
+- `$checkoutId`: `ID!`
+- `$billingAddress`: `CheckoutAddressInput!`
+
+**Fragments used**: `Checkout`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CheckoutBillingAddressUpdate($checkoutId: ID!, $billingAddress: CheckoutAddressInput!) {
+  checkoutBillingAddressUpdate(
+    checkoutId: $checkoutId
+    billingAddress: $billingAddress
+  ) {
+    checkout {
+      ...Checkout
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CheckoutEmailUpdate`
+
+**Section**: Checkout Mutations
+
+**Description**: Sets or updates the contact email on the checkout (used for guest checkout, order confirmation, and tracking emails). Validated against a regex; returns `INVALID` for malformed format.
+
+**Variables**:
+- `$checkoutId`: `ID!`
+- `$email`: `String!`
+
+**Fragments used**: `Checkout`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CheckoutEmailUpdate($checkoutId: ID!, $email: String!) {
+  checkoutEmailUpdate(checkoutId: $checkoutId, email: $email) {
+    checkout {
+      ...Checkout
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CheckoutShippingLineUpdate`
+
+**Section**: Checkout Mutations
+
+**Description**: Selects a shipping method by `shippingRateHandle` (a stable shipping-method UUID, NOT an opaque per-request token). The id comes from `availableShippingMethods` query, computed for the current address + cart subtotal at request time.
+
+**Variables**:
+- `$checkoutId`: `ID!`
+- `$shippingRateHandle`: `String!`
+
+**Fragments used**: `Checkout`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CheckoutShippingLineUpdate($checkoutId: ID!, $shippingRateHandle: String!) {
+  checkoutShippingLineUpdate(
+    checkoutId: $checkoutId
+    shippingRateHandle: $shippingRateHandle
+  ) {
+    checkout {
+      ...Checkout
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CheckoutDiscountCodeApply`
+
+**Section**: Checkout Mutations
+
+**Description**: Appends a discount code to the cart's `discount_codes` array. Note: while multiple codes can be stored, the pricing engine currently uses **only the first applied code** — codes do not stack. Validated for existence, active status, and customer usage limits via `discountService.validateDiscount`.
+
+**Variables**:
+- `$checkoutId`: `ID!`
+- `$discountCode`: `String!`
+
+**Fragments used**: `Checkout`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CheckoutDiscountCodeApply($checkoutId: ID!, $discountCode: String!) {
+  checkoutDiscountCodeApply(checkoutId: $checkoutId, discountCode: $discountCode) {
+    checkout {
+      ...Checkout
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CheckoutDiscountCodeRemove`
+
+**Section**: Checkout Mutations
+
+**Description**: Removes a code from the cart's `discount_codes` array (filters by exact match). Triggers re-pricing.
+
+**Variables**:
+- `$checkoutId`: `ID!`
+- `$discountCode`: `String!`
+
+**Fragments used**: `Checkout`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CheckoutDiscountCodeRemove($checkoutId: ID!, $discountCode: String!) {
+  checkoutDiscountCodeRemove(checkoutId: $checkoutId, discountCode: $discountCode) {
+    checkout {
+      ...Checkout
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CheckoutDiscountCodeValidate`
+
+**Section**: Checkout Mutations
+
+**Description**: READ-ONLY validation of a discount code against the current checkout — does NOT modify state. Returns `{ isValid, discount, error }` for previewing the effect (e.g. inline UI feedback as the user types).
+
+**Variables**:
+- `$checkoutId`: `ID!`
+- `$discountCode`: `String!`
+
+**Fragments used**: `UserError`
+
+**GraphQL**:
+```graphql
+mutation CheckoutDiscountCodeValidate($checkoutId: ID!, $discountCode: String!) {
+  checkoutDiscountCodeValidate(
+    checkoutId: $checkoutId
+    discountCode: $discountCode
+  ) {
+    result {
+      isValid
+      discount {
+        code
+        title
+        type
+        value
+        discountAmount {
+          amount
+          currencyCode
+        }
+      }
+      error {
+        code
+        message
+      }
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CheckoutPaymentMethodUpdate`
+
+**Section**: Checkout Mutations
+
+**Description**: Selects a payment method by `paymentMethodId` (UUID from `availablePaymentMethods` query). Validates existence and active status; no pre-authorization is performed here.
+
+**Variables**:
+- `$checkoutId`: `ID!`
+- `$paymentMethodId`: `ID!`
+
+**Fragments used**: `Checkout`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CheckoutPaymentMethodUpdate($checkoutId: ID!, $paymentMethodId: ID!) {
+  checkoutPaymentMethodUpdate(
+    checkoutId: $checkoutId
+    paymentMethodId: $paymentMethodId
+  ) {
+    checkout {
+      ...Checkout
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CheckoutComplete`
+
+**Section**: Checkout Mutations
+
+**Description**: Finalizes the checkout: creates the `Order`, marks the cart `CONVERTED`, deducts gift cards, emits `ORDER_CREATED` (and `ORDER_CONFIRMED` for COD) — all in a single serializable transaction. **Idempotent on `idempotencyKey`** (NOT on `checkoutId`); auto-generated from `cartId + timestamp` if the caller omits it. The `paymentUrl` field is reserved but is NOT populated here — for hosted gateways (PayU, P24) the storefront calls a separate `paymentCreate` mutation after this returns.
+
+**Variables**:
+- `$checkoutId`: `ID!`
+- `$input`: `CheckoutCompleteInput`
+
+**Fragments used**: `Checkout`, `Order`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CheckoutComplete($checkoutId: ID!, $input: CheckoutCompleteInput) {
+  checkoutComplete(checkoutId: $checkoutId, input: $input) {
+    checkout {
+      ...Checkout
+    }
+    order {
+      ...Order
+    }
+    paymentUrl
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CheckoutGiftCardApply`
+
+**Section**: Gift Card Checkout Mutations
+
+**Description**: Applies a gift card to the cart, stackable with discount codes. Consumption is FIFO: each card consumes `min(remainingBalance, paymentDue)` against the current cart total in the order they were applied. The gift card balance is NOT debited yet — actual deduction happens atomically inside the `checkoutComplete` transaction. Errors: `GIFT_CARD_NOT_FOUND`, `GIFT_CARD_DEPLETED`, `GIFT_CARD_UNUSABLE`, `GIFT_CARD_ALREADY_APPLIED`.
+
+**Variables**:
+- `$checkoutId`: `ID!`
+- `$giftCardCode`: `String!`
+
+**Fragments used**: `Checkout`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CheckoutGiftCardApply($checkoutId: ID!, $giftCardCode: String!) {
+  checkoutGiftCardApply(checkoutId: $checkoutId, giftCardCode: $giftCardCode) {
+    checkout {
+      ...Checkout
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CheckoutGiftCardRemove`
+
+**Section**: Gift Card Checkout Mutations
+
+**Description**: Removes a gift card from the applied list and recalculates FIFO `appliedAmount` for the remaining cards. Since gift card balances are only debited at `checkoutComplete`, removing before completion has no effect on the underlying gift card balance.
+
+**Variables**:
+- `$checkoutId`: `ID!`
+- `$giftCardCode`: `String!`
+
+**Fragments used**: `Checkout`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CheckoutGiftCardRemove($checkoutId: ID!, $giftCardCode: String!) {
+  checkoutGiftCardRemove(checkoutId: $checkoutId, giftCardCode: $giftCardCode) {
+    checkout {
+      ...Checkout
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `CheckoutGiftCardRecipientUpdate`
+
+**Section**: Gift Card Checkout Mutations
+
+**Description**: Sets per-line-item recipient details (name, email, message, delivery date) for digital gift card products in the cart (variants with `type: GIFT_CARD`). Required before `checkoutComplete` for any line item with a gift-card variant. Recipient details are associated with each gift-card line item and propagated to the resulting order.
+
+**Variables**:
+- `$input`: `CheckoutGiftCardRecipientInput!`
+
+**Fragments used**: `Checkout`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CheckoutGiftCardRecipientUpdate($input: CheckoutGiftCardRecipientInput!) {
+  checkoutGiftCardRecipientUpdate(input: $input) {
+    checkout {
+      ...Checkout
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `ReturnCreate`
+
+**Section**: Return Mutations
+
+**Description**: Creates an RMA in `REQUESTED` status (awaits merchant approval — NOT auto-approved). Input: `orderId`, `reason`, `items[{ variantId, quantity, reason, condition }]`, optional `compensationType` (REFUND or STORE_CREDIT) and `customerNote`. Validates the order's `fulfillmentStatus` permits returns and that requested quantities don't exceed already-shipped/unreturned quantities. Supports optional `idempotencyKey` for retry-safe creation.
+
+**Variables**:
+- `$input`: `ReturnCreateInput!`
+
+**Fragments used**: `Return`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation ReturnCreate($input: ReturnCreateInput!) {
+  returnCreate(input: $input) {
+    return {
+      ...Return
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `ReturnCancel`
+
+**Section**: Return Mutations
+
+**Description**: Cancels a return that is currently in `REQUESTED`, `APPROVED`, or `DRAFT` status (cancellation is allowed even AFTER merchant approval, as long as the return shipment hasn't been processed). Sets `cancelled_at` timestamp. Customer can only cancel returns they own.
+
+**Variables**:
+- `$id`: `ID!`
+
+**Fragments used**: `Return`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation ReturnCancel($id: ID!) {
+  returnCancel(id: $id) {
+    return {
+      ...Return
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `RedeemLoyaltyReward`
+
+**Section**: Loyalty Program Mutations
+
+**Description**: Redeems a loyalty reward by `rewardId`. Three reward types are supported, distinguished by which output field is populated: `discountCode` (issues a `LOYALTY-XXXX` code with 30-day expiry), `productDiscountCode` (issues a single-use 100%-off code for a specific product), or `giftCardCode` (creates a new gift card for the customer). Points are deducted atomically inside a transaction — if external creation (e.g. gift card service) fails after deduction, points are reversed.
+
+**Variables**:
+- `$input`: `RedeemRewardInput!`
+
+**Fragments used**: `RedeemRewardPayload`
+
+**GraphQL**:
+```graphql
+mutation RedeemLoyaltyReward($input: RedeemRewardInput!) {
+  redeemLoyaltyReward(input: $input) {
+    ...RedeemRewardPayload
+  }
+}
+```
+
+### Mutation: `GenerateReferralCode`
+
+**Section**: Loyalty Program Mutations
+
+**Description**: Returns the customer's referral code, generating one on first call. Idempotent UPSERT — subsequent calls return the existing code from `customers.referral_code`. Format: `REF-XXXXXXXX` (8 random alphanumeric chars). Output also includes a `shareUrl` built from the shop's domain.
+
+**Variables**: none
+
+**Fragments used**: `GenerateReferralCodePayload`
+
+**GraphQL**:
+```graphql
+mutation GenerateReferralCode {
+  generateReferralCode {
+    ...GenerateReferralCodePayload
+  }
+}
+```
+
+### Mutation: `ReviewCreate`
+
+**Section**: Review Mutations
+
+**Description**: Submits a product review (rating 1-5, content 10-5000 chars, sanitized via `sanitizePlainText`). Default state is `PENDING` — review is hidden from public until merchant approves. If the input includes `orderId`, `isVerifiedPurchase` is auto-set to `true`. Bot-protected and rate-limited (10/min by default).
+
+**Variables**:
+- `$input`: `ReviewCreateInput!`
+
+**Fragments used**: `ProductReview`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation ReviewCreate($input: ReviewCreateInput!) {
+  reviewCreate(input: $input) {
+    review {
+      ...ProductReview
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `ReviewUpvote`
+
+**Section**: Review Mutations
+
+**Description**: Records an upvote (helpful) on a review. UPSERT semantics — one `ReviewVote` row per `(reviewId, customerId)`. Calling upvote twice is a no-op; calling downvote afterwards replaces the vote. Increments `helpful_count` on the review (and decrements `unhelpful_count` if replacing a downvote).
+
+**Variables**:
+- `$reviewId`: `ID!`
+
+**Fragments used**: `ProductReview`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation ReviewUpvote($reviewId: ID!) {
+  reviewUpvote(reviewId: $reviewId) {
+    review {
+      ...ProductReview
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `ReviewDownvote`
+
+**Section**: Review Mutations
+
+**Description**: Records a downvote (unhelpful) on a review. Same UPSERT semantics as `reviewUpvote` — one vote row per `(reviewId, customerId)`, replacing any prior vote. Increments `unhelpful_count`.
+
+**Variables**:
+- `$reviewId`: `ID!`
+
+**Fragments used**: `ProductReview`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation ReviewDownvote($reviewId: ID!) {
+  reviewDownvote(reviewId: $reviewId) {
+    review {
+      ...ProductReview
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
+### Mutation: `WishlistCreate`
+
+**Section**: Wishlist Mutations
+
+**Description**: Creates a new wishlist for the logged-in customer. `name` is optional (defaults to "My Wishlist"); name uniqueness is NOT enforced — customers can have multiple lists with the same name. Setting `isPublic: true` generates a 16-byte hex `shareToken` for public sharing.
+
+**Variables**:
+- `$input`: `WishlistCreateInput!`
+
+**Fragments used**: `Wishlist`
+
+**GraphQL**:
+```graphql
+mutation WishlistCreate($input: WishlistCreateInput!) {
+  wishlistCreate(input: $input) {
+    wishlist {
+      ...Wishlist
+    }
+    userErrors
+  }
+}
+```
+
+### Mutation: `WishlistAddItem`
+
+**Section**: Wishlist Mutations
+
+**Description**: Adds an item by `productId` (and optional `variantId`) to a wishlist. Idempotent on the `(wishlist_id, product_id, variant_id)` unique constraint — adding an already-present item is a silent no-op (`ON CONFLICT DO NOTHING`). Captures `priceAtAdd` for price-drop notifications.
+
+**Variables**:
+- `$wishlistId`: `ID!`
+- `$input`: `WishlistItemInput!`
+
+**Fragments used**: `Wishlist`
+
+**GraphQL**:
+```graphql
+mutation WishlistAddItem($wishlistId: ID!, $input: WishlistItemInput!) {
+  wishlistAddItem(wishlistId: $wishlistId, input: $input) {
+    wishlist {
+      ...Wishlist
+    }
+    userErrors
+  }
+}
+```
+
+### Mutation: `WishlistRemoveItem`
+
+**Section**: Wishlist Mutations
+
+**Description**: Hard-deletes a wishlist item by `itemId` (the `WishlistItem` row id, NOT the product id).
+
+**Variables**:
+- `$wishlistId`: `ID!`
+- `$itemId`: `ID!`
+
+**Fragments used**: `Wishlist`
+
+**GraphQL**:
+```graphql
+mutation WishlistRemoveItem($wishlistId: ID!, $itemId: ID!) {
+  wishlistRemoveItem(wishlistId: $wishlistId, itemId: $itemId) {
+    wishlist {
+      ...Wishlist
+    }
+    userErrors
+  }
+}
+```
+
+### Mutation: `WishlistDelete`
+
+**Section**: Wishlist Mutations
+
+**Description**: Hard-deletes the wishlist row. All `WishlistItem` rows are removed via FK cascade. No soft-delete; cannot be undone.
+
+**Variables**:
+- `$wishlistId`: `ID!`
+
+**Fragments used**: `Wishlist`
+
+**GraphQL**:
+```graphql
+mutation WishlistDelete($wishlistId: ID!) {
+  wishlistDelete(wishlistId: $wishlistId) {
+    wishlist {
+      ...Wishlist
+    }
+    userErrors
+  }
+}
+```
+
+### Mutation: `CartUpdateAttributes`
+
+**Section**: Cart Attributes
+
+**Description**: Replaces (NOT merges) the cart's custom attributes — free-form `[{ key, value }]` pairs visible to merchant in admin. Use for delivery instructions, gift wrap flags, B2B PO numbers, etc. Limit: 250 pairs per cart (returns `CART_ATTRIBUTES_LIMIT_EXCEEDED`); each `key` max 255 chars.
+
+**Variables**:
+- `$id`: `ID!`
+- `$attributes`: `[CartAttributeInput!]!`
+
+**Fragments used**: `Cart`, `CartWarning`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CartUpdateAttributes($id: ID!, $attributes: [CartAttributeInput!]!) {
+  cartUpdateAttributes(id: $id, attributes: $attributes) {
+    cart {
+      ...Cart
+    }
+    userErrors {
+      ...UserError
+    }
+    warnings {
+      ...CartWarning
+    }
+  }
+}
+```
+
+---
+
+## Fragments
+
+Fragments are referenced by name in operations above. Each fragment is defined once below.
+
+### Fragment: `PageInfo` on `PageInfo`
+
+**Section**: Common
+
+**Description**: Standard Relay Connection page metadata. Spread on every paginated query's `pageInfo`.
+
+**GraphQL**:
+```graphql
+fragment PageInfo on PageInfo {
+  hasNextPage
+  hasPreviousPage
+  startCursor
+  endCursor
+}
+```
+
+### Fragment: `UserError` on `UserError`
+
+**Section**: Common
+
+**Description**: Generic mutation error envelope — included in every mutation's `userErrors[]` field. Always check before consuming the happy-path payload.
+
+**GraphQL**:
+```graphql
+fragment UserError on UserError {
+  message
+  code
+  field
+}
+```
+
+### Fragment: `CartWarning` on `CartWarning`
+
+**Section**: Common
+
+**Description**: Non-blocking cart warning (e.g. low stock, partial availability). Cart mutations succeed but surface these for UI hints.
+
+**GraphQL**:
+```graphql
+fragment CartWarning on CartWarning {
+  message
+  code
+  target
+}
+```
+
+### Fragment: `Image` on `Image`
+
+**Section**: Common
+
+**Description**: Base image — original size, no transform. Use for logos, favicons, branding assets that are already sized correctly. ~few KB.
+
+**GraphQL**:
+```graphql
+fragment Image on Image {
+  id
+  url
+  altText
+  width
+  height
+}
+```
+
+### Fragment: `ImageThumbnail` on `Image`
+
+**Section**: Common
+
+**Description**: 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.
+
+**GraphQL**:
+```graphql
+fragment ImageThumbnail on Image {
+  id
+  url(transform: {maxWidth: 300})
+  altText
+  width
+  height
+  thumbhash
+}
+```
+
+### Fragment: `ImageCard` on `Image`
+
+**Section**: Common
+
+**Description**: Card — product cards, collection / category tiles, blog post previews (rendered ~400px, transform delivers up to 800px for 2x DPI). Includes `thumbhash` placeholder.
+
+**GraphQL**:
+```graphql
+fragment ImageCard on Image {
+  id
+  url(transform: {maxWidth: 800})
+  altText
+  width
+  height
+  thumbhash
+}
+```
+
+### Fragment: `ImageFull` on `Image`
+
+**Section**: Common
+
+**Description**: Full — product detail gallery, hero banners (rendered ~800px, transform delivers up to 1600px for 2x DPI). Includes `thumbhash` placeholder.
+
+**GraphQL**:
+```graphql
+fragment ImageFull on Image {
+  id
+  url(transform: {maxWidth: 1600})
+  altText
+  width
+  height
+  thumbhash
+}
+```
+
+### Fragment: `Money` on `Money`
+
+**Section**: Common
+
+**Description**: Plain `{ amount, currencyCode }` price. Use for `compareAtPrice`, totals, and any field where currency conversion transparency is not needed. `amount` is a String.
+
+**GraphQL**:
+```graphql
+fragment Money on Money {
+  amount
+  currencyCode
+}
+```
+
+### Fragment: `Price` on `PriceMoney`
+
+**Section**: Common
+
+**Description**: Lightweight price for listing views (cards, grids, search results) — same shape as `Money`. Spread when full conversion metadata is overkill.
+
+**GraphQL**:
+```graphql
+fragment Price on PriceMoney {
+  amount
+  currencyCode
+}
+```
+
+### Fragment: `PriceMoney` on `PriceMoney`
+
+**Section**: Common
+
+**Description**: 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.
+
+**Uses fragments**: `Price`
+
+**GraphQL**:
+```graphql
+fragment PriceMoney on PriceMoney {
+  ...Price
+  baseAmount
+  baseCurrencyCode
+  exchangeRate
+  marginApplied
+  rateTimestamp
+  isConverted
+}
+```
+
+### Fragment: `SelectedOption` on `SelectedOption`
+
+**Section**: Common
+
+**Description**: Selected variant option (e.g. `{ name: "Color", value: "Red" }`) on a `ProductVariant`. Use to render variant labels in cart / order summaries.
+
+**GraphQL**:
+```graphql
+fragment SelectedOption on SelectedOption {
+  name
+  value
+}
+```
+
+### Fragment: `ProductVariant` on `ProductVariant`
+
+**Section**: Products
+
+**Description**: 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.
+
+**Uses fragments**: `ImageThumbnail`, `Money`, `SelectedOption`
+
+**GraphQL**:
+```graphql
+fragment ProductVariant on ProductVariant {
+  id
+  title
+  sku
+  price {
+    ...Money
+  }
+  compareAtPrice {
+    ...Money
+  }
+  isAvailable
+  availableStock
+  image {
+    ...ImageThumbnail
+  }
+  selectedOptions {
+    ...SelectedOption
+  }
+  barcode
+  weight {
+    value
+    unit
+  }
+  sortOrder
+}
+```
+
+### Fragment: `ProductCard` on `Product`
+
+**Section**: Products
+
+**Description**: 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.
+
+**Uses fragments**: `ImageCard`, `Money`
+
+**GraphQL**:
+```graphql
+fragment ProductCard on Product {
+  id
+  handle
+  title
+  vendor
+  category
+  isAvailable
+  averageRating
+  reviewCount
+  tags
+  featuredImage {
+    ...ImageCard
+  }
+  priceRange {
+    minVariantPrice {
+      ...Money
+    }
+    maxVariantPrice {
+      ...Money
+    }
+  }
+  compareAtPriceRange {
+    minVariantPrice {
+      ...Money
+    }
+    maxVariantPrice {
+      ...Money
+    }
+  }
+}
+```
+
+### Fragment: `ProductBase` on `Product`
+
+**Section**: Products
+
+**Description**: `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.
+
+**Uses fragments**: `ProductCard`
+
+**GraphQL**:
+```graphql
+fragment ProductBase on Product {
+  ...ProductCard
+  description
+  descriptionHtml
+  stockTotal
+  type
+  requiresRecipientInfo
+  visibility
+  attributeSetId
+  createdAt
+  updatedAt
+}
+```
+
+### Fragment: `ProductFull` on `Product`
+
+**Section**: Products
+
+**Description**: 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.
+
+**Uses fragments**: `ImageFull`, `PageInfo`, `ProductBase`, `ProductVariant`
+
+**GraphQL**:
+```graphql
+fragment ProductFull on Product {
+  ...ProductBase
+  images(first: 20) {
+    edges {
+      cursor
+      node {
+        ...ImageFull
+      }
+    }
+    nodes {
+      ...ImageFull
+    }
+    pageInfo {
+      ...PageInfo
+    }
+    totalCount
+  }
+  variants(first: 100) {
+    edges {
+      cursor
+      node {
+        ...ProductVariant
+      }
+    }
+    nodes {
+      ...ProductVariant
+    }
+    pageInfo {
+      ...PageInfo
+    }
+    totalCount
+  }
+  seo {
+    title
+    description
+  }
+}
+```
+
+### Fragment: `Collection` on `Collection`
+
+**Section**: Collections
+
+**Description**: 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.
+
+**Uses fragments**: `ImageCard`
+
+**GraphQL**:
+```graphql
+fragment Collection on Collection {
+  id
+  handle
+  title
+  description
+  descriptionHtml
+  image {
+    ...ImageCard
+  }
+  seo {
+    title
+    description
+  }
+  createdAt
+  updatedAt
+}
+```
+
+### Fragment: `Category` on `Category`
+
+**Section**: Categories
+
+**Description**: 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.
+
+**Uses fragments**: `ImageCard`
+
+**GraphQL**:
+```graphql
+fragment Category on Category {
+  id
+  name
+  slug
+  description
+  image {
+    ...ImageCard
+  }
+  level
+  path
+  productCount
+  sortOrder
+}
+```
+
+### Fragment: `MailingAddress` on `MailingAddress`
+
+**Section**: Customer
+
+**Description**: 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.
+
+**GraphQL**:
+```graphql
+fragment MailingAddress on MailingAddress {
+  id
+  streetLine1
+  streetLine2
+  city
+  company
+  country
+  countryCode
+  firstName
+  lastName
+  phone
+  state
+  stateCode
+  postalCode
+  isDefault
+}
+```
+
+### Fragment: `CustomerAccessToken` on `CustomerAccessToken`
+
+**Section**: Customer
+
+**Description**: Customer access token returned by `customerLogin` / `customerSignup` / `customerActivate` / `customerResetPassword` / `customerRefreshToken`. The token's JWT TTL is 24h; cookie max-age is 30d.
+
+**GraphQL**:
+```graphql
+fragment CustomerAccessToken on CustomerAccessToken {
+  accessToken
+  expiresAt
+}
+```
+
+### Fragment: `Customer` on `Customer`
+
+**Section**: Customer
+
+**Description**: Customer profile — basic info plus B2B fields (`taxId`, `vatNumber`, `regon`, `companyName`), default address, lifetime stats (`orderCount`, `totalSpent`), marketing preferences. Use on profile / settings pages.
+
+**Uses fragments**: `MailingAddress`, `Money`
+
+**GraphQL**:
+```graphql
+fragment Customer on Customer {
+  id
+  email
+  firstName
+  lastName
+  displayName
+  phone
+  isEmailVerified
+  emailMarketing
+  tags
+  customerType
+  companyName
+  taxId
+  vatNumber
+  regon
+  defaultAddress {
+    ...MailingAddress
+  }
+  orderCount
+  totalSpent {
+    ...Money
+  }
+  createdAt
+  updatedAt
+}
+```
+
+### Fragment: `Order` on `Order`
+
+**Section**: Customer
+
+**Description**: 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.
+
+**Uses fragments**: `MailingAddress`, `Money`
+
+**GraphQL**:
+```graphql
+fragment Order on Order {
+  id
+  orderNumber
+  totals {
+    total {
+      ...Money
+    }
+    subtotal {
+      ...Money
+    }
+    totalTax {
+      ...Money
+    }
+    totalShipping {
+      ...Money
+    }
+  }
+  status
+  paymentStatus
+  fulfillmentStatus
+  processedAt
+  confirmedAt
+  cancelledAt
+  expiredAt
+  shippingAddress {
+    ...MailingAddress
+  }
+  itemCount
+}
+```
+
+### Fragment: `CartCost` on `CartCost`
+
+**Section**: Cart
+
+**Description**: Cart-level totals — subtotal, total, tax, duty, checkout charge. Spread inside the `Cart` fragment.
+
+**Uses fragments**: `Money`
+
+**GraphQL**:
+```graphql
+fragment CartCost on CartCost {
+  total {
+    ...Money
+  }
+  subtotal {
+    ...Money
+  }
+  totalTax {
+    ...Money
+  }
+  totalDuty {
+    ...Money
+  }
+  checkoutCharge {
+    ...Money
+  }
+}
+```
+
+### Fragment: `CartLineCost` on `CartLineCost`
+
+**Section**: Cart
+
+**Description**: Per-line cost breakdown — unit price, line subtotal/total, compare-at unit price (for showing strikethroughs). Spread inside `CartLine`.
+
+**Uses fragments**: `Money`
+
+**GraphQL**:
+```graphql
+fragment CartLineCost on CartLineCost {
+  pricePerUnit {
+    ...Money
+  }
+  subtotal {
+    ...Money
+  }
+  total {
+    ...Money
+  }
+  compareAtPricePerUnit {
+    ...Money
+  }
+}
+```
+
+### Fragment: `AttributeSelection` on `AttributeSelection`
+
+**Section**: Cart
+
+**Description**: 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).
+
+**GraphQL**:
+```graphql
+fragment AttributeSelection on AttributeSelection {
+  attributeDefinitionId
+  attributeName
+  type
+  fillingMode
+  billingMode
+  optionId
+  optionLabel
+  optionIds
+  textValue
+  surchargeAmount
+  surchargeType
+  taxClassId
+  linkedVariantId
+}
+```
+
+### Fragment: `CartLine` on `CartLine`
+
+**Section**: Cart
+
+**Description**: 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.
+
+**Uses fragments**: `AttributeSelection`, `CartLineCost`, `ProductVariant`
+
+**GraphQL**:
+```graphql
+fragment CartLine on CartLine {
+  id
+  quantity
+  variant {
+    ...ProductVariant
+  }
+  cost {
+    ...CartLineCost
+  }
+  attributes {
+    key
+    value
+  }
+  attributeSelections {
+    ...AttributeSelection
+  }
+  productId
+  productTitle
+  productHandle
+  productType
+}
+```
+
+### Fragment: `CartBuyerIdentity` on `CartBuyerIdentity`
+
+**Section**: Cart
+
+**Description**: Buyer identity associated with the cart. Note: only `customerId` is currently persisted server-side; `email`, `phone`, `countryCode` are accepted in the input but ignored.
+
+**GraphQL**:
+```graphql
+fragment CartBuyerIdentity on CartBuyerIdentity {
+  email
+  phone
+  countryCode
+}
+```
+
+### Fragment: `CartDiscountCode` on `CartDiscountCode`
+
+**Section**: Cart
+
+**Description**: 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).
+
+**GraphQL**:
+```graphql
+fragment CartDiscountCode on CartDiscountCode {
+  code
+  isApplicable
+}
+```
+
+### Fragment: `CartDiscountAllocation` on `CartDiscountAllocation`
+
+**Section**: Cart
+
+**Description**: 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.
+
+**Uses fragments**: `Money`
+
+**GraphQL**:
+```graphql
+fragment CartDiscountAllocation on CartDiscountAllocation {
+  discountCode
+  amount {
+    ...Money
+  }
+}
+```
+
+### Fragment: `Cart` on `Cart`
+
+**Section**: Cart
+
+**Description**: 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.
+
+**Uses fragments**: `CartBuyerIdentity`, `CartCost`, `CartDiscountAllocation`, `CartDiscountCode`, `CartLine`, `PageInfo`
+
+**GraphQL**:
+```graphql
+fragment Cart on Cart {
+  id
+  checkoutUrl
+  totalQuantity
+  cost {
+    ...CartCost
+  }
+  lines(first: 100) {
+    edges {
+      cursor
+      node {
+        ... on CartLine {
+          ...CartLine
+        }
+      }
+    }
+    nodes {
+      ... on CartLine {
+        ...CartLine
+      }
+    }
+    pageInfo {
+      ...PageInfo
+    }
+    totalCount
+  }
+  buyerIdentity {
+    ...CartBuyerIdentity
+  }
+  discountCodes {
+    ...CartDiscountCode
+  }
+  discountAllocations {
+    ...CartDiscountAllocation
+  }
+  note
+  attributes {
+    key
+    value
+  }
+  createdAt
+  updatedAt
+}
+```
+
+### Fragment: `ShopColors` on `ShopColors`
+
+**Section**: Shop
+
+**Description**: Shop branding colors — primary, secondary, accent, background, text. Use to theme the storefront from server-side config.
+
+**GraphQL**:
+```graphql
+fragment ShopColors on ShopColors {
+  primary
+  secondary
+  accent
+  background
+  text
+}
+```
+
+### Fragment: `ShopFonts` on `ShopFonts`
+
+**Section**: Shop
+
+**Description**: Shop branding fonts — body (`primary`) and `heading` font families.
+
+**GraphQL**:
+```graphql
+fragment ShopFonts on ShopFonts {
+  primary
+  heading
+}
+```
+
+### Fragment: `SocialLinks` on `SocialLinks`
+
+**Section**: Shop
+
+**Description**: Social media links configured for the shop. Spread on the footer.
+
+**GraphQL**:
+```graphql
+fragment SocialLinks on SocialLinks {
+  facebook
+  instagram
+  twitter
+  youtube
+  tiktok
+  linkedin
+  pinterest
+}
+```
+
+### Fragment: `ShopAddress` on `ShopAddress`
+
+**Section**: Shop
+
+**Description**: Shop's physical / business address. Use on the contact page and footer.
+
+**GraphQL**:
+```graphql
+fragment ShopAddress on ShopAddress {
+  streetLine1
+  streetLine2
+  city
+  state
+  postalCode
+  country
+}
+```
+
+### Fragment: `BusinessHour` on `BusinessHour`
+
+**Section**: Shop
+
+**Description**: One day's business hours window. Spread inside `Shop.businessHours[]`.
+
+**GraphQL**:
+```graphql
+fragment BusinessHour on BusinessHour {
+  day
+  openTime
+  closeTime
+  isClosed
+}
+```
+
+### Fragment: `ShopBranding` on `ShopBranding`
+
+**Section**: Shop
+
+**Description**: Full shop branding bundle — logo + favicon + colors + fonts + social links. Spread inside the `Shop` fragment.
+
+**Uses fragments**: `Image`, `ShopColors`, `ShopFonts`, `SocialLinks`
+
+**GraphQL**:
+```graphql
+fragment ShopBranding on ShopBranding {
+  logo {
+    ...Image
+  }
+  favicon {
+    ...Image
+  }
+  colors {
+    ...ShopColors
+  }
+  fonts {
+    ...ShopFonts
+  }
+  socialLinks {
+    ...SocialLinks
+  }
+}
+```
+
+### Fragment: `BotProtectionProvider` on `BotProtectionProviderInfo`
+
+**Section**: Shop
+
+**Description**: Bot-protection provider config (provider name, site key, script URL) for storefront-side challenge widgets.
+
+**GraphQL**:
+```graphql
+fragment BotProtectionProvider on BotProtectionProviderInfo {
+  provider
+  siteKey
+  scriptUrl
+}
+```
+
+### Fragment: `BotProtection` on `BotProtectionInfo`
+
+**Section**: Shop
+
+**Description**: Bot-protection setup for the shop — primary + fallback provider, and the list of `protectedOperations` (mutation names that require a challenge token). Spread inside `Shop`.
+
+**Uses fragments**: `BotProtectionProvider`
+
+**GraphQL**:
+```graphql
+fragment BotProtection on BotProtectionInfo {
+  primary {
+    ...BotProtectionProvider
+  }
+  fallback {
+    ...BotProtectionProvider
+  }
+  protectedOperations
+}
+```
+
+### Fragment: `Shop` on `Shop`
+
+**Section**: Shop
+
+**Description**: 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.
+
+**Uses fragments**: `BotProtection`, `BusinessHour`, `Image`, `ShopAddress`, `ShopBranding`
+
+**GraphQL**:
+```graphql
+fragment Shop on Shop {
+  id
+  name
+  description
+  primaryDomain {
+    host
+    url
+    isSslEnabled
+  }
+  currencyCode
+  supportedCurrencies
+  paymentCurrencies
+  defaultLanguage
+  supportedLanguages
+  logo {
+    ...Image
+  }
+  contactEmail
+  contactPhone
+  address {
+    ...ShopAddress
+  }
+  businessHours {
+    ...BusinessHour
+  }
+  branding {
+    ...ShopBranding
+  }
+  botProtection {
+    ...BotProtection
+  }
+}
+```
+
+### Fragment: `PaymentMethod` on `PaymentMethod`
+
+**Section**: Payment Methods
+
+**Description**: 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.
+
+**GraphQL**:
+```graphql
+fragment PaymentMethod on PaymentMethod {
+  id
+  name
+  provider
+  type
+  icon
+  description
+  isDefault
+  supportedCurrencies
+  position
+}
+```
+
+### Fragment: `AvailablePaymentMethods` on `AvailablePaymentMethods`
+
+**Section**: Payment Methods
+
+**Description**: Active payment methods list with the merchant's `defaultMethod`. Returned by the `availablePaymentMethods` query.
+
+**Uses fragments**: `PaymentMethod`
+
+**GraphQL**:
+```graphql
+fragment AvailablePaymentMethods on AvailablePaymentMethods {
+  methods {
+    ...PaymentMethod
+  }
+  defaultMethod {
+    ...PaymentMethod
+  }
+}
+```
+
+### Fragment: `ShippingRate` on `ShippingRate`
+
+**Section**: Checkout
+
+**Description**: Single shipping rate option — `handle` is the stable id you pass to `checkoutShippingLineUpdate`, plus title and price.
+
+**Uses fragments**: `Money`
+
+**GraphQL**:
+```graphql
+fragment ShippingRate on ShippingRate {
+  handle
+  title
+  price {
+    ...Money
+  }
+}
+```
+
+### Fragment: `TaxLine` on `TaxLine`
+
+**Section**: Checkout
+
+**Description**: One tax line on the checkout — title, rate (decimal, e.g. 0.23 for 23%), computed amount. Spread on the order summary.
+
+**Uses fragments**: `Money`
+
+**GraphQL**:
+```graphql
+fragment TaxLine on TaxLine {
+  title
+  rate
+  price {
+    ...Money
+  }
+}
+```
+
+### Fragment: `DiscountAffectedItem` on `DiscountAffectedItem`
+
+**Section**: Checkout
+
+**Description**: 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.
+
+**Uses fragments**: `Money`
+
+**GraphQL**:
+```graphql
+fragment DiscountAffectedItem on DiscountAffectedItem {
+  productId
+  variantId
+  title
+  quantity
+  originalPrice {
+    ...Money
+  }
+  discountedPrice {
+    ...Money
+  }
+  savings {
+    ...Money
+  }
+  isFreeItem
+}
+```
+
+### Fragment: `DiscountApplication` on `DiscountApplication`
+
+**Section**: Checkout
+
+**Description**: 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.
+
+**Uses fragments**: `DiscountAffectedItem`, `Money`
+
+**GraphQL**:
+```graphql
+fragment DiscountApplication on DiscountApplication {
+  code
+  isApplicable
+  type
+  value {
+    ...Money
+  }
+  title
+  affectedItems {
+    ...DiscountAffectedItem
+  }
+  buyQuantity
+  getQuantity
+  getDiscountPercent
+}
+```
+
+### Fragment: `DiscountCode` on `DiscountCode`
+
+**Section**: Checkout
+
+**Description**: Lightweight discount code entry on the checkout — code + applicability flag.
+
+**GraphQL**:
+```graphql
+fragment DiscountCode on DiscountCode {
+  code
+  isApplicable
+}
+```
+
+### Fragment: `CheckoutLineItem` on `CheckoutLineItem`
+
+**Section**: Checkout
+
+**Description**: Single line item in the checkout — variant snapshot, quantity, unit + total prices, image. Use on the order summary panel.
+
+**Uses fragments**: `ImageThumbnail`, `Money`
+
+**GraphQL**:
+```graphql
+fragment CheckoutLineItem on CheckoutLineItem {
+  id
+  title
+  variantTitle
+  quantity
+  pricePerUnit {
+    ...Money
+  }
+  total {
+    ...Money
+  }
+  variantId
+  productId
+  sku
+  image {
+    ...ImageThumbnail
+  }
+}
+```
+
+### Fragment: `AppliedGiftCard` on `AppliedGiftCard`
+
+**Section**: Checkout
+
+**Description**: 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.
+
+**Uses fragments**: `Money`
+
+**GraphQL**:
+```graphql
+fragment AppliedGiftCard on AppliedGiftCard {
+  maskedCode
+  lastCharacters
+  appliedAmount {
+    ...Money
+  }
+  remainingBalance {
+    ...Money
+  }
+}
+```
+
+### Fragment: `Checkout` on `Checkout`
+
+**Section**: Checkout
+
+**Description**: 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`.
+
+**Uses fragments**: `AppliedGiftCard`, `CheckoutLineItem`, `DiscountApplication`, `DiscountCode`, `MailingAddress`, `Money`, `PaymentMethod`, `ShippingRate`, `TaxLine`
+
+**GraphQL**:
+```graphql
+fragment Checkout on Checkout {
+  id
+  isReady
+  isCompleted
+  completedOrderId
+  webUrl
+  lineItems {
+    ...CheckoutLineItem
+  }
+  totalQuantity
+  shippingAddress {
+    ...MailingAddress
+  }
+  billingAddress {
+    ...MailingAddress
+  }
+  shippingLine {
+    ...ShippingRate
+  }
+  availableShippingRates {
+    ...ShippingRate
+  }
+  shippingRatesReady
+  email
+  phone
+  customerId
+  discountCodes {
+    ...DiscountCode
+  }
+  discountApplications {
+    ...DiscountApplication
+  }
+  availablePaymentMethods {
+    ...PaymentMethod
+  }
+  selectedPaymentMethodId
+  cost {
+    subtotal {
+      ...Money
+    }
+    total {
+      ...Money
+    }
+    totalTax {
+      ...Money
+    }
+    totalShipping {
+      ...Money
+    }
+    totalDiscounts {
+      ...Money
+    }
+  }
+  taxLines {
+    ...TaxLine
+  }
+  appliedGiftCards {
+    ...AppliedGiftCard
+  }
+  totalGiftCardAmount {
+    ...Money
+  }
+  paymentDue {
+    ...Money
+  }
+  currencyCode
+  note
+  createdAt
+  updatedAt
+}
+```
+
+### Fragment: `ShipmentEvent` on `ShipmentEvent`
+
+**Section**: Shipments / Tracking
+
+**Description**: One tracking event in the shipment timeline — status, description, location, timestamp. Spread on the tracking page timeline.
+
+**GraphQL**:
+```graphql
+fragment ShipmentEvent on ShipmentEvent {
+  id
+  status
+  description
+  location
+  occurredAt
+  providerEventCode
+}
+```
+
+### Fragment: `ShipmentPackage` on `ShipmentPackage`
+
+**Section**: Shipments / Tracking
+
+**Description**: Physical package metadata (weight + dimensions). Used in the merchant's label generation; storefronts rarely render this directly.
+
+**GraphQL**:
+```graphql
+fragment ShipmentPackage on ShipmentPackage {
+  weight
+  length
+  width
+  height
+}
+```
+
+### Fragment: `ShipmentItem` on `ShipmentItem`
+
+**Section**: Shipments / Tracking
+
+**Description**: One item in a shipment — title, variant, sku, quantity, image URL. Spread inside `Shipment.items[]` for the tracking page item list.
+
+**GraphQL**:
+```graphql
+fragment ShipmentItem on ShipmentItem {
+  id
+  title
+  variantTitle
+  sku
+  quantity
+  imageUrl
+}
+```
+
+### Fragment: `Shipment` on `Shipment`
+
+**Section**: Shipments / Tracking
+
+**Description**: Full shipment shape — provider, tracking number + URL, label URL, status, ETA, recipient address, packages, items, full event timeline. Spread on the tracking page.
+
+**Uses fragments**: `MailingAddress`, `ShipmentEvent`, `ShipmentItem`, `ShipmentPackage`
+
+**GraphQL**:
+```graphql
+fragment Shipment on Shipment {
+  id
+  orderId
+  provider
+  serviceCode
+  trackingNumber
+  trackingUrl
+  labelUrl
+  status
+  estimatedDeliveryAt
+  shippedAt
+  deliveredAt
+  recipientAddress {
+    ...MailingAddress
+  }
+  packages {
+    ...ShipmentPackage
+  }
+  items {
+    ...ShipmentItem
+  }
+  events {
+    ...ShipmentEvent
+  }
+  createdAt
+  updatedAt
+}
+```
+
+### Fragment: `ShipmentBasic` on `Shipment`
+
+**Section**: Shipments / Tracking
+
+**Description**: Lightweight shipment shape — id, tracking number + URL, status, dates. No items / events / address. Use for order summary cards or on the public `shipmentByTrackingNumber` query.
+
+**GraphQL**:
+```graphql
+fragment ShipmentBasic on Shipment {
+  id
+  orderId
+  provider
+  trackingNumber
+  trackingUrl
+  status
+  estimatedDeliveryAt
+  shippedAt
+  deliveredAt
+  createdAt
+}
+```
+
+### Fragment: `ReturnShippingLabel` on `ReturnShippingLabel`
+
+**Section**: Returns / RMA
+
+**Description**: Return shipping label generated by the carrier — URL to download, carrier name, tracking number, expiry. Spread on the return detail page.
+
+**GraphQL**:
+```graphql
+fragment ReturnShippingLabel on ReturnShippingLabel {
+  url
+  carrier
+  trackingNumber
+  expiresAt
+}
+```
+
+### Fragment: `ReturnItemPhoto` on `ReturnItemPhoto`
+
+**Section**: Returns / RMA
+
+**Description**: Photo evidence attached to a return item (e.g. damage photo). Spread inside `ReturnItem.photos[]`.
+
+**GraphQL**:
+```graphql
+fragment ReturnItemPhoto on ReturnItemPhoto {
+  id
+  url
+  alt
+  description
+  createdAt
+}
+```
+
+### Fragment: `ReturnItem` on `ReturnItem`
+
+**Section**: Returns / RMA
+
+**Description**: 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[]`.
+
+**Uses fragments**: `Money`, `ReturnItemPhoto`
+
+**GraphQL**:
+```graphql
+fragment ReturnItem on ReturnItem {
+  id
+  variantId
+  productTitle
+  variantTitle
+  sku
+  imageUrl
+  quantity
+  reason
+  condition
+  unitPrice {
+    ...Money
+  }
+  photos {
+    ...ReturnItemPhoto
+  }
+  status
+  approvedQuantity
+}
+```
+
+### Fragment: `Return` on `Return`
+
+**Section**: Returns / RMA
+
+**Description**: 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.
+
+**Uses fragments**: `Money`, `ReturnItem`, `ReturnShippingLabel`
+
+**GraphQL**:
+```graphql
+fragment Return on Return {
+  id
+  returnNumber
+  orderId
+  orderNumber
+  status
+  reason
+  customerNote
+  compensationType
+  items {
+    ...ReturnItem
+  }
+  refundAmount {
+    ...Money
+  }
+  shippingLabel {
+    ...ReturnShippingLabel
+  }
+  requestedAt
+  approvedAt
+  receivedAt
+  refundedAt
+  completedAt
+  createdAt
+  updatedAt
+}
+```
+
+### Fragment: `ReturnReasonOption` on `ReturnReasonOption`
+
+**Section**: Returns / RMA
+
+**Description**: Single option in the return reasons dropdown — `value` enum, human-readable `label`, optional `description`. Returned by `returnReasons` query.
+
+**GraphQL**:
+```graphql
+fragment ReturnReasonOption on ReturnReasonOption {
+  value
+  label
+  description
+}
+```
+
+### Fragment: `GiftCard` on `GiftCard`
+
+**Section**: Gift Cards
+
+**Description**: Gift card detail — masked code (first + last 4 chars), status, initial + remaining balance, expiry, recipient/message. Returned by `giftCard($code)` query.
+
+**Uses fragments**: `Money`
+
+**GraphQL**:
+```graphql
+fragment GiftCard on GiftCard {
+  id
+  maskedCode
+  status
+  initialAmount {
+    ...Money
+  }
+  balance {
+    ...Money
+  }
+  expiresAt
+  recipientName
+  message
+  createdAt
+}
+```
+
+### Fragment: `GiftCardError` on `GiftCardError`
+
+**Section**: Gift Cards
+
+**Description**: Validation error on a gift card check — code (`NOT_FOUND` / `DISABLED` / `ALREADY_USED` / `EXPIRED` / `INSUFFICIENT_BALANCE`) + human message.
+
+**GraphQL**:
+```graphql
+fragment GiftCardError on GiftCardError {
+  code
+  message
+}
+```
+
+### Fragment: `GiftCardValidation` on `GiftCardValidation`
+
+**Section**: Gift Cards
+
+**Description**: 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.
+
+**Uses fragments**: `GiftCard`, `GiftCardError`, `Money`
+
+**GraphQL**:
+```graphql
+fragment GiftCardValidation on GiftCardValidation {
+  isValid
+  availableBalance {
+    ...Money
+  }
+  error {
+    ...GiftCardError
+  }
+  giftCard {
+    ...GiftCard
+  }
+}
+```
+
+### Fragment: `ShippingCarrier` on `ShippingCarrier`
+
+**Section**: Shipping Methods
+
+**Description**: Carrier offering the shipping method — id, display name, logo URL, internal service code.
+
+**GraphQL**:
+```graphql
+fragment ShippingCarrier on ShippingCarrier {
+  id
+  name
+  logoUrl
+  serviceCode
+}
+```
+
+### Fragment: `DeliveryEstimate` on `DeliveryEstimate`
+
+**Section**: Shipping Methods
+
+**Description**: Estimated delivery window — `minDays` to `maxDays` plus a human-readable description (e.g. "2-4 business days").
+
+**GraphQL**:
+```graphql
+fragment DeliveryEstimate on DeliveryEstimate {
+  minDays
+  maxDays
+  description
+}
+```
+
+### Fragment: `FreeShippingProgress` on `FreeShippingProgress`
+
+**Section**: Shipping Methods
+
+**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.
+
+**Uses fragments**: `Money`
+
+**GraphQL**:
+```graphql
+fragment FreeShippingProgress on FreeShippingProgress {
+  qualifies
+  currentAmount {
+    ...Money
+  }
+  threshold {
+    ...Money
+  }
+  remaining {
+    ...Money
+  }
+  progressPercent
+  message
+}
+```
+
+### Fragment: `AvailableShippingMethod` on `AvailableShippingMethod`
+
+**Section**: Shipping Methods
+
+**Description**: 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.
+
+**Uses fragments**: `DeliveryEstimate`, `FreeShippingProgress`, `Money`, `ShippingCarrier`
+
+**GraphQL**:
+```graphql
+fragment AvailableShippingMethod on AvailableShippingMethod {
+  id
+  name
+  description
+  carrier {
+    ...ShippingCarrier
+  }
+  price {
+    ...Money
+  }
+  isFree
+  estimatedDelivery {
+    ...DeliveryEstimate
+  }
+  freeShippingProgress {
+    ...FreeShippingProgress
+  }
+  sortOrder
+}
+```
+
+### Fragment: `AttributeSwatch` on `AttributeSwatch`
+
+**Section**: Attribute Filters
+
+**Description**: Visual swatch for an attribute filter value — color hex (for color filters) or image URL (for pattern/material swatches).
+
+**GraphQL**:
+```graphql
+fragment AttributeSwatch on AttributeSwatch {
+  colorHex
+  imageUrl
+}
+```
+
+### Fragment: `AttributeRangeBounds` on `AttributeRangeBounds`
+
+**Section**: Attribute Filters
+
+**Description**: Numeric range bounds for slider-style filters — min, max, currency code (when relevant).
+
+**GraphQL**:
+```graphql
+fragment AttributeRangeBounds on AttributeRangeBounds {
+  min
+  max
+  currencyCode
+}
+```
+
+### Fragment: `AttributeFilterValue` on `AttributeFilterValue`
+
+**Section**: Attribute Filters
+
+**Description**: 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.
+
+**Uses fragments**: `AttributeSwatch`, `Money`
+
+**GraphQL**:
+```graphql
+fragment AttributeFilterValue on AttributeFilterValue {
+  id
+  value
+  label
+  productCount
+  swatch {
+    ...AttributeSwatch
+  }
+  priceModifier {
+    ...Money
+  }
+  sortOrder
+}
+```
+
+### Fragment: `AttributeDefinition` on `AttributeDefinition`
+
+**Section**: Attribute Filters
+
+**Description**: 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[]`.
+
+**Uses fragments**: `AttributeFilterValue`, `AttributeRangeBounds`
+
+**GraphQL**:
+```graphql
+fragment AttributeDefinition on AttributeDefinition {
+  id
+  name
+  handle
+  type
+  isFilterable
+  isVisible
+  displayOrder
+  filterValues {
+    ...AttributeFilterValue
+  }
+  rangeBounds {
+    ...AttributeRangeBounds
+  }
+}
+```
+
+### Fragment: `PriceRangeFilter` on `PriceRange`
+
+**Section**: Attribute Filters
+
+**Description**: Min / max price range across products in the current listing context. Use to bound the price slider.
+
+**Uses fragments**: `Money`
+
+**GraphQL**:
+```graphql
+fragment PriceRangeFilter on PriceRange {
+  min {
+    ...Money
+  }
+  max {
+    ...Money
+  }
+}
+```
+
+### Fragment: `CategoryFilterOption` on `CategoryFilterOption`
+
+**Section**: Attribute Filters
+
+**Description**: 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.
+
+**GraphQL**:
+```graphql
+fragment CategoryFilterOption on CategoryFilterOption {
+  id
+  name
+  slug
+  productCount
+  level
+  parentId
+}
+```
+
+### Fragment: `AvailableFilters` on `AvailableFilters`
+
+**Section**: Attribute Filters
+
+**Description**: 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.
+
+**Uses fragments**: `AttributeDefinition`, `CategoryFilterOption`, `PriceRangeFilter`
+
+**GraphQL**:
+```graphql
+fragment AvailableFilters on AvailableFilters {
+  attributes {
+    ...AttributeDefinition
+  }
+  priceRange {
+    ...PriceRangeFilter
+  }
+  categories {
+    ...CategoryFilterOption
+  }
+  activeFilterCount
+  totalProducts
+}
+```
+
+### Fragment: `LoyaltyPageInfo` on `LoyaltyPageInfo`
+
+**Section**: Loyalty Program
+
+**Description**: Page metadata for the loyalty transactions connection (separate type from generic `PageInfo` for legacy reasons; identical shape).
+
+**GraphQL**:
+```graphql
+fragment LoyaltyPageInfo on LoyaltyPageInfo {
+  hasNextPage
+  hasPreviousPage
+  startCursor
+  endCursor
+}
+```
+
+### Fragment: `LoyaltyTier` on `LoyaltyTier`
+
+**Section**: Loyalty Program
+
+**Description**: 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.
+
+**Uses fragments**: `Money`
+
+**GraphQL**:
+```graphql
+fragment LoyaltyTier on LoyaltyTier {
+  id
+  name
+  type
+  minPoints
+  minAnnualSpend {
+    ...Money
+  }
+  pointsMultiplier
+  customBenefits {
+    name
+    description
+    icon
+  }
+}
+```
+
+### Fragment: `LoyaltyPointsSummary` on `LoyaltyPointsSummary`
+
+**Section**: Loyalty Program
+
+**Description**: 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`.
+
+**GraphQL**:
+```graphql
+fragment LoyaltyPointsSummary on LoyaltyPointsSummary {
+  totalPoints
+  currentPoints
+  pendingPoints
+  redeemedPoints
+  expiredPoints
+  expiringPoints
+  nextExpiryDate
+}
+```
+
+### Fragment: `TierProgress` on `TierProgress`
+
+**Section**: Loyalty Program
+
+**Description**: 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.
+
+**Uses fragments**: `LoyaltyTier`, `Money`
+
+**GraphQL**:
+```graphql
+fragment TierProgress on TierProgress {
+  currentTier {
+    ...LoyaltyTier
+  }
+  nextTier {
+    ...LoyaltyTier
+  }
+  pointsToNextTier
+  progressPercent
+  spendToNextTier {
+    ...Money
+  }
+}
+```
+
+### Fragment: `LoyaltyMember` on `LoyaltyMember`
+
+**Section**: Loyalty Program
+
+**Description**: Customer's loyalty membership — points summary, current tier, tier progress, annual spend, last activity. Returned by `loyaltyMember` (null if not enrolled).
+
+**Uses fragments**: `LoyaltyPointsSummary`, `LoyaltyTier`, `Money`, `TierProgress`
+
+**GraphQL**:
+```graphql
+fragment LoyaltyMember on LoyaltyMember {
+  id
+  customerId
+  points {
+    ...LoyaltyPointsSummary
+  }
+  tier {
+    ...LoyaltyTier
+  }
+  tierProgress {
+    ...TierProgress
+  }
+  annualSpend {
+    ...Money
+  }
+  lastActivityAt
+  enrolledAt
+}
+```
+
+### Fragment: `LoyaltyTransaction` on `LoyaltyTransaction`
+
+**Section**: Loyalty Program
+
+**Description**: 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.
+
+**GraphQL**:
+```graphql
+fragment LoyaltyTransaction on LoyaltyTransaction {
+  id
+  type
+  points
+  balanceAfter
+  orderId
+  description
+  expiresAt
+  createdAt
+}
+```
+
+### Fragment: `LoyaltyReward` on `LoyaltyReward`
+
+**Section**: Loyalty Program
+
+**Description**: Reward customers can redeem — name, type, points cost, discount value (% or fixed), tier requirement, availability flag, remaining redemptions. Spread on the rewards page.
+
+**Uses fragments**: `ImageCard`, `LoyaltyTier`, `Money`
+
+**GraphQL**:
+```graphql
+fragment LoyaltyReward on LoyaltyReward {
+  id
+  name
+  slug
+  type
+  pointsCost
+  discountPercent
+  discountAmount {
+    ...Money
+  }
+  description
+  image {
+    ...ImageCard
+  }
+  isAvailable
+  tierRequired {
+    ...LoyaltyTier
+  }
+  redemptionsRemaining
+}
+```
+
+### Fragment: `PointsEstimate` on `PointsEstimate`
+
+**Section**: Loyalty Program
+
+**Description**: 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.
+
+**GraphQL**:
+```graphql
+fragment PointsEstimate on PointsEstimate {
+  basePoints
+  bonusPoints
+  totalPoints
+  multiplier
+}
+```
+
+### Fragment: `LoyaltyAction` on `LoyaltyAction`
+
+**Section**: Loyalty Program
+
+**Description**: One earn action configured in the loyalty program — type (`PURCHASE` / `SIGNUP` / `REFERRAL` / `REVIEW` / `BIRTHDAY`), enabled flag, points granted.
+
+**GraphQL**:
+```graphql
+fragment LoyaltyAction on LoyaltyAction {
+  type
+  isEnabled
+  points
+}
+```
+
+### Fragment: `LoyaltySettings` on `LoyaltySettings`
+
+**Section**: Loyalty Program
+
+**Description**: 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`.
+
+**Uses fragments**: `LoyaltyAction`
+
+**GraphQL**:
+```graphql
+fragment LoyaltySettings on LoyaltySettings {
+  isEnabled
+  pointsName
+  pointsPerCurrency
+  pointsExpiryMonths
+  availableActions {
+    ...LoyaltyAction
+  }
+  referralEnabled
+  referralPoints
+  referralBonusPoints
+}
+```
+
+### Fragment: `ReferralStats` on `ReferralStats`
+
+**Section**: Loyalty Program
+
+**Description**: Customer referral statistics — code, share URL, counts of referred / completed / pending, lifetime points earned. Returned by `referralStats`.
+
+**GraphQL**:
+```graphql
+fragment ReferralStats on ReferralStats {
+  referralCode
+  shareUrl
+  totalReferred
+  completedReferrals
+  pendingReferrals
+  totalPointsEarned
+}
+```
+
+### Fragment: `RedeemRewardPayload` on `RedeemRewardPayload`
+
+**Section**: Loyalty Program
+
+**Description**: Result of `redeemLoyaltyReward` — depending on the reward type, exactly one of `discountCode`, `productDiscountCode`, `giftCardCode` is populated. Apply the returned code on cart/checkout.
+
+**GraphQL**:
+```graphql
+fragment RedeemRewardPayload on RedeemRewardPayload {
+  success
+  discountCode
+  productDiscountCode
+  giftCardCode
+  userErrors
+}
+```
+
+### Fragment: `GenerateReferralCodePayload` on `GenerateReferralCodePayload`
+
+**Section**: Loyalty Program
+
+**Description**: Result of `generateReferralCode` — the customer's referral code and shareable URL.
+
+**GraphQL**:
+```graphql
+fragment GenerateReferralCodePayload on GenerateReferralCodePayload {
+  success
+  referralCode
+  shareUrl
+  userErrors
+}
+```
+
+### Fragment: `ProductReview` on `ProductReview`
+
+**Section**: Reviews
+
+**Description**: 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.
+
+**GraphQL**:
+```graphql
+fragment ProductReview on ProductReview {
+  id
+  productId
+  rating
+  title
+  content
+  pros
+  cons
+  images
+  authorName
+  isVerifiedPurchase
+  helpfulCount
+  unhelpfulCount
+  response
+  responseAt
+  createdAt
+}
+```
+
+### Fragment: `ReviewStats` on `ReviewStats`
+
+**Section**: Reviews
+
+**Description**: Aggregate review stats for a product — average rating, total count, distribution per star (1-5). Returned by `reviewStats($productId)`.
+
+**GraphQL**:
+```graphql
+fragment ReviewStats on ReviewStats {
+  averageRating
+  totalCount
+  fiveStarCount
+  fourStarCount
+  threeStarCount
+  twoStarCount
+  oneStarCount
+}
+```
+
+### Fragment: `WishlistItem` on `WishlistItem`
+
+**Section**: Wishlists
+
+**Description**: 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`).
+
+**Uses fragments**: `Money`, `ProductCard`
+
+**GraphQL**:
+```graphql
+fragment WishlistItem on WishlistItem {
+  id
+  productId
+  variantId
+  product {
+    ...ProductCard
+  }
+  priceWhenAdded {
+    ...Money
+  }
+  notifyOnSale
+  notifyOnRestock
+  addedAt
+}
+```
+
+### Fragment: `Wishlist` on `Wishlist`
+
+**Section**: Wishlists
+
+**Description**: A customer's wishlist — name, public/private flag, share token (when public), items, item count. Spread on the wishlists page.
+
+**Uses fragments**: `WishlistItem`
+
+**GraphQL**:
+```graphql
+fragment Wishlist on Wishlist {
+  id
+  name
+  isPublic
+  shareToken
+  items {
+    ...WishlistItem
+  }
+  itemCount
+  createdAt
+  updatedAt
+}
+```
+
+### Fragment: `BlogCategory` on `BlogCategory`
+
+**Section**: Blog
+
+**Description**: Blog category — name, slug, description, post count. Spread on category navigation and post category labels.
+
+**GraphQL**:
+```graphql
+fragment BlogCategory on BlogCategory {
+  id
+  name
+  slug
+  description
+  postCount
+}
+```
+
+### Fragment: `BlogTag` on `BlogTag`
+
+**Section**: Blog
+
+**Description**: Blog tag — name, slug, post count. Spread on tag clouds and post tag labels.
+
+**GraphQL**:
+```graphql
+fragment BlogTag on BlogTag {
+  id
+  name
+  slug
+  postCount
+}
+```
+
+### Fragment: `BlogPost` on `BlogPost`
+
+**Section**: Blog
+
+**Description**: 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.
+
+**Uses fragments**: `BlogCategory`, `BlogTag`, `ImageCard`, `ImageThumbnail`
+
+**GraphQL**:
+```graphql
+fragment BlogPost on BlogPost {
+  id
+  title
+  slug
+  excerpt
+  content
+  contentFormat
+  featuredImage {
+    ...ImageCard
+  }
+  author {
+    id
+    name
+    bio
+    avatar {
+      ...ImageThumbnail
+    }
+  }
+  category {
+    ...BlogCategory
+  }
+  tags {
+    ...BlogTag
+  }
+  publishedAt
+  readingTimeMinutes
+  viewCount
+  commentCount
+  allowComments
+  isFeatured
+  status
+  seo {
+    title
+    description
+  }
+  createdAt
+  updatedAt
+}
+```
+
+### Fragment: `ProductRecommendation` on `ProductRecommendation`
+
+**Section**: Recommendations
+
+**Description**: 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.
+
+**Uses fragments**: `ProductCard`
+
+**GraphQL**:
+```graphql
+fragment ProductRecommendation on ProductRecommendation {
+  product {
+    ...ProductCard
+  }
+  type
+  score
+  reason
+}
+```
+
+### Fragment: `CartRecommendation` on `CartRecommendations`
+
+**Section**: Recommendations
+
+**Description**: Recommendations bundle for the cart drawer — `frequentlyBoughtTogether` (cross-sell) and `youMayAlsoLike` (related). Each entry has the same shape as `ProductRecommendation`.
+
+**Uses fragments**: `ProductCard`
+
+**GraphQL**:
+```graphql
+fragment CartRecommendation on CartRecommendations {
+  frequentlyBoughtTogether {
+    product {
+      ...ProductCard
+    }
+    type
+    score
+    reason
+  }
+  youMayAlsoLike {
+    product {
+      ...ProductCard
+    }
+    type
+    score
+    reason
+  }
+}
+```
+
+### Fragment: `LocationAddress` on `LocationAddress`
+
+**Section**: Store Availability (BOPIS / multi-location)
+
+**Description**: 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`.
+
+**GraphQL**:
+```graphql
+fragment LocationAddress on LocationAddress {
+  streetLine1
+  streetLine2
+  city
+  country
+  countryCode
+  state
+  stateCode
+  postalCode
+  phone
+  latitude
+  longitude
+  formatted
+}
+```
+
+### Fragment: `BusinessHoursWindow` on `BusinessHoursWindow`
+
+**Section**: Store Availability (BOPIS / multi-location)
+
+**Description**: One day's open/close window inside `BusinessHours` (24h clock).
+
+**GraphQL**:
+```graphql
+fragment BusinessHoursWindow on BusinessHoursWindow {
+  openHour
+  closeHour
+}
+```
+
+### Fragment: `BusinessHours` on `BusinessHours`
+
+**Section**: Store Availability (BOPIS / multi-location)
+
+**Description**: Weekly business hours — one window per day. Spread inside `Location.businessHours`.
+
+**Uses fragments**: `BusinessHoursWindow`
+
+**GraphQL**:
+```graphql
+fragment BusinessHours on BusinessHours {
+  monday {
+    ...BusinessHoursWindow
+  }
+  tuesday {
+    ...BusinessHoursWindow
+  }
+  wednesday {
+    ...BusinessHoursWindow
+  }
+  thursday {
+    ...BusinessHoursWindow
+  }
+  friday {
+    ...BusinessHoursWindow
+  }
+  saturday {
+    ...BusinessHoursWindow
+  }
+  sunday {
+    ...BusinessHoursWindow
+  }
+}
+```
+
+### Fragment: `Location` on `Location`
+
+**Section**: Store Availability (BOPIS / multi-location)
+
+**Description**: 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.
+
+**Uses fragments**: `BusinessHours`, `LocationAddress`
+
+**GraphQL**:
+```graphql
+fragment Location on Location {
+  id
+  name
+  type
+  supportsPickup
+  timezone
+  pickupInstructions
+  address {
+    ...LocationAddress
+  }
+  businessHours {
+    ...BusinessHours
+  }
+}
+```
+
+### Fragment: `StoreAvailability` on `StoreAvailability`
+
+**Section**: Store Availability (BOPIS / multi-location)
+
+**Description**: Per-location stock entry for one variant — availability flag, stock quantity (token-gated), pickup time, full location detail. Spread inside `StoreAvailabilityConnection.edges[].node`.
+
+**Uses fragments**: `Location`
+
+**GraphQL**:
+```graphql
+fragment StoreAvailability on StoreAvailability {
+  isAvailable
+  availableStock
+  pickupTime
+  location {
+    ...Location
+  }
+}
+```
+
+### Fragment: `StoreAvailabilityConnection` on `StoreAvailabilityConnection`
+
+**Section**: Store Availability (BOPIS / multi-location)
+
+**Description**: Relay connection of `StoreAvailability` entries for a variant — used inside the `VariantStoreAvailability` fragment. Pre-paginated to 10 by default.
+
+**Uses fragments**: `PageInfo`, `StoreAvailability`
+
+**GraphQL**:
+```graphql
+fragment StoreAvailabilityConnection on StoreAvailabilityConnection {
+  totalCount
+  pageInfo {
+    ...PageInfo
+  }
+  edges {
+    cursor
+    node {
+      ...StoreAvailability
+    }
+  }
+}
+```
+
+### Fragment: `VariantStoreAvailability` on `ProductVariant`
+
+**Section**: Store Availability (BOPIS / multi-location)
+
+**Description**: Slim variant projection optimized for the store-picker UI — id, title, sku, isAvailable, total `availableStock` plus per-location `storeAvailability` connection. Use in `productStoreAvailability` query.
+
+**Uses fragments**: `StoreAvailabilityConnection`
+
+**GraphQL**:
+```graphql
+fragment VariantStoreAvailability on ProductVariant {
+  id
+  title
+  sku
+  isAvailable
+  availableStock
+  storeAvailability(first: 10) {
+    ...StoreAvailabilityConnection
+  }
+}
+```
+
+### Fragment: `ShopPage` on `ShopPage`
+
+**Section**: Pages
+
+**Description**: CMS page — handle (URL slug), title, body (HTML), excerpt, SEO metadata, publish date. Spread on About / Privacy / Terms / Returns Policy pages.
+
+**GraphQL**:
+```graphql
+fragment ShopPage on ShopPage {
+  id
+  handle
+  title
+  body
+  excerpt
+  seo {
+    title
+    description
+  }
+  publishedAt
+  createdAt
+  updatedAt
+}
+```
+
+### Fragment: `MenuItem` on `MenuItem`
+
+**Section**: Navigation Menus
+
+**Description**: 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.
+
+**Uses fragments**: `Image`
+
+**GraphQL**:
+```graphql
+fragment MenuItem on MenuItem {
+  id
+  title
+  url
+  type
+  resourceId
+  image {
+    ...Image
+  }
+  items {
+    id
+    title
+    url
+    type
+    resourceId
+    items {
+      id
+      title
+      url
+      type
+      resourceId
+    }
+  }
+}
+```
+
+### Fragment: `Menu` on `Menu`
+
+**Section**: Navigation Menus
+
+**Description**: Navigation menu — handle (e.g. "main-menu", "footer", "mobile"), title, nested item tree. Returned by `menu($handle)` query.
+
+**Uses fragments**: `MenuItem`
+
+**GraphQL**:
+```graphql
+fragment Menu on Menu {
+  id
+  handle
+  title
+  items {
+    ...MenuItem
+  }
+}
+```
+
+### Fragment: `UrlRedirect` on `UrlRedirect`
+
+**Section**: URL Redirects
+
+**Description**: Single legacy `path` → new `target` redirect entry. Use on the server / edge to issue 301 redirects for migrated routes.
+
+**GraphQL**:
+```graphql
+fragment UrlRedirect on UrlRedirect {
+  path
+  target
+}
+```
+
+### Fragment: `LinkedVariantSummary` on `LinkedVariantSummary`
+
+**Section**: Product Configurator (per-product attributes)
+
+**Description**: 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`.
+
+**GraphQL**:
+```graphql
+fragment LinkedVariantSummary on LinkedVariantSummary {
+  id
+  productId
+  title
+  sku
+  availableStock
+  isAvailable
+  trackQuantity
+}
+```
+
+### Fragment: `ProductAttributeOption` on `ProductAttributeOption`
+
+**Section**: Product Configurator (per-product attributes)
+
+**Description**: 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.
+
+**Uses fragments**: `LinkedVariantSummary`
+
+**GraphQL**:
+```graphql
+fragment ProductAttributeOption on ProductAttributeOption {
+  id
+  value
+  label
+  sortOrder
+  colorHex
+  surchargeAmount
+  surchargeType
+  isDefault
+  linkedVariantId
+  linkedVariant {
+    ...LinkedVariantSummary
+  }
+}
+```
+
+### Fragment: `ProductAttributeDefinition` on `ProductAttributeDefinition`
+
+**Section**: Product Configurator (per-product attributes)
+
+**Description**: 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.
+
+**Uses fragments**: `ProductAttributeOption`
+
+**GraphQL**:
+```graphql
+fragment ProductAttributeDefinition on ProductAttributeDefinition {
+  id
+  name
+  slug
+  description
+  type
+  fillingMode
+  billingMode
+  taxClassId
+  scopeProductId
+  isRequired
+  isVisible
+  displayOrder
+  minValue
+  maxValue
+  options {
+    ...ProductAttributeOption
+  }
+}
+```