@doswiftly/storefront-operations 16.1.0 → 18.0.0

package/schema.graphql

@@ -77,7 +77,7 @@ type AttributeDefinition {
   name: String!
 
   """
-  Faza 3 Opcja A (2026-05-17): opcjonalne grupowanie atrybutu (np. "inventory", "marketing", "content"). NULL = atrybut bez grupy. Pomaga storefront-devom rozpoznać "te atrybuty są custom dane ERP" vs "te są filtrowalne cechy katalogu".
+  Optional grouping namespace (e.g. "inventory", "marketing", "content"). NULL = ungrouped. Helps distinguish custom ERP-data attributes from filterable catalog facets.
   """
   namespace: String
 
@@ -109,7 +109,7 @@ input AttributeFilterInput {
   minValue: Float
 
   """
-  Opcjonalny dyskryminator grupy atrybutów (np. "inventory", "marketing"). Faza 3 Opcja A (2026-05-17): konsolidacja MetaProperty-style custom fields pod AttributeDefinition — namespace pozwala filtrować "Marka z grupy XYZ" gdy multiple shopów ma `Marka` w różnych grupach.
+  Optional attribute-group discriminator (e.g. "inventory", "marketing"). Lets you filter a grouped attribute (e.g. "Brand in group XYZ") when the same attribute name exists under different groups.
   """
   namespace: String
 
@@ -146,7 +146,7 @@ type AttributeFilterValue {
 
 """Paginated + searchable attribute options (Relay Connection)"""
 type AttributeFilterValueConnection {
-  """Paginated edges z cursorami"""
+  """Paginated edges with cursors"""
   edges: [AttributeFilterValueEdge!]!
 
   """Shortcut: edges.map(e => e.node)"""
@@ -156,12 +156,12 @@ type AttributeFilterValueConnection {
   pageInfo: PageInfo!
 
   """
-  Total number of attribute options matching the filter (po zastosowaniu search + context). NIE zmienia się przy paginacji — pokazuje pełną liczbę dla counter UI.
+  Total number of attribute options matching the filter (after applying search + context). Stable across pagination — shows the full count for a counter UI.
   """
   totalCount: Int!
 }
 
-"""Edge w AttributeFilterValueConnection (Relay spec)"""
+"""Edge in AttributeFilterValueConnection (Relay spec)"""
 type AttributeFilterValueEdge {
   """
   Opaque pagination cursor (base64-encoded). Echo as `after` for next page.
@@ -189,27 +189,27 @@ enum AttributeOptionSurchargeType {
   PERCENT
 }
 
-"""Input dla attributeOptionsSearch query"""
+"""Input for the attributeOptionsSearch query"""
 input AttributeOptionsSearchInput {
-  """Opaque cursor z pageInfo.endCursor poprzedniej strony"""
+  """Opaque cursor from the previous page (pageInfo.endCursor)"""
   after: String
 
   """
-  Produktowy kontekst (categoryId/collectionId/searchQuery/currentFilters) dla accurate productCount. Exclude-self: gdy currentFilters zawiera ten sam atrybut, jest pomijany.
+  Product context (categoryId/collectionId/searchQuery/currentFilters) for accurate productCount. Exclude-self: when currentFilters contains the same attribute, it is skipped.
   """
   contextInput: AvailableFiltersInput
 
-  """Liczba zwracanych opcji (default 50, max 100)"""
+  """Number of options returned (default 50, max 100)"""
   first: Int
 
-  """Attribute handle (URL-friendly identifier, np. "licencja")"""
+  """Attribute handle (URL-friendly identifier, e.g. "license")"""
   handle: String!
 
-  """Wyszukiwanie po value/label (case-insensitive ILIKE, max 100 znaków)"""
+  """Search by value/label (case-insensitive, max 100 characters)"""
   search: String
 
   """
-  Sort — COUNT_DESC default (most popular first), LABEL_ASC dla alphabetical
+  Sort — COUNT_DESC default (most popular first), LABEL_ASC for alphabetical
   """
   sort: AttributeOptionsSearchSort
 }
@@ -322,8 +322,10 @@ type AttributeSwatch {
   """Hex color code (e.g., #FF5733)"""
   colorHex: String
 
-  """Image URL for pattern swatches"""
-  imageUrl: String
+  """
+  Image swatch for pattern/material attributes (e.g. fabric texture, wood grain). Use `image { url(transform: { maxWidth: 80 }) altText }` for small swatch tiles. Mutually meaningful with `colorHex` only when storefront chooses to render texture-over-color preview.
+  """
+  image: Image
 }
 
 """Type of product attribute"""
@@ -345,7 +347,7 @@ enum AttributeType {
 """Available filters for product listing"""
 type AvailableFilters {
   """
-  Liczba currently applied filters w `currentFilters` (Storefront UI renderuje "Filtry (3)" w sidebar header).
+  Number of currently applied filters in `currentFilters` (render as "Filters (3)" in a sidebar header).
   """
   activeCount: Int!
 
@@ -353,12 +355,12 @@ type AvailableFilters {
   attributes: [AttributeDefinition!]!
 
   """
-  Boolean facet count: liczba produktów w current context spełniających `Product.isAvailable` (przynajmniej jeden aktywny wariant z untracked inventory LUB available>0). Exclude-self: jeśli `available: true` jest w `currentFilters`, count IGNORUJE ten filtr i pokazuje "ile produktów dostępnych w bazowym kontekście" (nie "ile teraz widać"). Spójne semantically z `attributes[].filterValues[].productCount` (per-enum-value facet) i `brands[].productCount` (per-brand facet) — wszystkie używają exclude-self per dimension. Untracked inventory (gift cards, digital, na-zamówienie) zawsze liczy się jako available.
+  Boolean facet count: number of products in the current context that satisfy `Product.isAvailable` (at least one active variant with untracked inventory OR available>0). Exclude-self: if `available: true` is in `currentFilters`, the count IGNORES that filter and shows "how many products are available in the base context" (not "how many are visible right now"). Semantically consistent with `attributes[].filterValues[].productCount` (per-enum-value facet) and `brands[].productCount` (per-brand facet) — all use exclude-self per dimension. Untracked inventory (gift cards, digital, made-to-order) always counts as available.
   """
   availableCount: Int!
 
   """
-  Faza 3 (2026-05-17): canonical Brand entities z product counts w current context. Storefront UI renderuje checkbox list / dropdown z logo per brand. Klik → `filters: [{brand: {handle}}]`. Tylko brandy z >0 produktów w current product set + isActive=true.
+  Canonical Brand entities with product counts in the current context. Render a checkbox list / dropdown with a logo per brand; clicking maps to `filters: [{brand: {handle}}]`. Only brands with >0 products in the current product set and isActive=true are returned.
   """
   brands: [BrandFilterValue!]
 
@@ -369,7 +371,7 @@ type AvailableFilters {
   priceRange: PriceRange
 
   """
-  Total products w current context (categoryId/collectionId/searchQuery) PRZED zaaplikowaniem faceted filters z `currentFilters`. Spójne z `ProductConnection.totalCount` Relay Connection spec — gdy `currentFilters` jest pusty, `AvailableFilters.totalCount` === `products(filters).totalCount`. Użyj do "Wszystkie produkty (N)" w sidebar header.
+  Total products in the current context (categoryId/collectionId/searchQuery) BEFORE applying the faceted filters in `currentFilters`. Consistent with the `ProductConnection.totalCount` Relay Connection spec — when `currentFilters` is empty, `AvailableFilters.totalCount` === `products(filters).totalCount`. Use for "All products (N)" in a sidebar header.
   """
   totalCount: Int!
 }
@@ -377,7 +379,7 @@ type AvailableFilters {
 """Context for available filters query"""
 input AvailableFiltersInput {
   """
-  Czy filtr "dostępne" jest currently zaaplikowany. Mirror `ProductFilter.available`. Backend używa do exclude-self semantyki: gdy `available: true` (lub `false`) tutaj, `AvailableFilters.availableCount` IGNORUJE ten filtr (pokazuje "ile produktów ten facet odsłoni gdy włączysz"), pozostałe facet counts (`attributes[].filterValues[].productCount`, `brands[].productCount`, `categories[].productCount`) APLIKUJĄ go (pokazują "ile produktów w obecnym kontekście + tym facet"). Pomiń (null/undefined) gdy storefront nie aplikuje "dostępne" filter.
+  Whether the "available" filter is currently applied. Mirrors `ProductFilter.available`. Drives exclude-self semantics: when `available: true` (or `false`) here, `AvailableFilters.availableCount` IGNORES this filter (shows "how many products this facet reveals when enabled"), while the other facet counts (`attributes[].filterValues[].productCount`, `brands[].productCount`, `categories[].productCount`) APPLY it (show "how many products in the current context plus this facet"). Omit (null/undefined) when the storefront does not apply the "available" filter.
   """
   available: Boolean
 
@@ -388,7 +390,7 @@ input AvailableFiltersInput {
   collectionId: ID
 
   """
-  Currently applied attribute filters (to update facet counts). Per facet `productCount` używa exclude-self pattern: gdy attrId X jest w currentFilters, facet values X.* są liczone IGNORUJĄC X (pokazują "ile produktów dla X=Y w pozostałym kontekście"). Pozostałe attrIds są aplikowane.
+  Currently applied attribute filters (to update facet counts). Each facet `productCount` uses the exclude-self pattern: when attrId X is in currentFilters, facet values X.* are counted IGNORING X (showing "how many products for X=Y in the remaining context"). Other attrIds are applied.
   """
   currentFilters: [AttributeFilterInput!]
 
@@ -712,7 +714,7 @@ type BotProtectionProviderInfo {
 }
 
 """
-Canonical product brand entity (np. Funko, Nike). Distinct od ShopBrand (shop branding metadata).
+Canonical product brand entity (e.g. Funko, Nike). Distinct from ShopBrand (shop branding metadata).
 """
 type Brand {
   """URL-friendly handle (e.g. "funko" → /brands/funko). Stable per-shop."""
@@ -721,8 +723,10 @@ type Brand {
   """Brand unique identifier"""
   id: ID!
 
-  """Brand logo URL (CDN-served, storefront-rendered)"""
-  logo: String
+  """
+  Brand logo image. Use `logo { url(transform: { maxWidth: 200 }) altText }` for responsive sizing on brand tiles, breadcrumbs, and brand landing pages.
+  """
+  logo: Image
 
   """Brand display name (e.g. "Funko", "Nintendo")"""
   name: String!
@@ -743,10 +747,10 @@ type BrandColors {
   secondary: BrandColorGroup
 }
 
-"""Filter products po brand (canonical entity)"""
+"""Filter products by brand (canonical entity)"""
 input BrandFilter {
   """
-  Brand handle — URL-friendly identifier. Preferowany over `id` dla storefront refetch (stable po URL share).
+  Brand handle — URL-friendly identifier. Preferred over `id` for storefront refetch (stable across URL shares).
   """
   handle: String
 
@@ -754,21 +758,23 @@ input BrandFilter {
   id: ID
 }
 
-"""Brand filter value z product count"""
+"""Brand filter value with product count"""
 type BrandFilterValue {
-  """Brand handle (refetch payload — paste w ProductFilter.brand.handle)"""
+  """Brand handle (refetch payload — paste into ProductFilter.brand.handle)"""
   handle: String!
 
   """Brand ID"""
   id: ID!
 
-  """Brand logo URL (UI rendering)"""
-  logo: String
+  """
+  Brand logo image (UI rendering — facet sidebars / dropdowns). Use `logo { url(transform: { maxWidth: 80 }) altText }` for small thumbs.
+  """
+  logo: Image
 
   """Brand name"""
   name: String!
 
-  """Liczba produktów z tym brandem w current product set"""
+  """Number of products with this brand in the current product set"""
   productCount: Int!
 }
 
@@ -880,13 +886,20 @@ type Cart implements Node {
   """
   attributes: [CartAttribute!]!
 
-  """Available payment methods dla tego cart (shop-configured providers)"""
+  """
+  Available payment methods for this cart — deduplicated per type, sorted by merchant priority.
+  """
   availablePaymentMethods: [PaymentMethod!]!
 
   """
   Shipping methods available for this cart at the given destination. Reads the cart subtotal and weight directly — for pre-cart preview (e.g. a product detail page calculator) use the top-level `availableShippingMethods(address, cart)` query instead. Returns an empty `methods` list plus a `DIGITAL_ONLY_NO_SHIPPING` user error when the cart has no shippable items; the storefront can use this to skip the shipping step entirely.
   """
-  availableShippingMethods(address: ShippingAddressInput!): AvailableShippingMethodsPayload!
+  availableShippingMethods(
+    """
+    Destination address — country (ISO 3166-1 alpha-2), region, postal code and city
+    """
+    address: ShippingAddressInput!
+  ): AvailableShippingMethodsPayload!
 
   """
   Billing address attached to the cart via `cartSetBillingAddress`. Null when the buyer reuses the shipping address as billing (the order will then mirror the shipping address).
@@ -935,7 +948,23 @@ type Cart implements Node {
   id: ID!
 
   """Lines in the cart (paginated, Relay Connection)."""
-  lines(after: String, before: String, first: Float, last: Float): CartLineConnection!
+  lines(
+    """
+    Cursor for forward pagination (cursor of the last edge from the previous page)
+    """
+    after: String
+
+    """
+    Cursor for backward pagination (cursor of the first edge from the next page)
+    """
+    before: String
+
+    """Number of lines to return from the start (forward pagination, max 100)"""
+    first: Float
+
+    """Number of lines to return from the end (backward pagination, max 100)"""
+    last: Float
+  ): CartLineConnection!
 
   """
   Buyer-supplied note (e.g. delivery instructions). Free-form, surfaced to the merchant on the order.
@@ -948,13 +977,21 @@ type Cart implements Node {
   phone: String
 
   """Product recommendations based on cart contents"""
-  recommendations(first: Int = 4): CartRecommendations
+  recommendations(
+    """Number of cart-based recommendations per bucket (default 4, max 100)"""
+    first: Int = 4
+  ): CartRecommendations
 
   """
   True when at least one line in the cart requires physical shipping. False when every line is non-physical (digital, gift card, service, subscription). Use as the single signal to render or skip the shipping step in checkout.
   """
   requiresShipping: Boolean!
 
+  """
+  Optional concrete instrument code selected within `selectedPaymentMethod` (e.g. `"blik"`, `"mb"`, `"154"`). Set when the buyer clicks a specific instrument tile on the storefront (per `PaymentMethod.instruments`). Pre-payment intent: copied to `Order.paymentInstrument` on `cartComplete`. Cross-reference with `availablePaymentMethods.methods[].instruments[]` to resolve `displayName` / `brandImage { url }`.
+  """
+  selectedPaymentInstrument: String
+
   """
   The payment method currently selected on the cart. Null until the buyer picks a method via `cartSelectPaymentMethod`.
   """
@@ -982,6 +1019,11 @@ type Cart implements Node {
 
   """When the cart was last modified (ISO 8601)."""
   updatedAt: DateTime!
+
+  """
+  Non-fatal advisories computed at query time. Currently emitted: `PAYMENT_SELECTION_STALE` when `selectedPaymentMethod` / `selectedPaymentInstrument` are no longer in live gateway capabilities (storefront re-prompts the buyer). Read-only — backend state is not mutated.
+  """
+  warnings: [CartWarning!]!
 }
 
 """Result of `cartAddLines`."""
@@ -1171,6 +1213,30 @@ input CartBuyerIdentityInput {
   phone: String
 }
 
+"""
+Input for `cartClearPaymentSelection` — explicit deselect mutation. Use when the buyer goes back to the payment method picker in an accordion UI instead of re-selecting a method as a workaround. Atomically nulls all payment selection fields (method type + provider code + instrument code + legacy method ID). Idempotent — repeated calls yield the same final state.
+"""
+input CartClearPaymentSelectionInput {
+  """ID of the cart to clear payment selection on."""
+  cartId: ID!
+}
+
+"""
+Result of `cartClearPaymentSelection`. `cart` is populated on success with cleared selection fields (`selectedPaymentMethod === null`, `selectedPaymentInstrument === null`). `userErrors` is populated when the cart is locked (CONVERTED status → `ALREADY_COMPLETED` code).
+"""
+type CartClearPaymentSelectionPayload {
+  """The updated cart with cleared payment selection."""
+  cart: Cart
+
+  """
+  Business / validation errors carrying a stable `CartErrorCode` in `code` (e.g. `ALREADY_COMPLETED`).
+  """
+  userErrors: [UserError!]!
+
+  """Non-fatal advisories — the mutation itself succeeded."""
+  warnings: [CartWarning!]!
+}
+
 """Input for `cartComplete` — finalises the cart into an `Order`."""
 input CartCompleteInput {
   """ID of the cart to complete."""
@@ -1551,15 +1617,27 @@ type CartRemoveLinesPayload {
   warnings: [CartWarning!]!
 }
 
-"""Input for `cartSelectPaymentMethod`."""
+"""
+Input for `cartSelectPaymentMethod` (Intelligent Payment Methods). Method-centric: the buyer picks a category (BLIK, CARD, BANK_TRANSFER, ...) and the backend resolves the preferred provider from `MerchantPaymentConfig` (priority-sorted, merchant-configurable per shop). Optional `preferredProvider` + `preferredInstrument` enable instrument-level deep-link to the gateway hosted page (skips the default landing).
+"""
 input CartSelectPaymentMethodInput {
   """ID of the cart to update."""
   cartId: ID!
 
   """
-  ID of the chosen payment method (matches a `PaymentMethod.id` from `availablePaymentMethods`).
+  Category of the payment method the buyer picked (matches `PaymentMethod.type` from `availablePaymentMethods`).
+  """
+  methodType: PaymentMethodType!
+
+  """
+  Optional gateway-specific instrument code (`blik`, `mb`, `c`, `154`, ...) from `PaymentMethod.instruments[].code`. Requires `preferredProvider` to be set — instrument codes are provider-specific. No restrictive format is enforced, since different gateways may use `.` / `:` / `/` in future codes.
   """
-  paymentMethodId: ID!
+  preferredInstrument: String
+
+  """
+  Optional override of `PaymentMethod.preferredProvider`. Pass a `PaymentProvider` enum value (`PAYU`, `PRZELEWY24`, ...) read off `providersAvailable` / `PaymentInstrument.provider` when the buyer explicitly picks a gateway. Symmetric with the output — forward `instrument.provider` straight back, no case conversion.
+  """
+  preferredProvider: PaymentProvider
 }
 
 """Result of `cartSelectPaymentMethod`."""
@@ -1807,6 +1885,7 @@ enum CartWarningCode {
   MERCHANDISE_NOT_AVAILABLE
   MERCHANDISE_NOT_ENOUGH_STOCK
   PAYMENTS_AMOUNT_REGION_MISMATCH
+  PAYMENT_SELECTION_STALE
   SHIPPING_METHOD_AUTO_CLEARED
 }
 
@@ -1845,7 +1924,17 @@ type Category {
   productCount: Int!
 
   """Products in category"""
-  products(after: String, first: Float! = 20): CategoryConnection!
+  products(
+    """
+    Cursor for forward pagination (cursor of the last edge from the previous page)
+    """
+    after: String
+
+    """
+    Number of products to return from the start (forward pagination, max 100)
+    """
+    first: Float! = 20
+  ): CategoryConnection!
 
   """SEO metadata"""
   seo: SEO
@@ -1926,7 +2015,38 @@ type Collection implements Node {
   image: Image
 
   """Products in collection"""
-  products(after: String, before: String, filters: [ProductFilter!], first: Int, last: Int, reverse: Boolean = false, sortKey: ProductSortKeys = BEST_SELLING): ProductConnection!
+  products(
+    """
+    Cursor for forward pagination (cursor of the last edge from the previous page)
+    """
+    after: String
+
+    """
+    Cursor for backward pagination (cursor of the first edge from the next page)
+    """
+    before: String
+
+    """
+    Faceted filters to narrow the result set (collection scope always wins)
+    """
+    filters: [ProductFilter!]
+
+    """
+    Number of products to return from the start (forward pagination, max 100)
+    """
+    first: Int
+
+    """
+    Number of products to return from the end (backward pagination, max 100)
+    """
+    last: Int
+
+    """Reverse the sort order when true (descending by sortKey)"""
+    reverse: Boolean = false
+
+    """Sort key for ordering products within the collection"""
+    sortKey: ProductSortKeys = BEST_SELLING
+  ): ProductConnection!
 
   """SEO metadata"""
   seo: SEO
@@ -1988,24 +2108,24 @@ type ConvertedPriceRange {
   minVariantPrice: PriceMoney!
 }
 
-"""Wspierany kraj sklepu (ISO 3166-1 alpha-2)"""
+"""A country supported by the shop (ISO 3166-1 alpha-2)"""
 type Country implements Node {
-  """Języki wspierane przez sklep dostępne w tym kraju"""
+  """Shop languages available in this country"""
   availableLanguages: [Language!]!
 
-  """Primary currency w tym kraju"""
+  """Primary currency in this country"""
   currency: Currency!
 
-  """Globally-unique identifier (np. "country:PL")"""
+  """Globally-unique identifier (e.g. "country:PL")"""
   id: ID!
 
   """ISO 3166-1 alpha-2 country code"""
   isoCode: CountryCode!
 
-  """English name kraju (np. "Poland", "Germany")"""
+  """English country name (e.g. "Poland", "Germany")"""
   name: String!
 
-  """System jednostek (metric/imperial)"""
+  """Measurement system (metric/imperial)"""
   unitSystem: UnitSystem!
 }
 
@@ -2298,10 +2418,35 @@ type Customer implements Node {
   """
   Saved address book of the customer (Relay Connection). Use to render an address picker on checkout.
   """
-  addresses(after: String, before: String, first: Int, last: Int): MailingAddressConnection!
+  addresses(
+    """
+    Cursor for forward pagination (cursor of the last edge from the previous page)
+    """
+    after: String
+
+    """
+    Cursor for backward pagination (cursor of the first edge from the next page)
+    """
+    before: String
+
+    """
+    Number of addresses to return from the start (forward pagination, default 10, max 100)
+    """
+    first: Int
+
+    """
+    Number of addresses to return from the end (backward pagination, max 100)
+    """
+    last: Int
+  ): MailingAddressConnection!
 
   """Customer custom field values (post-Opcja A unified custom fields)."""
-  attributes(namespace: String): [EntityAttributeField!]!
+  attributes(
+    """
+    Optional attribute group filter (e.g. `loyalty`, `b2b`); omit to return all groups
+    """
+    namespace: String
+  ): [EntityAttributeField!]!
 
   """
   Company name. Populated when `customerType` is COMPANY; null for INDIVIDUAL profiles.
@@ -2354,7 +2499,15 @@ type Customer implements Node {
   """
   Orders placed by this customer (Relay Connection). Use for the order history page.
   """
-  orders(after: String, first: Int = 10): OrderConnection!
+  orders(
+    """
+    Cursor for forward pagination (cursor of the last edge from the previous page)
+    """
+    after: String
+
+    """Number of orders to return per page (default 10, max 100)"""
+    first: Int = 10
+  ): OrderConnection!
 
   """Customer phone number (free-form)."""
   phone: String
@@ -2364,6 +2517,11 @@ type Customer implements Node {
   """
   regon: String
 
+  """
+  Expiry of the access token authenticating the current request (ISO 8601). Present only on the authenticated current customer (the `customer` query); null otherwise. Schedule a proactive `customerRefreshToken` before this to keep the session alive.
+  """
+  sessionExpiresAt: DateTime
+
   """
   Merchant-assigned segmentation tags (e.g. "vip", "wholesale", "b2b"). Use to customise UI / pricing rules on the storefront.
   """
@@ -2804,7 +2962,7 @@ type Domain {
   """Whether HTTPS is enforced"""
   isSslEnabled: Boolean!
 
-  """Full URL z protocol"""
+  """Full URL including protocol"""
   url: URL!
 }
 
@@ -3103,7 +3261,12 @@ type Image {
   """
   Public image URL. Pass an optional `transform` argument (max width / height, crop region, scale, preferred format) to obtain a resized / reformatted CDN variant — useful for responsive images and modern formats like WebP / AVIF.
   """
-  url(transform: ImageTransformInput): String!
+  url(
+    """
+    Optional CDN transform (maxWidth/maxHeight/crop/scale/preferredContentType WEBP/AVIF)
+    """
+    transform: ImageTransformInput
+  ): String!
 
   """Native width of the source image in pixels."""
   width: Int
@@ -3217,28 +3380,28 @@ enum LanguageDirection {
 }
 
 """
-Summary of a ProductVariant linked to an AttributeOption (Faza 1.5 configurator).
+Summary of a ProductVariant linked to an AttributeOption (product configurator).
 """
 type LinkedVariantSummary {
-  """Available stock (stock − active reservations, zawsze ≥ 0)."""
+  """Available stock (stock − active reservations, always ≥ 0)."""
   availableStock: Int!
 
-  """Variant ID (w tenant DB)."""
+  """Variant ID."""
   id: ID!
 
-  """Czy w tej chwili dostępny do zakupu (uwzględnia allowBackorder)."""
+  """Whether currently purchasable (accounts for allowBackorder)."""
   isAvailable: Boolean!
 
   """Parent product ID."""
   productId: ID!
 
-  """SKU jeśli zdefiniowany."""
+  """SKU when defined."""
   sku: String
 
-  """Variant name (e.g., "Finiszer Zewnętrzny SD")."""
+  """Variant name (e.g., "Large / Graphite")."""
   title: String!
 
-  """Czy magazyn śledzi stock dla tego wariantu."""
+  """Whether inventory is tracked for this variant."""
   trackQuantity: Boolean!
 }
 
@@ -3251,18 +3414,18 @@ type LocaleCurrencyMapping {
   locale: String!
 }
 
-"""Localization context dla storefronta"""
+"""Localization context for the storefront"""
 type Localization {
-  """Wszystkie wsparte kraje (z aktywnych shipping zones)"""
+  """All supported countries (from active shipping zones)"""
   availableCountries: [Country!]!
 
-  """Wszystkie wsparte języki sklepu"""
+  """All supported shop languages"""
   availableLanguages: [Language!]!
 
-  """Aktualny kraj klienta (z `@inContext` lub geo-detection)"""
+  """The customer current country (from `@inContext` or geo-detection)"""
   country: Country!
 
-  """Aktualny język klienta (z `Accept-Language` lub `@inContext`)"""
+  """The customer current language (from `Accept-Language` or `@inContext`)"""
   language: Language!
 }
 
@@ -3836,87 +3999,191 @@ type Mutation {
   """
   Add one or more lines to the cart. Adding the same variant a second time merges into the existing line (sums the quantity). Returns the full updated cart plus any non-fatal warnings (e.g. stock dropped below requested quantity).
   """
-  cartAddLines(id: ID!, lines: [CartLineInput!]!): CartAddLinesPayload!
+  cartAddLines(
+    """Cart UUID to add lines to"""
+    id: ID!
+
+    """
+    Lines to add — each one variant + quantity (+ optional attributes / selections)
+    """
+    lines: [CartLineInput!]!
+  ): CartAddLinesPayload!
 
   """
   Apply a gift card to the cart by full code. The card is debited at `cartComplete`. Rate-limited to 5 requests per minute per IP+shop (gift card codes form a finite enumerable space).
   """
-  cartApplyGiftCard(input: CartApplyGiftCardInput!): CartApplyGiftCardPayload!
+  cartApplyGiftCard(
+    """Cart UUID + full gift card code to redeem against the cart"""
+    input: CartApplyGiftCardInput!
+  ): CartApplyGiftCardPayload!
+
+  """
+  Clear all payment selection state on the cart in a single atomic operation. Use for accordion "back to method picker" flows in the storefront UI. Idempotent — calling twice yields the same end state. The cart must be `ACTIVE` (CONVERTED carts reject with `ALREADY_COMPLETED`).
+  """
+  cartClearPaymentSelection(
+    """
+    Cart UUID to clear all payment selection state (method, provider, instrument)
+    """
+    input: CartClearPaymentSelectionInput!
+  ): CartClearPaymentSelectionPayload!
 
   """
   Finalise the cart into an `Order`. The cart is locked and no longer accepts mutations. Payment is initiated separately via `paymentCreate` — check `order.canCreatePayment` to decide whether to render a "Pay now" button or send the buyer directly to the confirmation page (for offline methods such as cash on delivery). Rate-limited to 5 requests per minute per IP+shop; pass an `idempotencyKey` to guard against duplicate orders on retry.
   """
-  cartComplete(input: CartCompleteInput!): CartCompletePayload!
+  cartComplete(
+    """
+    Cart UUID + optional idempotency key to guard against duplicate orders on retry
+    """
+    input: CartCompleteInput!
+  ): CartCompletePayload!
 
   """
   Create a new cart. All fields on `input` are optional — call with no input to create an empty cart, or pass initial lines, buyer identity, attributes, discount codes, email and a shipping address to skip the corresponding follow-up calls.
   """
-  cartCreate(input: CartCreateInput): CartCreatePayload!
+  cartCreate(
+    """
+    Optional initial cart contents — lines, buyer identity, email, address, attributes, discount codes
+    """
+    input: CartCreateInput
+  ): CartCreatePayload!
 
   """
   Replace (not merge) the list of discount codes on the cart. Pass an empty array to clear all codes. Rate-limited to 10 requests per minute per IP+shop.
   """
-  cartDiscountCodesUpdate(discountCodes: [String!]!, id: ID!): CartDiscountCodesUpdatePayload!
+  cartDiscountCodesUpdate(
+    """
+    Full replacement list of discount codes (case-insensitive); empty array clears all
+    """
+    discountCodes: [String!]!
+
+    """Cart UUID to apply discount codes to"""
+    id: ID!
+  ): CartDiscountCodesUpdatePayload!
 
   """
   Remove a previously applied gift card from the cart by its `CartAppliedGiftCard.id`. The storefront never has to handle the full gift card code on the client.
   """
-  cartRemoveGiftCard(input: CartRemoveGiftCardInput!): CartRemoveGiftCardPayload!
+  cartRemoveGiftCard(
+    """Cart UUID + applied gift card UUID to remove from the cart"""
+    input: CartRemoveGiftCardInput!
+  ): CartRemoveGiftCardPayload!
 
   """
   Remove one or more lines from the cart by `CartLine.id`. Equivalent to `cartUpdateLines` with `quantity: 0` but lets the storefront express the intent explicitly.
   """
-  cartRemoveLines(id: ID!, lineIds: [ID!]!): CartRemoveLinesPayload!
+  cartRemoveLines(
+    """Cart UUID to remove lines from"""
+    id: ID!
+
+    """UUIDs of cart lines to remove (`CartLine.id`)"""
+    lineIds: [ID!]!
+  ): CartRemoveLinesPayload!
 
   """
-  Select a payment method on the cart. Validates against the active shop payment methods and currency. The selection is finalised at `cartComplete`; payment itself is initiated via a separate `paymentCreate` mutation after the order is created.
+  Select a payment method on the cart by category (BLIK, CARD, BANK_TRANSFER, ...). Backend resolves the preferred provider from `MerchantPaymentConfig` at `paymentCreate` time. Optional `preferredProvider` overrides the merchant priority when the buyer explicitly picks a gateway from `PaymentMethod.providersAvailable`. Optional `preferredInstrument` enables instrument-level deep-link na gateway hosted page (BLIK ekran, mBank flow, etc.) — wymaga `preferredProvider`.
   """
-  cartSelectPaymentMethod(input: CartSelectPaymentMethodInput!): CartSelectPaymentMethodPayload!
+  cartSelectPaymentMethod(
+    """
+    Cart UUID + payment method category, with optional provider and instrument overrides
+    """
+    input: CartSelectPaymentMethodInput!
+  ): CartSelectPaymentMethodPayload!
 
   """
   Select a shipping method on the cart. Validates the method against the cart contents and the shipping address (must be eligible for the destination, and a pickup point must be set when the method delivers to a locker / collection point). Updates `cost.totalShipping` and the grand total.
   """
-  cartSelectShippingMethod(input: CartSelectShippingMethodInput!): CartSelectShippingMethodPayload!
+  cartSelectShippingMethod(
+    """Cart UUID + shipping method UUID to select for the cart"""
+    input: CartSelectShippingMethodInput!
+  ): CartSelectShippingMethodPayload!
 
   """
   Set the billing address on a cart. The shipping address is left unchanged — pass billing only when it differs from shipping (otherwise the order mirrors the shipping address as the billing address).
   """
-  cartSetBillingAddress(input: CartSetBillingAddressInput!): CartSetBillingAddressPayload!
+  cartSetBillingAddress(
+    """
+    Cart UUID + billing address (pass only when billing differs from shipping)
+    """
+    input: CartSetBillingAddressInput!
+  ): CartSetBillingAddressPayload!
 
   """
   Set the shipping address on a cart. Pass `address.pickupPoint` when the buyer is delivering to a parcel locker / collection point — required for non-HOME shipping methods. Replaces any previous shipping address; the billing address is left untouched.
   """
-  cartSetShippingAddress(input: CartSetShippingAddressInput!): CartSetShippingAddressPayload!
+  cartSetShippingAddress(
+    """
+    Cart UUID + shipping address (with optional pickup point for parcel locker delivery)
+    """
+    input: CartSetShippingAddressInput!
+  ): CartSetShippingAddressPayload!
 
   """
   Replace (not merge) the cart-level custom attributes — free-form key/value pairs surfaced to the merchant on the order. Use for cart-wide metadata such as a B2B PO number or marketing source. Max 250 pairs / 255-char keys; over the limit returns `CART_ATTRIBUTES_LIMIT_EXCEEDED`.
   """
-  cartUpdateAttributes(attributes: [CartAttributeInput!]!, id: ID!): CartUpdateAttributesPayload!
+  cartUpdateAttributes(
+    """
+    Full replacement list of cart-level key/value attributes (max 250 pairs, 255-char keys)
+    """
+    attributes: [CartAttributeInput!]!
+
+    """Cart UUID whose attributes are replaced"""
+    id: ID!
+  ): CartUpdateAttributesPayload!
 
   """
   Update buyer identity on the cart — email, phone, customer ID, country and language hints. Only supplied fields are touched; omit a field to leave it unchanged.
   """
-  cartUpdateBuyerIdentity(buyerIdentity: CartBuyerIdentityInput!, id: ID!): CartUpdateBuyerIdentityPayload!
+  cartUpdateBuyerIdentity(
+    """
+    Buyer identity fields — email / phone / customer ID / country / language; only supplied fields touched
+    """
+    buyerIdentity: CartBuyerIdentityInput!
+
+    """Cart UUID whose buyer identity is updated"""
+    id: ID!
+  ): CartUpdateBuyerIdentityPayload!
 
   """
   Set recipient details (email, display name, personalised message) on a gift card line item — the gift card will be delivered to this recipient on order completion.
   """
-  cartUpdateGiftCardRecipient(input: CartUpdateGiftCardRecipientInput!): CartUpdateGiftCardRecipientPayload!
+  cartUpdateGiftCardRecipient(
+    """
+    Cart UUID + gift card line item UUID + recipient details (email, name, message)
+    """
+    input: CartUpdateGiftCardRecipientInput!
+  ): CartUpdateGiftCardRecipientPayload!
 
   """
   Update existing cart lines — quantity, custom attributes and / or configurator selections. Set `quantity` to 0 to remove a line. Address lines by `CartLine.id`.
   """
-  cartUpdateLines(id: ID!, lines: [CartLineUpdateInput!]!): CartUpdateLinesPayload!
+  cartUpdateLines(
+    """Cart UUID to update lines on"""
+    id: ID!
+
+    """
+    Line updates — addressed by `CartLine.id`; `quantity: 0` removes the line
+    """
+    lines: [CartLineUpdateInput!]!
+  ): CartUpdateLinesPayload!
 
   """
   Set or replace the buyer note on the cart (free-form, up to 1000 chars). Surfaced to the merchant on the resulting order.
   """
-  cartUpdateNote(id: ID!, note: String!): CartUpdateNotePayload!
+  cartUpdateNote(
+    """Cart UUID whose note is updated"""
+    id: ID!
+
+    """
+    Free-form buyer note (max 1000 chars), surfaced to the merchant on the order
+    """
+    note: String!
+  ): CartUpdateNotePayload!
 
   """
   Activate customer account using raw activation token (admin-created flow)
   """
   customerActivate(
+    """New password (must satisfy the shop password policy)"""
     password: String!
 
     """Raw activation token from the activation email"""
@@ -3924,12 +4191,20 @@ type Mutation {
   ): CustomerActivatePayload!
 
   """Add customer address"""
-  customerAddAddress(address: MailingAddressInput!): CustomerAddAddressPayload!
+  customerAddAddress(
+    """
+    Address to add to the customer address book (incl. optional B2B `taxId` / `vatNumber`)
+    """
+    address: MailingAddressInput!
+  ): CustomerAddAddressPayload!
 
   """
   Sign a customer in with email and password. Returns an access token to use on subsequent requests (as a Bearer header or via the SDK auth cookie).
   """
-  customerLogin(input: CustomerAccessTokenCreateInput!): CustomerLoginPayload!
+  customerLogin(
+    """Login credentials — email + password"""
+    input: CustomerAccessTokenCreateInput!
+  ): CustomerLoginPayload!
 
   """
   Sign the current customer out. Invalidates the access token on the server; the SDK BFF auth helpers additionally clear the HTTP-only cookie.
@@ -3942,13 +4217,22 @@ type Mutation {
   customerRefreshToken: CustomerRefreshTokenPayload!
 
   """Remove customer address"""
-  customerRemoveAddress(id: ID!): CustomerRemoveAddressPayload!
+  customerRemoveAddress(
+    """UUID of the address to remove"""
+    id: ID!
+  ): CustomerRemoveAddressPayload!
 
   """Request password reset email"""
-  customerRequestPasswordReset(email: String!): CustomerRequestPasswordResetPayload!
+  customerRequestPasswordReset(
+    """
+    Customer email (RFC 5322); always returns success to prevent account enumeration
+    """
+    email: String!
+  ): CustomerRequestPasswordResetPayload!
 
   """Reset customer password via signed URL from email"""
   customerResetPassword(
+    """New password (must satisfy the shop password policy)"""
     newPassword: String!
 
     """Raw password-reset token from the password-reset email"""
@@ -3956,66 +4240,142 @@ type Mutation {
   ): CustomerResetPasswordPayload!
 
   """Set default address"""
-  customerSetDefaultAddress(addressId: ID!): CustomerSetDefaultAddressPayload!
+  customerSetDefaultAddress(
+    """
+    UUID of the address to mark as default for shipping and billing pickers
+    """
+    addressId: ID!
+  ): CustomerSetDefaultAddressPayload!
 
   """
   Register a new customer with email and password. Returns the created customer plus an access token so the storefront can sign the buyer in immediately, no follow-up login call needed.
   """
-  customerSignup(input: CustomerCreateInput!): CustomerSignupPayload!
+  customerSignup(
+    """
+    New customer registration data — email, password, optional profile and marketing consent
+    """
+    input: CustomerCreateInput!
+  ): CustomerSignupPayload!
 
   """Subscribe an email to the newsletter (guest-friendly, double opt-in)."""
-  customerSubscribeToMarketing(input: CustomerSubscribeToMarketingInput!): SubscribeToMarketingPayload!
+  customerSubscribeToMarketing(
+    """
+    Newsletter subscribe — email to opt in (double opt-in flow, anti-enumeration)
+    """
+    input: CustomerSubscribeToMarketingInput!
+  ): SubscribeToMarketingPayload!
 
   """Unsubscribe an email from the newsletter (guest-friendly, idempotent)."""
-  customerUnsubscribeFromMarketing(input: CustomerUnsubscribeFromMarketingInput!): UnsubscribeFromMarketingPayload!
+  customerUnsubscribeFromMarketing(
+    """
+    Newsletter unsubscribe — email to opt out (idempotent, anti-enumeration)
+    """
+    input: CustomerUnsubscribeFromMarketingInput!
+  ): UnsubscribeFromMarketingPayload!
 
   """Update customer profile"""
-  customerUpdate(customer: CustomerUpdateInput!): CustomerUpdatePayload!
+  customerUpdate(
+    """
+    Customer profile changes — only supplied fields are touched (strict-hybrid)
+    """
+    customer: CustomerUpdateInput!
+  ): CustomerUpdatePayload!
 
   """Update customer address"""
-  customerUpdateAddress(address: MailingAddressInput!, id: ID!): CustomerUpdateAddressPayload!
+  customerUpdateAddress(
+    """New values — supplied fields replace existing ones"""
+    address: MailingAddressInput!
+
+    """UUID of the address to update"""
+    id: ID!
+  ): CustomerUpdateAddressPayload!
 
   """Generate or retrieve referral code"""
   loyaltyGenerateReferralCode: GenerateReferralCodePayload!
 
   """Redeem a loyalty reward"""
-  loyaltyRedeemReward(input: RedeemRewardInput!): RedeemRewardPayload!
+  loyaltyRedeemReward(
+    """Reward redemption payload (rewardId UUID)"""
+    input: RedeemRewardInput!
+  ): RedeemRewardPayload!
 
   """
   Initiate a payment session for an order created by `cartComplete`. Call after checking `order.canCreatePayment`. Idempotent on the order — a second call returns the existing still-valid session. Branch on the returned `payment.flow` to launch the payment (redirect / embedded / instant). Rate-limited to 5 requests per minute per IP+shop.
   """
-  paymentCreate(input: PaymentCreateInput!): PaymentCreatePayload!
+  paymentCreate(
+    """
+    Payment session payload (orderId UUID, optional returnUrl/cancelUrl — open-redirect validated server-side)
+    """
+    input: PaymentCreateInput!
+  ): PaymentCreatePayload!
 
   """Cancel a return request"""
-  returnCancel(id: ID!): ReturnCancelPayload!
+  returnCancel(
+    """Return UUID to cancel (only REQUESTED/APPROVED/DRAFT statuses)"""
+    id: ID!
+  ): ReturnCancelPayload!
 
   """Create a return request"""
-  returnCreate(input: ReturnCreateInput!): ReturnCreatePayload!
+  returnCreate(
+    """
+    Return request payload (orderId, reason, items[], optional customerNote/compensationType/idempotencyKey)
+    """
+    input: ReturnCreateInput!
+  ): ReturnCreatePayload!
 
   """Create a product review"""
-  reviewCreate(input: ReviewCreateInput!): ReviewPayload!
+  reviewCreate(
+    """
+    Review payload (productId, rating 1-5, content min 10 chars, optional title/pros/cons/images)
+    """
+    input: ReviewCreateInput!
+  ): ReviewPayload!
 
   """
   Mark review as not helpful (downvote). Replaces any prior vote by same customer.
   """
-  reviewDownvote(reviewId: ID!): ReviewPayload!
+  reviewDownvote(
+    """Review UUID to downvote"""
+    reviewId: ID!
+  ): ReviewPayload!
 
   """
   Mark review as helpful (upvote). Replaces any prior vote by same customer.
   """
-  reviewUpvote(reviewId: ID!): ReviewPayload!
+  reviewUpvote(
+    """Review UUID to upvote"""
+    reviewId: ID!
+  ): ReviewPayload!
 
   """Add item to wishlist"""
-  wishlistAddItem(id: ID!, input: WishlistItemInput!): WishlistPayload!
+  wishlistAddItem(
+    """Wishlist UUID to add the item to"""
+    id: ID!
+
+    """Product UUID (and optional variant UUID) + notification preferences"""
+    input: WishlistItemInput!
+  ): WishlistPayload!
 
   """Create a new wishlist"""
-  wishlistCreate(input: WishlistCreateInput!): WishlistPayload!
+  wishlistCreate(
+    """Wishlist details (name + isPublic flag for share-by-link visibility)"""
+    input: WishlistCreateInput!
+  ): WishlistPayload!
 
   """Delete a wishlist"""
-  wishlistDelete(id: ID!): WishlistPayload!
+  wishlistDelete(
+    """Wishlist UUID to delete (must be owned by the authenticated customer)"""
+    id: ID!
+  ): WishlistPayload!
 
   """Remove item from wishlist"""
-  wishlistRemoveItem(id: ID!, itemId: ID!): WishlistPayload!
+  wishlistRemoveItem(
+    """Wishlist UUID containing the item"""
+    id: ID!
+
+    """Wishlist item UUID to remove"""
+    itemId: ID!
+  ): WishlistPayload!
 }
 
 """GraphQL Node interface — universal ID-based lookup"""
@@ -4025,7 +4385,7 @@ interface Node {
 }
 
 """
-Type discriminator dla node()/nodes() queries (UUID nie zawiera type prefix)
+Type discriminator for node()/nodes() queries (the UUID does not contain a type prefix)
 """
 enum NodeType {
   ARTICLE
@@ -4050,7 +4410,12 @@ type Order implements Node {
   accessToken: String!
 
   """Order custom field values (post-Opcja A unified custom fields)."""
-  attributes(namespace: String): [EntityAttributeField!]!
+  attributes(
+    """
+    Optional namespace prefix to filter attributes (e.g. "erp", "b2b", "fulfillment")
+    """
+    namespace: String
+  ): [EntityAttributeField!]!
 
   """
   True when the storefront should initiate an online payment for this order — render a "Pay now" button. False when the order is cancelled, already paid, or uses an offline payment method (cash on delivery, manual bank transfer) where no online flow applies. Retry-friendly: returns true for UNPAID / PENDING / FAILED payment statuses when the method supports online init.
@@ -4086,7 +4451,17 @@ type Order implements Node {
   """
   Line items on the order (paginated, Relay Connection). Use to render the order summary on the confirmation or order detail page.
   """
-  lineItems(after: String, first: Int = 10): OrderLineItemConnection!
+  lineItems(
+    """
+    Cursor for forward pagination (cursor of the last edge from the previous page)
+    """
+    after: String
+
+    """
+    Number of line items to return from the start (forward pagination, default 10)
+    """
+    first: Int = 10
+  ): OrderLineItemConnection!
 
   """
   Human-readable order number shown to the buyer and the merchant (e.g. "1042"). Distinct from `id`.
@@ -4094,7 +4469,7 @@ type Order implements Node {
   orderNumber: String!
 
   """
-  Category of the payment method on the order (CARD, BLIK, BANK_TRANSFER, CASH_ON_DELIVERY, OTHER). Use to drive iconography and copy on the confirmation page (e.g. show the card icon for CARD, the BLIK logo for BLIK).
+  Category of the payment method on the order (CARD, BLIK, BANK_TRANSFER, INSTALLMENT, WALLET, CASH_ON_DELIVERY, OTHER). Use to drive iconography and copy on the confirmation page (e.g. show the card icon for CARD, the BLIK logo for BLIK, the wallet icon for WALLET — Apple Pay / Google Pay).
   """
   paymentMethodType: PaymentMethodType!
 
@@ -4163,39 +4538,39 @@ enum OrderFulfillmentStatus {
   UNFULFILLED
 }
 
-"""Pozycja zamówienia (line item) z variant snapshot i live enrichment"""
+"""Order line item with variant snapshot and live enrichment"""
 type OrderLineItem {
   """Unique identifier"""
   id: ID!
 
   """
-  Całkowita cena linii z momentu zakupu (unitPrice × quantity, minor units)
+  Line total captured at purchase time (unitPrice × quantity, minor units)
   """
   originalTotalPrice: Money!
 
   """
-  Cena jednostkowa z momentu zakupu (minor units, include BUNDLED surcharges)
+  Unit price captured at purchase time (minor units, includes BUNDLED surcharges)
   """
   originalUnitPrice: Money!
 
-  """Ilość zamówiona (snapshot z checkout)"""
+  """Quantity ordered (snapshot from checkout)"""
   quantity: Int!
 
-  """Ilość już zrealizowana (shipped — per-item fulfillment tracking)"""
+  """Quantity already fulfilled (shipped — per-item fulfillment tracking)"""
   quantityFulfilled: Int!
 
   """
-  Ilość pozostała do zwrotu/refund (quantity - returnedQuantity, clamp ≥ 0). Industry-standard semantyka dla refund tracking.
+  Quantity still eligible for return/refund (quantity − returnedQuantity, clamped ≥ 0). Industry-standard semantics for refund tracking.
   """
   refundableQuantity: Int!
 
   """
-  Nazwa produktu z momentu zakupu (snapshot). NIE live `Product.name` — preserved nawet po edycji produktu (KSeF/invoice compliance).
+  Product name captured at purchase time (snapshot). Not the live `Product.name` — preserved even after the product is edited (invoice compliance).
   """
   title: String!
 
   """
-  Live wariant produktu (fresh image/price). Null jeśli wariant został usunięty po zakupie — consumer powinien użyć `title` jako fallback.
+  Live product variant (fresh image/price). Null when the variant was deleted after purchase — consumers should fall back to `title`.
   """
   variant: ProductVariant
 }
@@ -4212,7 +4587,7 @@ type OrderLineItemConnection {
   pageInfo: PageInfo!
 
   """
-  Total count of line items in the order (convention parity z OrderConnection/MailingAddressConnection)
+  Total count of line items in the order (convention parity with OrderConnection/MailingAddressConnection)
   """
   totalCount: Int!
 }
@@ -4337,9 +4712,14 @@ type PaymentCreatePayload {
   payment: PaymentSession
 
   """
-  Business / validation errors carrying a stable `PaymentErrorCode` in `code` (e.g. `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `PAYMENT_FAILED`).
+  Business / validation errors carrying a stable `PaymentErrorCode` in `code` (e.g. `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `PAYMENT_FAILED`, `INSTRUMENT_PRESELECTION_FAILED`).
   """
   userErrors: [UserError!]!
+
+  """
+  Non-blocking signals — backend state change context (e.g. instrument auto-cleared, server-side adjustment). Default empty array. Storefront branches per `code` for UI retry hints / analytics events.
+  """
+  warnings: [PaymentWarning!]!
 }
 
 """
@@ -4352,25 +4732,96 @@ enum PaymentInitiationFlow {
   ONLINE_REDIRECT
 }
 
+"""
+A single concrete instrument exposed by a gateway provider (e.g. BLIK code, mBank Pay-By-Link, Apple Pay) within a broader PaymentMethod. Pass `code` as `preferredInstrument` in `cartSelectPaymentMethod` to deep-link the gateway straight to this screen.
+"""
+type PaymentInstrument {
+  """
+  Optional brand image (bank logo, wallet icon). Use as tile artwork via `brandImage { url(transform: { maxWidth: 64 }) altText }`. Null when the gateway does not expose one or the instrument has no brand visual (BLIK code).
+  """
+  brandImage: Image
+
+  """
+  Gateway-specific instrument identifier (PayU: `"blik"`/`"mb"`/`"c"`, P24: numeric ID string `"154"`). Pass as `preferredInstrument` in `cartSelectPaymentMethod`. Stable per provider — the gateway does not renumber.
+  """
+  code: String!
+
+  """
+  UX rendering hint — how the storefront should render this instrument (prominent button vs branded tile vs dropdown vs radio). Backend-agnostic mapping to visual treatment.
+  """
+  displayHint: PaymentInstrumentDisplayHint!
+
+  """
+  Buyer-facing display name (e.g. "BLIK", "mBank", "ING Bank Śląski", "Apple Pay").
+  """
+  displayName: String!
+
+  """
+  True when the instrument is currently enabled in the gateway live capabilities. The storefront can gray-out the tile when false instead of hiding it (observability for the merchant).
+  """
+  enabled: Boolean!
+
+  """
+  Provider that handles this instrument (UPPERCASE enum). Required for cross-provider dedupe (e.g. a BLIK code offered by both PayU and P24 — distinct instruments despite the same method type).
+  """
+  provider: PaymentProvider!
+
+  """
+  Semantic type classifying the instrument within the method (BLIK code vs bank vs wallet vs card brand). Storefront-facing dispatch for per-instrument UI components.
+  """
+  type: PaymentInstrumentType!
+}
+
+"""
+UX rendering hint for a payment instrument — the storefront can switch between prominent button / branded tile / dropdown / radio per hint. Backend-agnostic mapping to visual treatment.
+"""
+enum PaymentInstrumentDisplayHint {
+  BRANDED_TILE
+  DROPDOWN_OPTION
+  PROMINENT_BUTTON
+  RADIO_OPTION
+}
+
+"""
+Classifies a concrete instrument within a PaymentMethod (BLIK code vs bank vs wallet vs card brand). Storefront-facing typing for per-instrument UI dispatch.
+"""
+enum PaymentInstrumentType {
+  BANK
+  BLIK_CODE
+  CARD_BRAND
+  OTHER
+  WALLET
+}
+
 """
 A payment method offered to the buyer at checkout — what to render in the payment picker and pass to `cartSelectPaymentMethod`.
 """
 type PaymentMethod {
+  """
+  True when the buyer can actually pick this method right now. False when the resolving gateway is temporarily unavailable (incident/maintenance) or reported the method as disabled. Storefront UI should gray-out the tile when false instead of hiding it — gives merchants observability into routing failures.
+  """
+  available: Boolean!
+
   """
   Optional buyer-facing description shown under the name (e.g. "Pay with your bank app").
   """
   description: String
 
   """
-  Optional icon URL configured by the merchant. Use as the method tile artwork.
+  Optional icon image configured by the merchant. Use `icon { url(transform: { maxWidth: 64 }) altText }` as the method tile artwork in the payment picker.
   """
-  icon: String
+  icon: Image
 
   """
   Stable ID of the payment method. Pass to `cartSelectPaymentMethod` to select it.
   """
   id: ID!
 
+  """
+  Concrete instruments exposed by gateway providers within this method (BLIK code, branded banks, wallets, card brands). Null when no provider exposes granular data for this method. Empty array when a gateway exposes them but all instruments are disabled or removed by post-filtering (cross-provider leak prevention). Render the list and pass `code` as `preferredInstrument` in `cartSelectPaymentMethod` to deep-link the gateway to this screen.
+  """
+  instruments: [PaymentInstrument!]
+
   """
   True when the merchant has marked this method as the default. Pre-select it in the picker.
   """
@@ -4387,9 +4838,19 @@ type PaymentMethod {
   position: Float!
 
   """
-  Provider code (e.g. "payu", "stripe", "p24", "cash_on_delivery"). Identifies the integration behind the method; do not branch UI on it — use `type` instead.
+  Preferred provider (UPPERCASE enum) that the backend will route to when the buyer picks this method type and does not specify `preferredProvider`. Populated only when at least one provider supports the type.
   """
-  provider: String!
+  preferredProvider: PaymentProvider
+
+  """
+  Provider (e.g. `PAYU`, `STRIPE`, `PRZELEWY24`, `CASH_ON_DELIVERY`). Identifies the integration behind the method; do not branch UI on it — use `type` instead.
+  """
+  provider: PaymentProvider!
+
+  """
+  Providers (UPPERCASE enum: `PAYU`, `PRZELEWY24`, ...) that can fulfil this method type for the current shop, ordered by merchant priority. Pre-select `preferredProvider`; expose the rest only when the buyer wants to choose explicitly. Single-element array when only one provider supports the type.
+  """
+  providersAvailable: [PaymentProvider!]
 
   """
   ISO 4217 currency codes the method accepts. Null when the method accepts the shop currency without restriction.
@@ -4397,20 +4858,51 @@ type PaymentMethod {
   supportedCurrencies: [String!]
 
   """
-  Category of the method (CARD, BLIK, BANK_TRANSFER, CASH_ON_DELIVERY, OTHER). Drives iconography and copy.
+  Category of the method (CARD, BLIK, BANK_TRANSFER, INSTALLMENT, WALLET, CASH_ON_DELIVERY, OTHER). Drives iconography and copy.
   """
   type: PaymentMethodType!
+
+  """
+  When `available` is false, this enum carries the diagnostic reason (GATEWAY_DOWN, GATEWAY_DISABLED, NO_INSTRUMENTS, CREDENTIALS_INVALID). Null when `available` is true. UI can render context-aware copy ("PayU is temporarily down" vs "Method not configured").
+  """
+  unavailableReason: PaymentMethodUnavailableReason
 }
 
 """
-Category of a payment method: CARD, BLIK, BANK_TRANSFER, CASH_ON_DELIVERY or OTHER. Drives iconography and copy in the payment picker; do not branch on `provider` directly.
+Category of a payment method (CARD / BLIK / BANK_TRANSFER / INSTALLMENT / WALLET / CASH_ON_DELIVERY / OTHER). Drives iconography and copy in the payment picker; do not branch on `provider` directly — use this `type` instead.
 """
 enum PaymentMethodType {
   BANK_TRANSFER
   BLIK
   CARD
   CASH_ON_DELIVERY
+  INSTALLMENT
   OTHER
+  WALLET
+}
+
+"""
+Why a payment method is currently unavailable. GATEWAY_DOWN/DISABLED/NO_INSTRUMENTS are transient (gateway-side); CREDENTIALS_INVALID needs merchant action in the admin panel.
+"""
+enum PaymentMethodUnavailableReason {
+  CREDENTIALS_INVALID
+  GATEWAY_DISABLED
+  GATEWAY_DOWN
+  NO_INSTRUMENTS
+}
+
+"""
+Canonical payment provider identifier (UPPERCASE per GraphQL convention). Used for `Order.paymentProvider`, `Payment.provider`, `PaymentMethod.provider`, `PaymentMethod.providersAvailable`, `PaymentMethod.preferredProvider` and `CartSelectPaymentMethodInput.preferredProvider`. The set of gateways a shop can use is configurable — the values listed here are the providers the platform currently supports.
+"""
+enum PaymentProvider {
+  BANK_TRANSFER
+  CASH_ON_DELIVERY
+  GIFT_CARD
+  MANUAL_PAYMENT
+  PAYU
+  PRZELEWY24
+  STRIPE
+  TEST_GATEWAY
 }
 
 """
@@ -4456,21 +4948,50 @@ type PaymentSession {
 
 """Shop payment configuration (currency, country, providers)"""
 type PaymentSettings {
-  """Country code sklepu — driver dostępności metod płatności"""
+  """Shop country code — drives payment method availability"""
   countryCode: CountryCode!
 
-  """Primary currency użyty do procesowania płatności"""
+  """Primary currency used to process payments"""
   currencyCode: CurrencyCode!
 
-  """Waluty displayable on storefront (Money.currencyCode allowlist)"""
+  """
+  Currencies displayable on the storefront (Money.currencyCode allowlist)
+  """
   enabledPresentmentCurrencies: [CurrencyCode!]!
 
   """
-  Kody aktywnych payment providerów dla tego sklepu (z IntegrationProvider table, type=PAYMENT). Np. ["payu", "cash_on_delivery"]. Storefront-dev używa do warunkowania UI checkout.
+  Codes of the payment providers active for this shop. E.g. ["payu", "cash_on_delivery"]. Use to conditionally render the checkout UI.
   """
   paymentProviders: [String!]!
 }
 
+"""
+Non-blocking signal emitted alongside `userErrors` — backend state change context (e.g. an auto-clear, a server-side adjustment) that the storefront may surface as a retry hint or analytics event. Always pre-translated by backend per shop locale.
+"""
+type PaymentWarning {
+  """
+  Machine-readable code — branch on this to dispatch UI retry hints. Add a new code only when there is a distinct UX response.
+  """
+  code: PaymentWarningCode!
+
+  """
+  Pre-translated user-facing message describing what happened (Polish-first per shop locale).
+  """
+  message: String!
+
+  """
+  Optional additional hint string for UI dispatch — currently unused for `INSTRUMENT_CLEARED_FOR_RETRY` (semantic encoded in `message`). Reserved for future warning codes (e.g. `SLOW_GATEWAY_RESPONSE` → "Retry in 30s").
+  """
+  retryHint: String
+}
+
+"""
+Machine-readable code for `PaymentWarning.code`. Non-blocking signals from payment mutations — branch on this to dispatch UI retry hints. `INSTRUMENT_CLEARED_FOR_RETRY` indicates backend auto-cleared a preselected payment instrument after gateway rejection; next `paymentCreate` will land on the gateway default page.
+"""
+enum PaymentWarningCode {
+  INSTRUMENT_CLEARED_FOR_RETRY
+}
+
 """
 A pickup point (parcel locker or staffed collection point) attached to a delivery address. The buyer picks it in the carrier widget; it is persisted on the cart shipping address and carried through to the order.
 """
@@ -4603,23 +5124,28 @@ type Product implements Node {
   """
   Customer-facing product attributes (configurator) — set definitions + per-product scoped
   """
-  attributes(filter: ProductAttributeFilterInput): [ProductAttributeDefinition!]!
+  attributes(
+    """
+    Optional filter — pass `{ fillingMode: CUSTOMER }` to return only buyer-fillable configurator fields
+    """
+    filter: ProductAttributeFilterInput
+  ): [ProductAttributeDefinition!]!
 
   """Average rating (1-5)"""
   averageRating: Float
 
   """
-  Canonical brand entity (Faza 3, 2026-05-17). Resolved via DataLoader (N+1 safe dla list queries). Null gdy product nie ma przypisanego brand_id.
+  Canonical brand entity. Resolved via DataLoader (N+1 safe for list queries). Null when the product has no assigned brand.
   """
   brand: Brand
 
   """
-  Wszystkie kategorie do których produkt należy (M2M przez ProductCategory junction). Posortowane po junction.sortOrder ASC. Empty list gdy produkt nie jest w żadnej kategorii.
+  All categories the product belongs to (M2M via the ProductCategory junction). Sorted by junction.sortOrder ASC. Empty list when the product is in no category.
   """
   categories: [Category!]!
 
   """
-  Compare-at price range (Money pair). Null gdy żaden variant nie ma compareAtPrice.
+  Compare-at price range (Money pair). Null when no variant has a compareAtPrice.
   """
   compareAtPriceRange: ProductPriceRange
 
@@ -4645,7 +5171,25 @@ type Product implements Node {
   id: ID!
 
   """Product images (Relay Connection)"""
-  images(after: String, before: String, first: Float, last: Float): ImageConnection!
+  images(
+    """
+    Cursor for forward pagination (cursor of the last edge from the previous page)
+    """
+    after: String
+
+    """
+    Cursor for backward pagination (cursor of the first edge from the next page)
+    """
+    before: String
+
+    """
+    Number of images to return from the start (forward pagination, default 10, max 100)
+    """
+    first: Float
+
+    """Number of images to return from the end (backward pagination, max 100)"""
+    last: Float
+  ): ImageConnection!
 
   """Whether product is available for sale (any variant in stock)"""
   isAvailable: Boolean!
@@ -4664,17 +5208,20 @@ type Product implements Node {
   priceRange: ProductPriceRange!
 
   """
-  Opt-in: price range with full conversion transparency (exchangeRate, baseCurrency, isConverted). Use dla currency-converter UI gdy customer ma preferred currency inną niż shop base.
+  Opt-in: price range with full conversion transparency (exchangeRate, baseCurrency, isConverted). Use for a currency-converter UI when the customer has a preferred currency different from the shop base.
   """
   priceRangeWithConversion: ConvertedPriceRange
 
   """
-  Domyślna kategoria dla breadcrumb/nav (= categories[0] po sortOrder). Null gdy produkt nie jest w żadnej kategorii.
+  Default category for breadcrumb/nav (= categories[0] by sortOrder). Null when the product is in no category.
   """
   primaryCategory: Category
 
   """Similar products recommendations"""
-  recommendations(first: Int = 4): ProductRecommendations
+  recommendations(
+    """Number of similar products to return (default 4, max 100)"""
+    first: Int = 4
+  ): ProductRecommendations
 
   """Number of reviews"""
   reviewCount: Int
@@ -4700,14 +5247,34 @@ type Product implements Node {
   updatedAt: DateTime!
 
   """Product variants (Relay Connection)"""
-  variants(after: String, before: String, first: Float, last: Float): ProductVariantConnection!
+  variants(
+    """
+    Cursor for forward pagination (cursor of the last edge from the previous page)
+    """
+    after: String
+
+    """
+    Cursor for backward pagination (cursor of the first edge from the next page)
+    """
+    before: String
+
+    """
+    Number of variants to return from the start (forward pagination, max 100)
+    """
+    first: Float
+
+    """
+    Number of variants to return from the end (backward pagination, max 100)
+    """
+    last: Float
+  ): ProductVariantConnection!
 
   """
-  Legacy vendor/brand name (free-text). Preferred: `brand` field (canonical Brand entity, Faza 3).
+  Legacy vendor/brand name (free-text). Preferred: `brand` field (canonical Brand entity).
   """
   vendor: String
 
-  """Catalog visibility (Faza 1.5) — PUBLIC | HIDDEN | BUNDLE_ONLY"""
+  """Catalog visibility — PUBLIC | HIDDEN | BUNDLE_ONLY"""
   visibility: ProductVisibility!
 }
 
@@ -4784,12 +5351,12 @@ type ProductAttributeOption {
   label: String!
 
   """
-  Summary powiązanego ProductVariant (Faza 1.5). Null gdy option nie ma linkedVariantId albo wariant został usunięty.
+  Summary of the linked ProductVariant. Null when the option has no linkedVariantId or the variant was deleted.
   """
   linkedVariant: LinkedVariantSummary
 
   """
-  Linked ProductVariant ID for component stock decrement (Faza 1.5 — Hidden Products pattern)
+  Linked ProductVariant ID for component stock decrement (hidden-products pattern).
   """
   linkedVariantId: ID
 
@@ -4797,11 +5364,11 @@ type ProductAttributeOption {
   sortOrder: Int!
 
   """
-  Surcharge amount when selected (FIXED = grosze; PERCENT = thousandths of percent — Faza 2)
+  Surcharge amount when selected (FIXED = minor currency units; PERCENT = thousandths of percent).
   """
   surchargeAmount: Int
 
-  """Surcharge type — FIXED | PERCENT (Faza 2)"""
+  """Surcharge type — FIXED | PERCENT."""
   surchargeType: AttributeOptionSurchargeType
 
   """Internal value (slug-style)"""
@@ -4840,7 +5407,7 @@ type ProductEdge {
 """Single product filter"""
 input ProductFilter {
   """
-  DoSwiftly: dynamic attribute filters (configurator + custom fields system). Optional `namespace` w AttributeFilterInput dyskryminuje per grupa atrybutów.
+  DoSwiftly: dynamic attribute filters (configurator + custom fields system). Optional `namespace` in AttributeFilterInput discriminates per attribute group.
   """
   attributes: [AttributeFilterInput!]
 
@@ -4848,7 +5415,7 @@ input ProductFilter {
   available: Boolean
 
   """
-  Faza 3 (2026-05-17): filter by canonical Brand entity. Wybierz po `slug` (URL-stable) lub `id` (raw UUID). Multiple `brand` entries w `filters[]` array = OR semantics. Vendor (legacy free-text) wciąż wspierany via `productVendor`.
+  Filter by canonical Brand entity. Choose by `slug` (URL-stable) or `id` (raw UUID). Multiple `brand` entries in the `filters[]` array = OR semantics. Vendor (legacy free-text) is still supported via `productVendor`.
   """
   brand: BrandFilter
 
@@ -4974,8 +5541,10 @@ type ProductReview {
   helpfulCount: Int!
   id: ID!
 
-  """Review images"""
-  images: [String!]!
+  """
+  Review image attachments uploaded by the reviewer. Use `images { url(transform: { maxWidth: 600 }) altText }` for responsive gallery rendering in the review card.
+  """
+  images: [Image!]!
 
   """Is verified purchase"""
   isVerifiedPurchase: Boolean!
@@ -5042,7 +5611,12 @@ A purchasable unit of a product — one variant out of the product variants list
 """
 type ProductVariant {
   """Variant custom field values (post-Opcja A unified custom fields)."""
-  attributes(namespace: String): [EntityAttributeField!]!
+  attributes(
+    """
+    Optional namespace filter (e.g. "erp", "b2b") to return only attributes with matching prefix
+    """
+    namespace: String
+  ): [EntityAttributeField!]!
 
   """
   Available stock — what the buyer can buy now (on-hand minus active reservations, never below 0). Null when the merchant has disabled stock tracking for this variant (e.g. digital, made-to-order).
@@ -5103,7 +5677,7 @@ type ProductVariant {
   sortOrder: Int
 
   """
-  Per-location stock availability. Null for single-location shops. Resolved by StoreAvailabilityResolver with `near`, `locationType`, and `@inContext(preferredLocationId)` support.
+  Per-location stock availability. Null for single-location shops. Resolved per-location with `near`, `locationType`, and `@inContext(preferredLocationId)` support.
   """
   storeAvailability(
     """Cursor for pagination"""
@@ -5154,7 +5728,7 @@ type ProductVariantEdge {
   node: ProductVariant!
 }
 
-"""Catalog placement — PUBLIC | HIDDEN | BUNDLE_ONLY (Faza 1.5)"""
+"""Catalog placement — PUBLIC | HIDDEN | BUNDLE_ONLY"""
 enum ProductVisibility {
   BUNDLE_ONLY
   HIDDEN
@@ -5166,25 +5740,58 @@ type Query {
   allSupportedCurrencies: [Currency!]!
 
   """
-  Paginated + searchable attribute options dla drill-into filter UI (np. dropdown z 800 licencjami + search input). Honors product context z exclude-self per attribute. Sort: COUNT_DESC default (most popular first), LABEL_ASC dla alfabetycznego z polskim collation.
+  Paginated + searchable attribute options for a drill-into filter UI (e.g. a dropdown of 800 licenses + search input). Honors product context with exclude-self per attribute. Sort: COUNT_DESC default (most popular first), LABEL_ASC for alphabetical (Polish collation).
   """
-  attributeOptionsSearch(input: AttributeOptionsSearchInput!): AttributeFilterValueConnection!
+  attributeOptionsSearch(
+    """
+    Search payload (handle, search query, pagination, sort COUNT_DESC/LABEL_ASC, optional product context)
+    """
+    input: AttributeOptionsSearchInput!
+  ): AttributeFilterValueConnection!
 
   """
-  Payment methods active for the current shop, plus the merchant default. Shop-level — independent of cart contents in this iteration. Fetch once for the checkout payment step.
+  Payment methods active for the current shop, plus the merchant default. Returns one row per `PaymentMethodType` (BLIK, CARD, BANK_TRANSFER, ...) with `providersAvailable` (provider codes sorted by merchant priority) and `preferredProvider` (the head of the list). Shop-level — independent of cart contents.
   """
   availablePaymentMethods: AvailablePaymentMethods!
 
   """
   Standalone shipping-method preview for an address — does not require a cart. Pass an optional `cart` summary (subtotal, weight, currency) to evaluate price-based / weight-based rules and free-shipping thresholds. For an already-created cart, prefer `cart.availableShippingMethods(address)` — it reads the cart contents directly.
   """
-  availableShippingMethods(address: ShippingAddressInput!, cart: CartShippingInput): AvailableShippingMethodsPayload!
+  availableShippingMethods(
+    """Delivery address used to match shipping zones"""
+    address: ShippingAddressInput!
+
+    """
+    Optional cart summary (subtotal, weight, currency) for price/weight rules
+    """
+    cart: CartShippingInput
+  ): AvailableShippingMethodsPayload!
 
   """Get live shipping rates from configured carriers"""
-  availableShippingRates(address: ShippingAddressInput!, packages: [PackageDimensionsInput!], totalWeight: Float): AvailableShippingRatesPayload!
+  availableShippingRates(
+    """Recipient address sent to carrier APIs for rate quotes"""
+    address: ShippingAddressInput!
+
+    """
+    Package dimensions (weight + length/width/height) for accurate rate calculation
+    """
+    packages: [PackageDimensionsInput!]
+
+    """Total cart weight in kilograms (fallback when packages omitted)"""
+    totalWeight: Float
+  ): AvailableShippingRatesPayload!
 
   """Get B2B pricing for a product variant"""
-  b2bPricing(quantity: Float = 1, retailPrice: Float!, variantId: ID!): B2BPriceDisplay
+  b2bPricing(
+    """Quantity for volume tier evaluation (default 1)"""
+    quantity: Float = 1
+
+    """Retail price in minor units (e.g. 9999 = 99.99 PLN)"""
+    retailPrice: Float!
+
+    """Product variant UUID to price"""
+    variantId: ID!
+  ): B2BPriceDisplay
 
   """List blog categories"""
   blogCategories: [BlogCategory!]!
@@ -5226,20 +5833,32 @@ type Query {
   ): BlogPostConnection!
 
   """List blog tags"""
-  blogTags(limit: Int = 50): [BlogTag!]!
+  blogTags(
+    """Maximum number of tags to return (default 50, max 200)"""
+    limit: Int = 50
+  ): [BlogTag!]!
 
   """
   Fetch a cart by ID — returns null when the cart does not exist or has already been completed (converted to an order). Use to hydrate the cart state on page load or after a recovery flow.
   """
-  cart(id: ID!): Cart
+  cart(
+    """Cart UUID to fetch"""
+    id: ID!
+  ): Cart
 
   """
   Preview whether a discount code is currently applicable to a cart — read-only, no cart side effects. Use for inline feedback while the buyer types a code, before calling `cartDiscountCodesUpdate`. Result depends on the cart subtotal (minimum-order rules) so do not cache aggressively: prefer `fetchPolicy: "network-only"` or include `cart.subtotal` in the cache key.
   """
-  cartValidateDiscountCode(cartId: ID!, discountCode: String!): DiscountValidationResult!
+  cartValidateDiscountCode(
+    """Cart UUID to validate the discount code against"""
+    cartId: ID!
+
+    """Discount code to preview (case-insensitive)"""
+    discountCode: String!
+  ): DiscountValidationResult!
 
   """
-  Lista kategorii (Relay Connection) z opcjonalnym filtrem rootsOnly/parentId
+  List of categories (Relay Connection) with optional rootsOnly/parentId filtering
   """
   categories(
     """Forward pagination cursor (after this element)"""
@@ -5255,7 +5874,7 @@ type Query {
     last: Int
 
     """
-    Filter by parent category ID — używaj `null` semantically dla "roots" via `rootsOnly` flag
+    Filter by parent category ID — use `null` semantically for "roots" via the `rootsOnly` flag
     """
     parentId: ID
 
@@ -5331,11 +5950,16 @@ type Query {
   """
   Fetch a single order owned by the authenticated customer. Returns null silently when there is no authenticated customer or the order does not belong to them. For guest order access use `orderByToken` instead.
   """
-  customerOrder(orderId: ID!): Order
+  customerOrder(
+    """Order UUID owned by the authenticated customer"""
+    orderId: ID!
+  ): Order
 
   """Estimate points for an order amount"""
   estimatePoints(
-    """Order total in major currency units (e.g., PLN)"""
+    """
+    Order total in major currency units (e.g. 99.99 PLN) to estimate earned points for
+    """
     orderTotal: Float!
   ): PointsEstimate!
 
@@ -5349,19 +5973,30 @@ type Query {
   ): ExchangeRate
 
   """Get gift card by code (null if not found)"""
-  giftCard(code: String!): GiftCard
+  giftCard(
+    """Gift card code to look up (case-sensitive)"""
+    code: String!
+  ): GiftCard
 
   """Validate gift card for use"""
-  giftCardValidate(amount: Float, code: String!): GiftCardValidatePayload!
+  giftCardValidate(
+    """Optional amount in major units to check balance sufficiency"""
+    amount: Float
+
+    """Gift card code to validate"""
+    code: String!
+  ): GiftCardValidatePayload!
 
   """Get available languages for this shop"""
   languages: [Language!]!
 
-  """Localization context (kraje, języki, aktualny kraj/język klienta)"""
+  """
+  Localization context (countries, languages, the customer current country/language)
+  """
   localization: Localization!
 
   """
-  Fetch a single active location by ID. Returns null when missing, inactive, or owned by another shop (tenant isolation via StorefrontShopGuard).
+  Fetch a single active location by ID. Returns null when missing, inactive, or owned by another shop (tenant isolation enforced server-side).
   """
   location(
     """Location UUID"""
@@ -5401,18 +6036,47 @@ type Query {
   loyaltyTiers: [LoyaltyTier!]!
 
   """Get loyalty transaction history"""
-  loyaltyTransactions(after: String, first: Int = 20): LoyaltyTransactionConnection!
+  loyaltyTransactions(
+    """
+    Cursor for forward pagination (cursor of the last edge from the previous page)
+    """
+    after: String
+
+    """
+    Number of transactions to return from the start (forward pagination, max 100)
+    """
+    first: Int = 20
+  ): LoyaltyTransactionConnection!
 
   """Get a navigation menu by handle"""
-  menu(handle: String!): Menu
+  menu(
+    """
+    Navigation menu handle (e.g. "main-menu", "footer") configured in admin
+    """
+    handle: String!
+  ): Menu
 
   """Universal ID-based lookup (Relay Node spec)"""
-  node(id: ID!, type: NodeType!): Node
+  node(
+    """Global object UUID to fetch"""
+    id: ID!
+
+    """
+    NodeType discriminator (PRODUCT / COLLECTION / CART / CUSTOMER / ORDER)
+    """
+    type: NodeType!
+  ): Node
 
   """
-  Batch ID-based lookup; same NodeType dla all IDs. Missing/wrong IDs → null entries (preserved length).
+  Batch ID-based lookup; same NodeType for all IDs. Missing/wrong IDs → null entries (preserved length).
   """
-  nodes(ids: [ID!]!, type: NodeType!): [Node]!
+  nodes(
+    """List of UUIDs to fetch (all must be the same NodeType)"""
+    ids: [ID!]!
+
+    """NodeType discriminator applied to every id in the batch"""
+    type: NodeType!
+  ): [Node]!
 
   """
   Fetch a single order by its opaque access token (guest order access without a session). Optional `email` argument enables defense-in-depth: if provided, must match the order buyer email (case-insensitive); on mismatch the query returns null exactly like an invalid token. Rate-limited to 5 requests per minute per IP+shop. Response carries Cache-Control: no-store.
@@ -5455,7 +6119,10 @@ type Query {
   ): ShopPageConnection!
 
   """Get personalized product recommendations for the current customer"""
-  personalizedRecommendations(first: Int = 10): ProductRecommendations!
+  personalizedRecommendations(
+    """Number of recommendations to return (default 10, max 100)"""
+    first: Int = 10
+  ): ProductRecommendations!
 
   """Get single product by ID or handle"""
   product(
@@ -5469,7 +6136,12 @@ type Query {
   """
   Get available filters for product listing (renamed from availableFilters in Storefront 5.0)
   """
-  productFilters(input: AvailableFiltersInput): AvailableFilters!
+  productFilters(
+    """
+    Product context (collectionId/categoryId/searchQuery) + currently applied filters for exclude-self facet counts
+    """
+    input: AvailableFiltersInput
+  ): AvailableFilters!
 
   """Get recommended products similar to the given product"""
   productRecommendations(
@@ -5519,16 +6191,25 @@ type Query {
   referralStats: ReferralStats
 
   """Get return by ID"""
-  return(id: ID!): ReturnPayload!
+  return(
+    """Return UUID to fetch (customer-owned, ownership verified)"""
+    id: ID!
+  ): ReturnPayload!
 
   """Get available return reasons"""
   returnReasons: [ReturnReasonOption!]!
 
   """Get returns for an order"""
-  returnsByOrder(orderId: ID!): ReturnConnection!
+  returnsByOrder(
+    """Order UUID to list returns for (ownership verified)"""
+    orderId: ID!
+  ): ReturnConnection!
 
   """Get product review statistics"""
-  reviewStats(productId: ID!): ReviewStats!
+  reviewStats(
+    """Product UUID to fetch review statistics for"""
+    productId: ID!
+  ): ReviewStats!
 
   """Search products (DoSwiftly alias for products() with required query)"""
   searchProducts(
@@ -5563,10 +6244,16 @@ type Query {
   ): PredictiveSearchResult!
 
   """Get shipment by ID"""
-  shipment(id: ID!): ShipmentPayload!
+  shipment(
+    """Shipment UUID (customer must own parent order)"""
+    id: ID!
+  ): ShipmentPayload!
 
   """Get shipment by tracking number"""
-  shipmentByTrackingNumber(trackingNumber: String!): ShipmentPayload!
+  shipmentByTrackingNumber(
+    """Carrier tracking number (public lookup, no auth required)"""
+    trackingNumber: String!
+  ): ShipmentPayload!
 
   """Get current shop information"""
   shop: Shop!
@@ -5575,7 +6262,12 @@ type Query {
   shopCurrencyConfig: ShopCurrencyConfig!
 
   """Get translations for a language"""
-  translations(input: TranslationsInput!): Translations!
+  translations(
+    """
+    Translation request (language code, optional namespaces filter) — falls back to shop default language
+    """
+    input: TranslationsInput!
+  ): Translations!
 
   """List URL redirects"""
   urlRedirects(
@@ -5795,8 +6487,10 @@ type ReturnItem {
   """Item ID"""
   id: ID!
 
-  """Product image URL"""
-  imageUrl: String
+  """
+  Product image at time of return submission. Use `image { url(transform: { maxWidth: ... }) altText }` for responsive thumbnails in the merchant return dashboard.
+  """
+  image: Image
 
   """Evidence photos"""
   photos: [ReturnItemPhoto!]
@@ -6103,8 +6797,10 @@ type ShipmentItem {
   """Item ID"""
   id: ID!
 
-  """Product image URL"""
-  imageUrl: String
+  """
+  Live variant image with snapshot fallback. Use `image { url(transform: { maxWidth: 200, preferredContentType: WEBP }) altText }` for responsive thumbnails. Returns `null` when the variant has been deleted since fulfillment — render a placeholder client-side.
+  """
+  image: Image
 
   """Quantity shipped"""
   quantity: Int!
@@ -6202,9 +6898,9 @@ type ShippingCarrier {
   id: ID
 
   """
-  URL of the carrier logo. Use for the method tile in the shipping picker.
+  Carrier logo image. Use `logo { url(transform: { maxWidth: 64 }) altText }` for the method tile in the shipping picker.
   """
-  logoUrl: String
+  logo: Image
 
   """Carrier display name (e.g. "InPost", "DPD", "DHL")."""
   name: String!
@@ -6246,7 +6942,7 @@ type Shop {
   """Default currency code (ISO 4217)"""
   currencyCode: CurrencyCode!
 
-  """Customer account URL (login/orders) — z primaryDomain"""
+  """Customer account URL (login/orders) — derived from primaryDomain"""
   customerAccountUrl: URL
 
   """Default language code (ISO 639-1)"""
@@ -6268,7 +6964,7 @@ type Shop {
   logo: Image
 
   """
-  Money display format z `{{amount}}` placeholder, np. "{{amount}} zł"
+  Money display format with the `{{amount}}` placeholder, e.g. "{{amount}} zł"
   """
   moneyFormat: String!
 
@@ -6574,8 +7270,10 @@ type TierBenefit {
   """Benefit description"""
   description: String
 
-  """Benefit icon"""
-  icon: String
+  """
+  Benefit icon image. Use `icon { url(transform: { maxWidth: 48 }) altText }` for small visual markers on the tier benefits list.
+  """
+  icon: Image
 
   """Benefit name"""
   name: String!
@@ -6640,7 +7338,7 @@ URL string per RFC 3986 (e.g. "https://shop.example.com/products/foo").
 """
 scalar URL
 
-"""Measurement system (metric vs imperial) — wpływa na display formats"""
+"""Measurement system (metric vs imperial) — affects display formats"""
 enum UnitSystem {
   IMPERIAL_SYSTEM
   METRIC_SYSTEM