@doswiftly/storefront-operations 13.1.0 → 15.1.0

package/schema.graphql

@@ -32,12 +32,14 @@ directive @inContext(
   preferredLocationId: ID
 ) on MUTATION | QUERY | SUBSCRIPTION
 
-"""Generic attribute"""
+"""
+A generic key/value attribute — used for line item properties and other free-form metadata.
+"""
 type Attribute {
-  """Attribute key"""
+  """Attribute key."""
   key: String!
 
-  """Attribute value"""
+  """Attribute value. Null when the key is set without an associated value."""
   value: String
 }
 
@@ -63,7 +65,9 @@ type AttributeDefinition {
   """Attribute ID"""
   id: ID!
 
-  """Whether attribute is filterable"""
+  """
+  Whether attribute is filterable (admin toggle). For storefront UI rendering signal use `isUsableAsFilter` (computed).
+  """
   isFilterable: Boolean!
 
   """Whether attribute is visible on product pages"""
@@ -140,6 +144,34 @@ type AttributeFilterValue {
   value: String!
 }
 
+"""Paginated + searchable attribute options (Relay Connection)"""
+type AttributeFilterValueConnection {
+  """Paginated edges z cursorami"""
+  edges: [AttributeFilterValueEdge!]!
+
+  """Shortcut: edges.map(e => e.node)"""
+  nodes: [AttributeFilterValue!]!
+
+  """Relay pagination info (hasNextPage, hasPreviousPage, cursors)"""
+  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.
+  """
+  totalCount: Int!
+}
+
+"""Edge w AttributeFilterValueConnection (Relay spec)"""
+type AttributeFilterValueEdge {
+  """
+  Opaque pagination cursor (base64-encoded). Echo as `after` for next page.
+  """
+  cursor: String!
+
+  """Attribute filter value (option + product count + swatch)"""
+  node: AttributeFilterValue!
+}
+
 """Attribute input"""
 input AttributeInput {
   """Attribute key"""
@@ -157,6 +189,37 @@ enum AttributeOptionSurchargeType {
   PERCENT
 }
 
+"""Input dla attributeOptionsSearch query"""
+input AttributeOptionsSearchInput {
+  """Opaque cursor z pageInfo.endCursor poprzedniej strony"""
+  after: String
+
+  """
+  Produktowy kontekst (categoryId/collectionId/searchQuery/currentFilters) dla accurate productCount. Exclude-self: gdy currentFilters zawiera ten sam atrybut, jest pomijany.
+  """
+  contextInput: AvailableFiltersInput
+
+  """Liczba zwracanych opcji (default 50, max 100)"""
+  first: Int
+
+  """Attribute handle (URL-friendly identifier, np. "licencja")"""
+  handle: String!
+
+  """Wyszukiwanie po value/label (case-insensitive ILIKE, max 100 znaków)"""
+  search: String
+
+  """
+  Sort — COUNT_DESC default (most popular first), LABEL_ASC dla alphabetical
+  """
+  sort: AttributeOptionsSearchSort
+}
+
+"""Sort order for attributeOptionsSearch results"""
+enum AttributeOptionsSearchSort {
+  COUNT_DESC
+  LABEL_ASC
+}
+
 """Min/max bounds for numeric attributes"""
 type AttributeRangeBounds {
   """Currency code for CURRENCY type"""
@@ -169,64 +232,88 @@ type AttributeRangeBounds {
   min: Float
 }
 
-"""Typed snapshot of customer-filled attribute selection (Faza 1 R5)"""
+"""
+A configurator selection that the buyer filled in on a line item — typed snapshot taken at add-to-cart and frozen on the resulting order. Distinct from `CartLine.attributes` (free-form key/value line item properties): selections are validated against the product attribute definition, carry pricing surcharges and can link to a hidden component variant.
+"""
 type AttributeSelection {
-  """AttributeDefinition ID (snapshot at addItem)"""
+  """ID of the attribute definition this selection refers to."""
   attributeDefinitionId: ID!
 
-  """AttributeDefinition name (snapshot)"""
+  """Display name of the attribute at the moment it was added to the cart."""
   attributeName: String!
 
-  """Billing mode; null = informational only"""
+  """
+  How the surcharge is charged: BUNDLED (folded into the line unit price) or SEPARATE_LINE (its own line on the order). Null when the selection is informational and has no surcharge.
+  """
   billingMode: AttributeBillingMode
 
-  """Filling mode (snapshot)"""
+  """
+  Who supplies the value: MERCHANT (set on the product), CUSTOMER (filled at add-to-cart) or BOTH.
+  """
   fillingMode: AttributeFillingMode!
 
-  """Linked ProductVariant ID for component stock (Faza 1.5)"""
+  """
+  Linked variant whose stock is decremented when this option is chosen — used by the hidden-product configurator pattern (e.g. finish, accessory). Null when no component stock is tied to the selection.
+  """
   linkedVariantId: ID
 
-  """Selected option ID (SELECT/RADIO/CHECKBOX)"""
+  """
+  Selected option ID for single-choice types (SELECT, RADIO, single-CHECKBOX).
+  """
   optionId: ID
 
-  """Selected option IDs (MULTI_SELECT — Faza 2)"""
+  """
+  Selected option IDs for multi-choice types (MULTI_SELECT, CHECKBOX list).
+  """
   optionIds: [ID!]
 
-  """Selected option label (snapshot)"""
+  """Display label of the selected option at the moment of selection."""
   optionLabel: String
 
   """
-  Surcharge amount snapshot (FIXED = grosze; PERCENT = thousandths of percent)
+  Surcharge attached to this selection in minor units of the shop currency when `surchargeType` is FIXED; thousandths of a percent (per mille of a percent) when PERCENT. Already reflected in the line cost.
   """
   surchargeAmount: Int!
 
-  """Surcharge type (snapshot)"""
+  """
+  How the surcharge is calculated — FIXED (absolute amount) or PERCENT. Null when the selection has no surcharge.
+  """
   surchargeType: AttributeOptionSurchargeType
 
-  """Tax class ID (snapshot); null = inherit from variant"""
+  """
+  Tax class applied to this selection. Null means the line inherits its tax class from the variant.
+  """
   taxClassId: ID
 
-  """Free-text value (TEXT/TEXTAREA/NUMBER/DATE)"""
+  """Free-text value for TEXT, TEXTAREA, NUMBER or DATE attribute types."""
   textValue: String
 
-  """AttributeDefinition type (snapshot)"""
+  """
+  Attribute data type (TEXT, SELECT, RADIO, CHECKBOX, NUMBER, DATE, COLOR, etc.). Drives which value field is populated.
+  """
   type: AttributeType!
 }
 
 """
-Customer-filled attribute selection (Faza 1 R5 — server-side validated)
+A configurator selection on a cart line — server-side validated against the product attribute definition. The value goes into one of `optionId`, `optionIds` or `textValue` depending on the attribute type.
 """
 input AttributeSelectionInput {
-  """AttributeDefinition ID"""
+  """ID of the attribute definition this selection refers to."""
   attributeDefinitionId: ID!
 
-  """Selected option ID for SELECT/RADIO/CHECKBOX"""
+  """
+  Selected option ID for single-choice attribute types (SELECT, RADIO, single-CHECKBOX).
+  """
   optionId: ID
 
-  """Selected option IDs for MULTI_SELECT (Faza 2)"""
+  """
+  Selected option IDs for multi-choice attribute types (MULTI_SELECT, CHECKBOX list).
+  """
   optionIds: [ID!]
 
-  """Free-text value for TEXT/TEXTAREA/NUMBER/DATE"""
+  """
+  Free-text value for TEXT, TEXTAREA, NUMBER or DATE attribute types (max 2000 chars).
+  """
   textValue: String
 }
 
@@ -271,7 +358,7 @@ type AvailableFilters {
   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: {slug}}]`. Tylko brandy z >0 produktów w current product set + isActive=true.
+  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.
   """
   brands: [BrandFilterValue!]
 
@@ -309,54 +396,89 @@ input AvailableFiltersInput {
   searchQuery: String
 }
 
-"""Available payment methods for checkout"""
+"""
+Result of `availablePaymentMethods` — the methods to render in the payment picker plus the merchant default.
+"""
 type AvailablePaymentMethods {
-  """Default payment method"""
+  """
+  Method marked as the merchant default — pre-select in the picker. Null when no default is configured.
+  """
   defaultMethod: PaymentMethod
 
-  """List of available payment methods"""
+  """Payment methods active for the shop, sorted by `position`."""
   methods: [PaymentMethod!]!
 }
 
-"""Available shipping method"""
+"""
+A shipping method offered to the buyer for the current cart and destination — what to render in the shipping picker.
+"""
 type AvailableShippingMethod {
-  """Carrier information"""
+  """
+  Carrier behind the method. Null when the merchant configured a custom non-carrier method.
+  """
   carrier: ShippingCarrier
 
-  """Method description"""
+  """
+  Destination type — HOME (courier to the street address), PICKUP_POINT (staffed counter) or LOCKER (parcel locker). Drives whether the storefront must render a pickup-point picker for the method instead of inferring it from the method name.
+  """
+  deliveryType: DeliveryType!
+
+  """
+  Optional method description shown under the name (e.g. "Saturday delivery available").
+  """
   description: String
 
-  """Estimated delivery time"""
+  """
+  Estimated delivery window. Null when the merchant has not configured an estimate for this method.
+  """
   estimatedDelivery: DeliveryEstimate
 
-  """Free shipping progress if threshold exists"""
+  """
+  Progress towards the free-shipping threshold for this method, when one is configured. Null otherwise.
+  """
   freeShippingProgress: FreeShippingProgress
 
-  """Shipping method ID (used as handle for selection)"""
+  """
+  Stable ID of the shipping method. Pass to `cartSelectShippingMethod` to select it.
+  """
   id: ID!
 
-  """Whether shipping is free"""
+  """
+  True when the price is zero — the method is free for this cart (e.g. free-shipping threshold met).
+  """
   isFree: Boolean!
 
-  """Method name"""
+  """Display name of the method (e.g. "DPD Standard")."""
   name: String!
 
-  """Shipping price"""
+  """
+  Cost of the method for the current cart (in the buyer preferred currency).
+  """
   price: Money!
 
-  """Sort order for display"""
+  """
+  Merchant-configured display position — lower values come first in the picker.
+  """
   sortOrder: Int!
 }
 
-"""Available shipping methods result"""
+"""
+Result of `availableShippingMethods` / `cart.availableShippingMethods` — the methods to render plus optional free-shipping progress and any user errors.
+"""
 type AvailableShippingMethodsPayload {
-  """Best free shipping progress across all methods"""
+  """
+  Best free-shipping progress across all returned methods. Use to render a single banner above the picker.
+  """
   freeShippingProgress: FreeShippingProgress
 
-  """Available shipping methods"""
+  """
+  Methods available for the current cart and destination, sorted by `sortOrder`.
+  """
   methods: [AvailableShippingMethod!]!
 
-  """User errors"""
+  """
+  Validation / availability errors — e.g. `DIGITAL_ONLY_NO_SHIPPING` when the cart contains only non-physical items. Branch on `code`.
+  """
   userErrors: [UserError!]!
 }
 
@@ -431,6 +553,9 @@ type BlogCategory {
   """Category description"""
   description: String
 
+  """URL-friendly handle"""
+  handle: String!
+
   """Category ID"""
   id: ID!
 
@@ -445,9 +570,6 @@ type BlogCategory {
 
   """SEO metadata"""
   seo: SEO
-
-  """URL-friendly slug"""
-  slug: String!
 }
 
 """Blog post"""
@@ -479,6 +601,9 @@ type BlogPost {
   """Featured image"""
   featuredImage: Image
 
+  """URL-friendly handle"""
+  handle: String!
+
   """Post ID"""
   id: ID!
 
@@ -494,9 +619,6 @@ type BlogPost {
   """SEO metadata"""
   seo: SEO
 
-  """URL-friendly slug"""
-  slug: String!
-
   """Post status"""
   status: BlogPostStatus!
 
@@ -552,6 +674,9 @@ enum BlogPostStatus {
 
 """Blog tag"""
 type BlogTag {
+  """URL-friendly handle"""
+  handle: String!
+
   """Tag ID"""
   id: ID!
 
@@ -560,9 +685,6 @@ type BlogTag {
 
   """Number of posts with this tag"""
   postCount: Int!
-
-  """URL-friendly slug"""
-  slug: String!
 }
 
 """Bot protection configuration (platform-level)"""
@@ -589,25 +711,21 @@ type BotProtectionProviderInfo {
   siteKey: String!
 }
 
-"""Shop brand metadata (logo, colors, slogan)"""
+"""
+Canonical product brand entity (np. Funko, Nike). Distinct od ShopBrand (shop branding metadata).
+"""
 type Brand {
-  """Primary + secondary brand colors"""
-  colors: BrandColors
-
-  """Cover image / hero banner"""
-  coverImage: Image
-
-  """Primary logo"""
-  logo: Image
+  """URL-friendly handle (e.g. "funko" → /brands/funko). Stable per-shop."""
+  handle: String!
 
-  """Short brand description"""
-  shortDescription: String
+  """Brand unique identifier"""
+  id: ID!
 
-  """Marketing slogan / tagline"""
-  slogan: String
+  """Brand logo URL (CDN-served, storefront-rendered)"""
+  logo: String
 
-  """Square logo variant (favicons, app tiles)"""
-  squareLogo: Image
+  """Brand display name (e.g. "Funko", "Nintendo")"""
+  name: String!
 }
 
 """Single brand color group (background + foreground hex)"""
@@ -627,17 +745,20 @@ type BrandColors {
 
 """Filter products po brand (canonical entity)"""
 input BrandFilter {
-  """Brand ID — exact UUID match"""
-  id: ID
-
   """
-  Brand slug — URL-friendly identifier. Preferowany over `id` dla storefront refetch (stable po URL share).
+  Brand handle — URL-friendly identifier. Preferowany over `id` dla storefront refetch (stable po URL share).
   """
-  slug: String
+  handle: String
+
+  """Brand ID — exact UUID match"""
+  id: ID
 }
 
 """Brand filter value z product count"""
 type BrandFilterValue {
+  """Brand handle (refetch payload — paste w ProductFilter.brand.handle)"""
+  handle: String!
+
   """Brand ID"""
   id: ID!
 
@@ -649,26 +770,6 @@ type BrandFilterValue {
 
   """Liczba produktów z tym brandem w current product set"""
   productCount: Int!
-
-  """Brand slug (refetch payload — paste w ProductFilter.brand.slug)"""
-  slug: String!
-}
-
-"""
-Brand summary — minimalna projekcja dla storefront catalog + filter rendering
-"""
-type BrandSummary {
-  """Brand unique identifier"""
-  id: ID!
-
-  """Brand logo URL (CDN-served, storefront-rendered)"""
-  logo: String
-
-  """Brand display name (e.g. "Funko", "Nintendo")"""
-  name: String!
-
-  """URL-friendly slug — używane dla future /marka/[slug] landing pages"""
-  slug: String!
 }
 
 """Business hours for a day"""
@@ -765,61 +866,79 @@ type CarrierShippingRate {
   serviceName: String!
 }
 
-"""Shopping cart"""
+"""
+A shopping cart — the buyer-facing aggregate that holds items, totals, buyer identity, addresses, selected shipping and payment methods, gift cards and discount codes through to checkout completion.
+"""
 type Cart implements Node {
-  """Gift cards applied do tego koszyka (debited at cartComplete)"""
+  """
+  Gift cards attached to the cart. Each card is debited by its `appliedAmount` when the cart completes.
+  """
   appliedGiftCards: [CartAppliedGiftCard!]!
 
-  """Cart attributes"""
+  """
+  Cart-level custom attributes (free-form key/value). Use for cart-wide metadata such as B2B PO number or marketing source. Replace (not merge) the list with `cartUpdateAttributes`.
+  """
   attributes: [CartAttribute!]!
 
   """Available payment methods dla tego cart (shop-configured providers)"""
   availablePaymentMethods: [PaymentMethod!]!
 
   """
-  Cart-aware shipping methods discovery. Returns empty methods + DIGITAL_ONLY_NO_SHIPPING user error when the cart contains only non-physical items (digital, gift card, service, subscription). Physical / mixed carts get the same method computation as the standalone `availableShippingMethods` query but with subtotal and weight pulled from the cart aggregate.
+  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!
 
   """
-  Billing address ustawiony przez cartSetBillingAddress (jeśli różny od shipping)
+  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).
   """
   billingAddress: MailingAddress
 
-  """Buyer identity information"""
+  """
+  Buyer identity attached to the cart (email, phone, country and language hints). Null on a fresh cart before any identity is captured.
+  """
   buyerIdentity: CartBuyerIdentity
 
-  """Checkout URL"""
+  """
+  Hosted checkout URL the storefront may redirect to as a fallback. The recommended flow is to drive checkout through SDK mutations (`cartSetShippingAddress`, `cartSelectShippingMethod`, `cartSelectPaymentMethod`, `cartComplete`).
+  """
   checkoutUrl: URL
 
-  """Cost breakdown"""
+  """
+  Cost breakdown for the cart (subtotal, tax, shipping, discount, grand total).
+  """
   cost: CartCost!
 
-  """Creation timestamp"""
+  """When the cart was created (ISO 8601)."""
   createdAt: DateTime!
 
-  """Discount allocations"""
+  """
+  Per-code discount amounts that make up `cost.totalDiscount`. Render line-item discount breakdown from this list.
+  """
   discountAllocations: [CartDiscountAllocation!]!
 
-  """Applied discount codes"""
+  """Discount codes attached to the cart with their applicability flag."""
   discountCodes: [CartDiscountCode!]!
 
   """
-  Customer email (D2 — persisted via cartUpdateBuyerIdentity). Convenience accessor; pełen kontekst w buyerIdentity.email.
+  Convenience accessor — buyer email as last set via `cartUpdateBuyerIdentity`. The same value is available on `buyerIdentity.email`.
   """
   email: String
 
-  """Unique cart identifier"""
+  """
+  Stable cart identifier — persist in a cookie / local store between sessions.
+  """
   id: ID!
 
-  """Cart line items (Relay Connection)"""
+  """Lines in the cart (paginated, Relay Connection)."""
   lines(after: String, before: String, first: Float, last: Float): CartLineConnection!
 
-  """Cart note"""
+  """
+  Buyer-supplied note (e.g. delivery instructions). Free-form, surfaced to the merchant on the order.
+  """
   note: String
 
   """
-  Customer phone (D2). Convenience accessor; pełen kontekst w buyerIdentity.phone.
+  Convenience accessor — buyer phone as last set via `cartUpdateBuyerIdentity`. The same value is available on `buyerIdentity.phone`.
   """
   phone: String
 
@@ -827,43 +946,51 @@ type Cart implements Node {
   recommendations(first: Int = 4): CartRecommendations
 
   """
-  True if any 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 picker in checkout.
+  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!
 
-  """Selected payment method (PayU/Stripe/COD/etc.)"""
+  """
+  The payment method currently selected on the cart. Null until the buyer picks a method via `cartSelectPaymentMethod`.
+  """
   selectedPaymentMethod: PaymentMethod
 
   """
-  Selected shipping method (D8 term unification — wcześniej selectedShippingRate)
+  The shipping method currently selected on the cart (label + cost). Null until the buyer picks a method.
   """
   selectedShippingMethod: CartShippingMethod
 
-  """Shipping address ustawiony przez cartSetShippingAddress"""
+  """
+  Shipping address attached to the cart via `cartSetShippingAddress`. Null until set.
+  """
   shippingAddress: MailingAddress
 
-  """Total quantity of all items"""
+  """
+  Sum of `quantity` across all lines — the badge number for the cart icon.
+  """
   totalQuantity: Int!
 
-  """Last update timestamp"""
+  """When the cart was last modified (ISO 8601)."""
   updatedAt: DateTime!
 }
 
-"""Result of adding lines to cart"""
+"""Result of `cartAddLines`."""
 type CartAddLinesPayload {
-  """Updated cart"""
+  """The updated cart on success; null when `userErrors` is non-empty."""
   cart: Cart
 
   """
-  User errors (code is namespaced — e.g. CART_NOT_FOUND, CART_LINE_NOT_FOUND)
+  Business / validation errors carrying a stable `CartErrorCode` in `code` (e.g. `CART_NOT_FOUND`, `NOT_ENOUGH_IN_STOCK`).
   """
   userErrors: [UserError!]!
 
-  """Non-fatal warnings"""
+  """Non-fatal advisories — the mutation itself succeeded."""
   warnings: [CartWarning!]!
 }
 
-"""Mailing address input dla cart fulfillment mutations"""
+"""
+Mailing address used as the shipping or billing address on a cart. Carries an optional pickup point (for parcel locker / collection-point delivery) and optional B2B fields (`taxId`, `regon`).
+"""
 input CartAddressInput {
   """City"""
   city: String!
@@ -883,9 +1010,19 @@ input CartAddressInput {
   """Phone number"""
   phone: String
 
+  """
+  Selected pickup point — required when the chosen shipping method has a deliveryType other than HOME (parcel locker / collection point).
+  """
+  pickupPoint: PickupPointInput
+
   """Postal / ZIP code"""
   postalCode: String!
 
+  """
+  Buyer business registry number for B2B invoicing (Polish REGON). Persisted on the resulting order at checkout completion.
+  """
+  regon: String
+
   """State / province"""
   state: String
 
@@ -894,153 +1031,209 @@ input CartAddressInput {
 
   """Second line of street address"""
   streetLine2: String
+
+  """
+  Buyer tax ID for B2B invoicing (Polish NIP). Persisted on the resulting order at checkout completion.
+  """
+  taxId: String
 }
 
-"""Gift card applied to a cart"""
+"""
+A gift card that the buyer has attached to the cart. The card is debited when the cart completes.
+"""
 type CartAppliedGiftCard {
-  """Amount applied to this cart"""
+  """Amount of this gift card that will be applied to the cart total."""
   appliedAmount: Money!
 
-  """Last 4 characters of the gift card code"""
+  """
+  Stable identifier of this applied gift card on the cart. Pass it to `cartRemoveGiftCard` so the storefront never has to hold the full gift card code.
+  """
+  id: ID!
+
+  """
+  Last 4 characters of the gift card code — useful when several cards are applied.
+  """
   lastCharacters: String!
 
-  """Masked gift card code for display (np. "****-****-****-ABCD")"""
+  """Masked code safe for display (e.g. "****-****-****-ABCD")."""
   maskedCode: String!
 
-  """Remaining balance on the gift card after this cart"""
+  """Remaining balance on the gift card after this cart is completed."""
   remainingBalance: Money!
 }
 
-"""Input dla cartApplyGiftCard mutation"""
+"""Input for `cartApplyGiftCard`."""
 input CartApplyGiftCardInput {
-  """Cart ID"""
+  """ID of the cart to update."""
   cartId: ID!
 
-  """Gift card code (np. ABCD-1234-EFGH-5678)"""
+  """
+  Full gift card code entered by the buyer (e.g. "ABCD-1234-EFGH-5678"). Max 64 chars.
+  """
   giftCardCode: String!
 }
 
-"""Result of applying gift card to cart"""
+"""Result of `cartApplyGiftCard`."""
 type CartApplyGiftCardPayload {
-  """Updated cart z appliedGiftCards"""
+  """The updated cart with the gift card included in `appliedGiftCards`."""
   cart: Cart
 
   """
-  User errors (CartErrorCode-namespaced — np. GIFT_CARD_NOT_FOUND, GIFT_CARD_DEPLETED, GIFT_CARD_UNUSABLE)
+  Business / validation errors carrying a stable `CartErrorCode` in `code` (e.g. `GIFT_CARD_NOT_FOUND`, `GIFT_CARD_DEPLETED`, `GIFT_CARD_UNUSABLE`).
   """
   userErrors: [UserError!]!
 
-  """Non-fatal warnings"""
+  """Non-fatal advisories — the mutation itself succeeded."""
   warnings: [CartWarning!]!
 }
 
-"""Cart line attribute"""
+"""
+Custom attribute on a cart line — free-form key/value used for line item properties such as engraving text or gift wrap flags.
+"""
 type CartAttribute {
-  """Attribute key"""
+  """Attribute key (e.g. "giftWrap", "engraving")."""
   key: String!
 
-  """Attribute value"""
+  """Attribute value. Null when the key is set without an associated value."""
   value: String
 }
 
-"""Input for cart attribute"""
+"""
+A custom cart attribute key/value pair. Used by `cartUpdateAttributes`; the full list is replaced on each call.
+"""
 input CartAttributeInput {
-  """Attribute key"""
+  """Attribute key (max 255 chars)."""
   key: String!
 
-  """Attribute value"""
+  """Attribute value (max 500 chars). Omit to set the key without a value."""
   value: String
 }
 
-"""Buyer identity information"""
+"""
+Buyer identity attached to the cart — email, phone, locale hints used during checkout and on the resulting order.
+"""
 type CartBuyerIdentity {
-  """ISO 3166-1 alpha-2 country code"""
+  """
+  Buyer country (ISO 3166-1 alpha-2). Hint for pricing, tax and shipping eligibility before an address is provided.
+  """
   countryCode: CountryCode
 
-  """Customer ID"""
+  """
+  Customer record ID when the cart is owned by a signed-in customer. Null for guest carts.
+  """
   customerId: ID
 
-  """Customer email"""
+  """Buyer email — receives the order confirmation when the cart completes."""
   email: String
 
-  """ISO 639-1 preferred language code"""
+  """
+  Buyer preferred language (ISO 639-1). Used for the order confirmation email and any localised content.
+  """
   languageCode: LanguageCode
 
-  """Customer phone"""
+  """Buyer phone number, free-form (validated only for length)."""
   phone: String
 }
 
-"""Input for buyer identity"""
+"""
+Buyer identity to attach to a cart. All fields are optional — only the supplied fields are updated.
+"""
 input CartBuyerIdentityInput {
-  """ISO 3166-1 alpha-2 country code"""
+  """
+  Buyer country (ISO 3166-1 alpha-2). Hint for currency, tax and shipping eligibility before an address is set.
+  """
   countryCode: CountryCode
 
-  """Customer ID"""
+  """
+  ID of a signed-in customer that owns this cart. Pass to bind a guest cart to a customer record.
+  """
   customerId: ID
 
-  """Customer email"""
+  """Buyer email address. Persisted to the order at checkout completion."""
   email: String
 
-  """ISO 639-1 preferred language code"""
+  """
+  Buyer preferred language (ISO 639-1). Used for the order confirmation email and localised content.
+  """
   languageCode: LanguageCode
 
-  """Customer phone"""
+  """Buyer phone number. Free-form; max 30 chars."""
   phone: String
 }
 
-"""Input dla cartComplete mutation — finalizuje cart do Order"""
+"""Input for `cartComplete` — finalises the cart into an `Order`."""
 input CartCompleteInput {
-  """Cart ID do skompletowania"""
+  """ID of the cart to complete."""
   cartId: ID!
 
   """
-  Optional idempotency key — zapobiega duplicate Orders przy retry / network issue (jeśli null, generowany z cartId + minute timestamp)
+  Optional idempotency key — guards against duplicate orders on retry / network issue. When omitted, the server derives one from the cart ID and the current minute, which is sufficient for the typical "user double-clicks the pay button" case.
   """
   idempotencyKey: String
 }
 
 """
-Result of completing cart — transition cart → order (per D4 NO paymentUrl). Cart NIE w payload — po complete koszyk jest CONVERTED/locked.
+Result of `cartComplete`. The cart is converted into an `Order` and locked — no further mutations are accepted on it. Payment is initiated separately via `paymentCreate` (after checking `order.canCreatePayment`).
 """
 type CartCompletePayload {
   """
-  Order created z cart. Zapewnia canCreatePayment + paymentMethodType (Phase 4 ResolveFields) dla decyzji storefront przycisku "Zapłać".
+  The order created from the cart. Carries `canCreatePayment` and `paymentMethodType` signals so the storefront can decide whether to render a "Pay now" button or send the buyer straight to the confirmation page (for offline methods).
   """
   order: Order
 
   """
-  User errors (CartErrorCode-namespaced — np. INSUFFICIENT_STOCK, SHIPPING_ADDRESS_REQUIRED, PAYMENT_METHOD_REQUIRED, EMAIL_REQUIRED)
+  Business / validation errors carrying a stable `CartErrorCode` in `code` (e.g. `NOT_ENOUGH_IN_STOCK`, `SHIPPING_ADDRESS_REQUIRED`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_REQUIRED`, `EMAIL_REQUIRED`, `ALREADY_COMPLETED`).
   """
   userErrors: [UserError!]!
 
-  """Non-fatal warnings"""
+  """Non-fatal advisories — the mutation itself succeeded."""
   warnings: [CartWarning!]!
 }
 
-"""Cart cost breakdown"""
+"""
+Cart cost breakdown. All amounts are in the buyer preferred currency (auto-converted when the shop runs multi-currency). `total` is what the buyer will pay at checkout — no need to recompute.
+"""
 type CartCost {
-  """Checkout charge amount."""
+  """
+  Additional fixed checkout fee configured by the shop (e.g. small-order surcharge). Null when no such fee applies.
+  """
   checkoutCharge: Money
 
   """Opt-in: checkoutCharge with conversion transparency."""
   checkoutChargeWithConversion: PriceMoney
 
-  """Subtotal before taxes and shipping. Default field."""
+  """Subtotal of items in the cart before taxes, shipping and discounts."""
   subtotal: Money!
 
   """Opt-in: subtotal with full conversion transparency."""
   subtotalWithConversion: PriceMoney
 
-  """Total amount including taxes."""
+  """
+  Grand total the buyer will pay — includes taxes, discounts and any selected shipping. Use this directly on the checkout summary instead of summing `subtotal` + extras.
+  """
   total: Money!
 
-  """Total duty amount."""
+  """
+  Aggregated discount across the cart — the sum of every entry in `discountAllocations`. Returns an amount of 0 when no discount applies.
+  """
+  totalDiscount: Money!
+
+  """
+  Total customs duty on the cart. Null when no duty applies (most domestic orders).
+  """
   totalDuty: Money
 
   """Opt-in: totalDuty with conversion transparency."""
   totalDutyWithConversion: PriceMoney
 
-  """Total tax amount."""
+  """
+  Cost of the currently selected shipping method. Null until a shipping method is selected — a selected free-shipping method returns an amount of 0, so null unambiguously means "no method chosen yet".
+  """
+  totalShipping: Money
+
+  """
+  Total tax across all lines. Null when tax has not yet been calculated for this cart (e.g. before an address is set in tax-inclusive shops).
+  """
   totalTax: Money
 
   """Opt-in: totalTax with conversion transparency."""
@@ -1050,150 +1243,194 @@ type CartCost {
   totalWithConversion: PriceMoney
 }
 
-"""Input for creating a cart"""
+"""
+Input for `cartCreate`. All fields are optional — pass only what you have at cart creation time.
+"""
 input CartCreateInput {
-  """Cart attributes"""
+  """
+  Cart-level custom attributes to set on the new cart (up to 50 entries).
+  """
   attributes: [CartAttributeInput!]
 
-  """Buyer identity"""
+  """
+  Buyer identity to attach to the new cart (email, phone, customer ID, country, language).
+  """
   buyerIdentity: CartBuyerIdentityInput
 
-  """Discount codes to apply"""
+  """
+  Discount codes to apply at creation (up to 10). Equivalent to calling `cartDiscountCodesUpdate` immediately after creating the cart.
+  """
   discountCodes: [String!]
 
-  """Customer email (Phase 3 D2 — merge funkcjonalności checkoutCreate)"""
+  """
+  Buyer email — shortcut for `buyerIdentity.email`. If both are provided, this field wins.
+  """
   email: String
 
-  """Initial cart lines"""
+  """Initial lines to add to the cart (up to 100)."""
   lines: [CartLineInput!]
 
-  """Cart note"""
+  """Buyer-supplied note (max 1000 chars), e.g. delivery instructions."""
   note: String
 
-  """Shipping address (Phase 3 — fulfillment context w jednym round-trip)"""
+  """
+  Shipping address to attach to the new cart — lets the storefront skip a follow-up `cartSetShippingAddress` call.
+  """
   shippingAddress: CartAddressInput
 }
 
-"""Result of cart creation"""
+"""Result of `cartCreate`."""
 type CartCreatePayload {
-  """Created cart"""
+  """The created cart on success; null when `userErrors` is non-empty."""
   cart: Cart
 
   """
-  User errors (code is namespaced — e.g. CART_NOT_FOUND, CART_LINE_NOT_FOUND)
+  Business / validation errors. Each entry carries a stable `code` (e.g. `CART_NOT_FOUND`, `NOT_ENOUGH_IN_STOCK`, `INVALID_MERCHANDISE_LINE`) — branch on `code`, never on `message`.
   """
   userErrors: [UserError!]!
 
-  """Non-fatal warnings"""
+  """
+  Non-fatal advisories (informational only; the mutation itself succeeded).
+  """
   warnings: [CartWarning!]!
 }
 
-"""Discount allocation showing how discount is applied"""
+"""
+Per-code discount amount applied to the cart. Sum these for the aggregate total — or read `CartCost.totalDiscount`.
+"""
 type CartDiscountAllocation {
-  """Discount amount"""
+  """Amount discounted by this code on the cart."""
   amount: Money!
 
-  """Discount code"""
+  """The discount code that produced this allocation."""
   discountCode: String!
 }
 
-"""Discount code applied to cart"""
+"""A discount code that the buyer has attached to the cart."""
 type CartDiscountCode {
-  """Discount code string"""
+  """The code string as entered by the buyer (case is preserved as stored)."""
   code: String!
 
-  """Whether the code is applicable"""
+  """
+  Whether this code currently produces a discount on the cart. False when the code is recognised but its conditions are not met (e.g. minimum-order, customer-eligibility, or product-set restrictions) — keep the chip visible and surface the reason.
+  """
   isApplicable: Boolean!
 }
 
-"""Result of applying discount codes"""
+"""Result of `cartDiscountCodesUpdate`."""
 type CartDiscountCodesUpdatePayload {
-  """Updated cart"""
+  """The updated cart on success."""
   cart: Cart
 
   """
-  User errors (code is namespaced — e.g. CART_NOT_FOUND, CART_LINE_NOT_FOUND)
+  Business / validation errors carrying a stable `CartErrorCode` in `code` (e.g. `INVALID_DISCOUNT_CODE`).
   """
   userErrors: [UserError!]!
 
-  """Non-fatal warnings"""
+  """Non-fatal advisories — the mutation itself succeeded."""
   warnings: [CartWarning!]!
 }
 
-"""Single line item in the cart"""
+"""
+A single line item in the cart — one variant, a quantity and the data attached to it (cost, attributes, configurator selections).
+"""
 type CartLine {
-  """Typed customer-filled attribute selections (surcharge + tax snapshot)"""
+  """
+  Typed configurator selections filled in by the buyer (snapshot from add-to-cart). Validated server-side against the product attribute definition; carries any pricing surcharge.
+  """
   attributeSelections: [AttributeSelection!]!
 
-  """Line Item Properties — raw key/value pairs"""
+  """
+  Free-form custom attributes (line item properties) attached to this line — engraving text, gift wrap, B2B PO line reference, etc.
+  """
   attributes: [Attribute!]!
 
-  """Cost information for this line"""
+  """
+  Per-line cost breakdown (unit price, subtotal, total, optional compare-at).
+  """
   cost: CartLineCost!
 
-  """Unique line identifier"""
+  """
+  Stable line identifier. Use it to address the line in `cartUpdateLines` / `cartRemoveLines`.
+  """
   id: ID!
 
-  """Parent product handle (slug)"""
+  """
+  URL handle (slug) of the parent product — link target for the cart drawer (denormalised).
+  """
   productHandle: String
 
-  """Parent product ID"""
+  """
+  ID of the parent product. Denormalised so a cart drawer renders without an extra round-trip.
+  """
   productId: ID
 
-  """Parent product title"""
+  """Display title of the parent product (denormalised)."""
   productTitle: String
 
-  """Parent product type"""
+  """
+  Type of the parent product (PHYSICAL, DIGITAL, SERVICE, SUBSCRIPTION, GIFT_CARD). Drives whether the line requires shipping and which post-purchase flow applies.
+  """
   productType: ProductTypeEnum
 
-  """Quantity of this item"""
+  """
+  Quantity of the variant in this line (≥ 1; set to 0 with `cartUpdateLines` to remove).
+  """
   quantity: Int!
 
   """
-  True if this line item requires physical shipping (productType=PHYSICAL). False for digital, gift card, service, and subscription items. Use to skip the shipping step in checkout when every line is non-physical.
+  True when this line requires physical shipping (`productType` = PHYSICAL). False for digital, gift card, service and subscription items. Use together with `Cart.requiresShipping` to decide whether to render the shipping step.
   """
   requiresShipping: Boolean!
 
-  """Product variant being purchased"""
+  """
+  The variant being purchased — fresh data (current price, image, stock).
+  """
   variant: ProductVariant!
 }
 
-"""Paginated cart lines"""
+"""Paginated list of cart lines (Relay Connection)."""
 type CartLineConnection {
-  """Cart line edges with cursors"""
+  """Edges with the line and its cursor — use for cursor-based pagination."""
   edges: [CartLineEdge!]!
 
-  """Cart line nodes (shortcut for edges.map(e => e.node))"""
+  """Cart line nodes — convenience shortcut for `edges.map(e => e.node)`."""
   nodes: [CartLine!]!
 
-  """Pagination info"""
+  """Cursor pagination info (`hasNextPage`, `endCursor`, etc.)."""
   pageInfo: PageInfo!
 
-  """Total count of cart lines"""
+  """Total number of lines in the cart across all pages."""
   totalCount: Int!
 }
 
-"""Cost information for a single cart line"""
+"""Cost breakdown for a single cart line."""
 type CartLineCost {
-  """Compare-at price per unit if discounted."""
+  """
+  Strike-through compare-at unit price when the line is on sale. Null when the line is not discounted; show the strike-through only when this is present and greater than `pricePerUnit`.
+  """
   compareAtPricePerUnit: Money
 
   """Opt-in: compareAtPricePerUnit with conversion transparency."""
   compareAtPricePerUnitWithConversion: PriceMoney
 
-  """Price per unit. Default field — shop base currency."""
+  """
+  Unit price of the line item in the shop base currency. Use this for per-unit display.
+  """
   pricePerUnit: Money!
 
   """Opt-in: pricePerUnit with conversion transparency."""
   pricePerUnitWithConversion: PriceMoney
 
-  """Subtotal before discounts."""
+  """Line subtotal before line-level discounts (`pricePerUnit` × quantity)."""
   subtotal: Money!
 
   """Opt-in: subtotal with conversion transparency."""
   subtotalWithConversion: PriceMoney
 
-  """Total after discounts."""
+  """
+  Line total after any line-level discounts and surcharges. This is what the buyer pays for the line.
+  """
   total: Money!
 
   """Opt-in: total with conversion transparency."""
@@ -1209,35 +1446,45 @@ type CartLineEdge {
   node: CartLine!
 }
 
-"""Input for adding a line to cart"""
+"""
+A line to add to the cart — variant, quantity and optional custom attributes / configurator selections.
+"""
 input CartLineInput {
-  """Customer-filled AttributeDefinition selections (Faza 1 R5)"""
+  """
+  Typed configurator selections to apply to this line — validated against the product attribute definition; pricing surcharges are taken from a snapshot at add-to-cart.
+  """
   attributeSelections: [AttributeSelectionInput!]
 
-  """Line attributes (Line Item Properties)"""
+  """
+  Free-form custom attributes (line item properties) — e.g. engraving text, gift wrap, B2B PO line reference. Up to 50 entries.
+  """
   attributes: [AttributeInput!]
 
-  """Quantity to add"""
+  """Quantity to add (1 to 9999). Defaults to 1 when omitted."""
   quantity: Int! = 1
 
-  """Product variant ID"""
+  """ID of the product variant being purchased."""
   variantId: ID!
 }
 
-"""Input for updating a cart line"""
+"""
+An update to apply to an existing cart line — new quantity (set to 0 to remove) and optional attribute updates.
+"""
 input CartLineUpdateInput {
   """
-  Updated customer-filled attribute selections (null preserves; [] clears)
+  Replacement list of configurator selections. Omit (or pass null) to keep the existing selections; pass an empty array to clear them.
   """
   attributeSelections: [AttributeSelectionInput!]
 
-  """Updated Line Item Properties (null preserves)"""
+  """
+  Replacement list of custom attributes on the line. Omit (or pass null) to keep the existing list; pass an empty array to clear it.
+  """
   attributes: [AttributeInput!]
 
-  """Cart line ID to update"""
+  """ID of the cart line to update (`CartLine.id`)."""
   id: ID!
 
-  """New quantity"""
+  """New quantity. Use 0 to remove the line from the cart."""
   quantity: Int!
 }
 
@@ -1250,130 +1497,142 @@ type CartRecommendations {
   youMayAlsoLike: [ProductRecommendation!]!
 }
 
-"""Input dla cartRemoveGiftCard mutation"""
+"""Input for `cartRemoveGiftCard`."""
 input CartRemoveGiftCardInput {
-  """Cart ID"""
+  """ID of the cart to update."""
   cartId: ID!
 
-  """Gift card code (matching wartości aplikowanej karty)"""
-  giftCardCode: String!
+  """
+  ID of the applied gift card to remove — `CartAppliedGiftCard.id` from the cart.
+  """
+  giftCardId: ID!
 }
 
-"""Result of removing gift card from cart"""
+"""Result of `cartRemoveGiftCard`."""
 type CartRemoveGiftCardPayload {
-  """Updated cart (gift card usunięty z appliedGiftCards)"""
+  """The updated cart with the gift card removed from `appliedGiftCards`."""
   cart: Cart
 
-  """User errors (CartErrorCode-namespaced)"""
+  """
+  Business / validation errors carrying a stable `CartErrorCode` in `code`.
+  """
   userErrors: [UserError!]!
 
-  """Non-fatal warnings"""
+  """Non-fatal advisories — the mutation itself succeeded."""
   warnings: [CartWarning!]!
 }
 
-"""Result of removing cart lines"""
+"""Result of `cartRemoveLines`."""
 type CartRemoveLinesPayload {
-  """Updated cart"""
+  """The updated cart on success; null when `userErrors` is non-empty."""
   cart: Cart
 
   """
-  User errors (code is namespaced — e.g. CART_NOT_FOUND, CART_LINE_NOT_FOUND)
+  Business / validation errors carrying a stable `CartErrorCode` in `code`.
   """
   userErrors: [UserError!]!
 
-  """Non-fatal warnings"""
+  """Non-fatal advisories — the mutation itself succeeded."""
   warnings: [CartWarning!]!
 }
 
-"""Input dla cartSelectPaymentMethod mutation"""
+"""Input for `cartSelectPaymentMethod`."""
 input CartSelectPaymentMethodInput {
-  """Cart ID"""
+  """ID of the cart to update."""
   cartId: ID!
 
-  """Payment method (integration provider) ID"""
+  """
+  ID of the chosen payment method (matches a `PaymentMethod.id` from `availablePaymentMethods`).
+  """
   paymentMethodId: ID!
 }
 
-"""Result of selecting payment method on cart"""
+"""Result of `cartSelectPaymentMethod`."""
 type CartSelectPaymentMethodPayload {
-  """Updated cart (selectedPaymentMethod populated)"""
+  """The updated cart with `selectedPaymentMethod` populated."""
   cart: Cart
 
   """
-  User errors (CartErrorCode-namespaced — np. PAYMENT_METHOD_REQUIRED, INVALID_PAYMENT)
+  Business / validation errors carrying a stable `CartErrorCode` in `code` (e.g. `PAYMENT_METHOD_REQUIRED`, `INVALID_PAYMENT_METHOD`, `PAYMENT_METHOD_NOT_SUPPORTED`).
   """
   userErrors: [UserError!]!
 
-  """Non-fatal warnings"""
+  """Non-fatal advisories — the mutation itself succeeded."""
   warnings: [CartWarning!]!
 }
 
-"""Input dla cartSelectShippingMethod mutation (D8 term unification)"""
+"""Input for `cartSelectShippingMethod`."""
 input CartSelectShippingMethodInput {
-  """Cart ID"""
+  """ID of the cart to update."""
   cartId: ID!
 
   """
-  Shipping method ID (handle z available shipping methods query). Typed ID! per D8 rename argument rateId → shippingMethodId.
+  ID of the chosen shipping method (matches an `AvailableShippingMethod.id` from `cart.availableShippingMethods`).
   """
   shippingMethodId: ID!
 }
 
-"""Result of selecting shipping method on cart (D8 term unification)"""
+"""Result of `cartSelectShippingMethod`."""
 type CartSelectShippingMethodPayload {
-  """Updated cart (selectedShippingMethod populated)"""
+  """
+  The updated cart with `selectedShippingMethod` populated and `cost.totalShipping` updated.
+  """
   cart: Cart
 
   """
-  User errors (CartErrorCode-namespaced — np. SHIPPING_METHOD_REQUIRED, ZIP_CODE_NOT_SUPPORTED)
+  Business / validation errors carrying a stable `CartErrorCode` in `code` (e.g. `SHIPPING_METHOD_REQUIRED`, `FORBIDDEN_SHIPPING_METHOD`, `ZIP_CODE_NOT_SUPPORTED`).
   """
   userErrors: [UserError!]!
 
-  """Non-fatal warnings"""
+  """Non-fatal advisories — the mutation itself succeeded."""
   warnings: [CartWarning!]!
 }
 
-"""Input dla cartSetBillingAddress mutation"""
+"""Input for `cartSetBillingAddress`."""
 input CartSetBillingAddressInput {
-  """Billing address (zostawia shipping bez zmian)"""
+  """New billing address. The shipping address is left unchanged."""
   address: CartAddressInput!
 
-  """Cart ID"""
+  """ID of the cart to update."""
   cartId: ID!
 }
 
-"""Result of setting cart billing address"""
+"""Result of `cartSetBillingAddress`."""
 type CartSetBillingAddressPayload {
-  """Updated cart"""
+  """The updated cart with the new billing address."""
   cart: Cart
 
-  """User errors (CartErrorCode-namespaced)"""
+  """
+  Business / validation errors carrying a stable `CartErrorCode` in `code`.
+  """
   userErrors: [UserError!]!
 
-  """Non-fatal warnings"""
+  """Non-fatal advisories — the mutation itself succeeded."""
   warnings: [CartWarning!]!
 }
 
-"""Input dla cartSetShippingAddress mutation"""
+"""Input for `cartSetShippingAddress`."""
 input CartSetShippingAddressInput {
-  """Shipping address"""
+  """
+  New shipping address. Replaces any previous shipping address on the cart.
+  """
   address: CartAddressInput!
 
-  """Cart ID"""
+  """ID of the cart to update."""
   cartId: ID!
 }
 
-"""Result of setting cart shipping address"""
+"""Result of `cartSetShippingAddress`."""
 type CartSetShippingAddressPayload {
-  """Updated cart"""
+  """The updated cart with the new shipping address."""
   cart: Cart
 
   """
-  User errors (CartErrorCode-namespaced — np. INVALID_ADDRESS, EMAIL_REQUIRED)
+  Business / validation errors carrying a stable `CartErrorCode` in `code` (e.g. `INVALID_ADDRESS`, `EMAIL_REQUIRED`, `PICKUP_POINT_REQUIRED`).
   """
   userErrors: [UserError!]!
 
-  """Non-fatal warnings"""
+  """Non-fatal advisories — the mutation itself succeeded."""
   warnings: [CartWarning!]!
 }
 
@@ -1389,123 +1648,140 @@ input CartShippingInput {
   totalWeight: Int
 }
 
-"""Shipping method selected on a cart (D8 term unification)"""
+"""
+The shipping method currently selected on a cart, with its display label and cost.
+"""
 type CartShippingMethod {
-  """Shipping method (rate) handle"""
+  """
+  Handle of the selected shipping method — matches the `id` of an `AvailableShippingMethod`.
+  """
   handle: ID!
 
-  """Shipping cost"""
+  """Cost of the selected shipping method."""
   price: Money!
 
-  """Display title (e.g. "DPD Standard 2 dni")"""
+  """Display title for the checkout summary (e.g. "DPD Standard, 2 days")."""
   title: String!
 }
 
-"""Result of updating cart attributes"""
+"""Result of `cartUpdateAttributes`."""
 type CartUpdateAttributesPayload {
-  """Updated cart"""
+  """The updated cart on success."""
   cart: Cart
 
   """
-  User errors (code is namespaced — e.g. CART_NOT_FOUND, CART_LINE_NOT_FOUND)
+  Business / validation errors carrying a stable `CartErrorCode` in `code` (e.g. `CART_ATTRIBUTES_UPDATE_FAILED`).
   """
   userErrors: [UserError!]!
 
-  """Non-fatal warnings"""
+  """Non-fatal advisories — the mutation itself succeeded."""
   warnings: [CartWarning!]!
 }
 
-"""Result of updating buyer identity"""
+"""Result of `cartUpdateBuyerIdentity`."""
 type CartUpdateBuyerIdentityPayload {
-  """Updated cart"""
+  """The updated cart on success."""
   cart: Cart
 
   """
-  User errors (code is namespaced — e.g. CART_NOT_FOUND, CART_LINE_NOT_FOUND)
+  Business / validation errors carrying a stable `CartErrorCode` in `code`.
   """
   userErrors: [UserError!]!
 
-  """Non-fatal warnings"""
+  """Non-fatal advisories — the mutation itself succeeded."""
   warnings: [CartWarning!]!
 }
 
 """
-Input dla cartUpdateGiftCardRecipient mutation (gift card line item recipient info)
+Input for `cartUpdateGiftCardRecipient` — sets the recipient details for a gift card line item.
 """
 input CartUpdateGiftCardRecipientInput {
-  """Cart ID"""
+  """ID of the cart to update."""
   cartId: ID!
 
-  """Cart line item ID (musi reprezentować gift card SKU)"""
+  """ID of the cart line; the line must be a gift card SKU."""
   lineItemId: ID!
 
-  """Personalised message dla recipienta (max 500 znaków)"""
+  """Personalised message included with the gift card (max 500 chars)."""
   message: String
 
-  """Recipient email (gift card delivery target)"""
+  """Recipient email — where the gift card code will be delivered."""
   recipientEmail: String
 
-  """Recipient display name"""
+  """Recipient display name."""
   recipientName: String
 }
 
-"""Result of updating gift card recipient info on cart line item"""
+"""Result of `cartUpdateGiftCardRecipient`."""
 type CartUpdateGiftCardRecipientPayload {
-  """Updated cart"""
+  """
+  The updated cart with the new gift card recipient info on the target line.
+  """
   cart: Cart
 
-  """User errors (CartErrorCode-namespaced)"""
+  """
+  Business / validation errors carrying a stable `CartErrorCode` in `code`.
+  """
   userErrors: [UserError!]!
 
-  """Non-fatal warnings"""
+  """Non-fatal advisories — the mutation itself succeeded."""
   warnings: [CartWarning!]!
 }
 
-"""Result of updating cart lines"""
+"""Result of `cartUpdateLines`."""
 type CartUpdateLinesPayload {
-  """Updated cart"""
+  """The updated cart on success; null when `userErrors` is non-empty."""
   cart: Cart
 
   """
-  User errors (code is namespaced — e.g. CART_NOT_FOUND, CART_LINE_NOT_FOUND)
+  Business / validation errors carrying a stable `CartErrorCode` in `code` (e.g. `CART_NOT_FOUND`, `NOT_ENOUGH_IN_STOCK`).
   """
   userErrors: [UserError!]!
 
-  """Non-fatal warnings"""
+  """Non-fatal advisories — the mutation itself succeeded."""
   warnings: [CartWarning!]!
 }
 
-"""Result of updating cart note"""
+"""Result of `cartUpdateNote`."""
 type CartUpdateNotePayload {
-  """Updated cart"""
+  """The updated cart on success."""
   cart: Cart
 
   """
-  User errors (code is namespaced — e.g. CART_NOT_FOUND, CART_LINE_NOT_FOUND)
+  Business / validation errors carrying a stable `CartErrorCode` in `code`.
   """
   userErrors: [UserError!]!
 
-  """Non-fatal warnings"""
+  """Non-fatal advisories — the mutation itself succeeded."""
   warnings: [CartWarning!]!
 }
 
 """Cart warning (non-fatal advisory)"""
 type CartWarning {
-  """Typed warning code"""
+  """
+  Stable machine-readable warning code. Branch on this for UI behaviour — never on `message` (translated, locale-dependent).
+  """
   code: CartWarningCode!
 
-  """Warning message"""
+  """
+  Human-readable warning message — informational, the mutation itself succeeded.
+  """
   message: String!
 
-  """Target identifier (cart line ID lub field path)"""
+  """
+  What the warning is about — a cart line ID when the warning refers to a specific item, or a field path otherwise.
+  """
   target: String!
 }
 
-"""Non-fatal cart warnings"""
+"""
+Stable, machine-readable codes for non-fatal cart warnings. The mutation succeeded; the storefront can surface a toast or stay silent based on the code.
+"""
 enum CartWarningCode {
   MERCHANDISE_NOT_AVAILABLE
   MERCHANDISE_NOT_ENOUGH_STOCK
   PAYMENTS_AMOUNT_REGION_MISMATCH
+  SHIPPING_METHOD_AUTO_CLEARED
 }
 
 """Product category - hierarchical organization"""
@@ -1516,6 +1792,11 @@ type Category {
   """Category description"""
   description: String
 
+  """
+  URL-friendly handle (e.g. "electronics" -> /categories/electronics). Stable per-shop.
+  """
+  handle: String!
+
   """Unique identifier"""
   id: ID!
 
@@ -1543,9 +1824,6 @@ type Category {
   """SEO metadata"""
   seo: SEO
 
-  """URL-friendly slug"""
-  slug: String!
-
   """Sort order within parent"""
   sortOrder: Int!
 }
@@ -1582,6 +1860,9 @@ input CategoryFilter {
 
 """Category filter option"""
 type CategoryFilterOption {
+  """URL-friendly handle"""
+  handle: String!
+
   """Category ID"""
   id: ID!
 
@@ -1596,9 +1877,6 @@ type CategoryFilterOption {
 
   """Number of products in this category"""
   productCount: Int!
-
-  """URL-friendly slug"""
-  slug: String!
 }
 
 """Collection - curated group of products"""
@@ -1705,7 +1983,7 @@ type Country implements Node {
   unitSystem: UnitSystem!
 }
 
-"""ISO 3166-1 alpha-2 country code"""
+"""ISO 3166-1 alpha-2 country code (2-letter uppercase, e.g. PL, DE, US)."""
 enum CountryCode {
   AT
   AU
@@ -1773,7 +2051,7 @@ type Currency {
   symbolPosition: CurrencySymbolPosition!
 }
 
-"""ISO 4217 currency code"""
+"""ISO 4217 currency code (3-letter uppercase, e.g. PLN, EUR, USD)."""
 enum CurrencyCode {
   AED
   AFN
@@ -1987,90 +2265,122 @@ enum CurrencySymbolPosition {
   BEFORE
 }
 
-"""Customer - registered user"""
+"""
+A registered customer of the shop — identity, profile, B2B fields, saved addresses and order history. Returned by `customer` (currently authenticated) and `customerSignup`.
+"""
 type Customer implements Node {
-  """Saved addresses (Relay Connection)"""
+  """
+  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!
 
   """Customer custom field values (post-Opcja A unified custom fields)."""
   attributes(namespace: String): [EntityAttributeField!]!
 
-  """Company name (populated for COMPANY type)"""
+  """
+  Company name. Populated when `customerType` is COMPANY; null for INDIVIDUAL profiles.
+  """
   companyName: String
 
-  """Account creation date"""
+  """When the customer account was created (ISO 8601)."""
   createdAt: DateTime!
 
-  """Business type discriminator (INDIVIDUAL/COMPANY)"""
+  """
+  Profile type — INDIVIDUAL (B2C) or COMPANY (B2B). When COMPANY, the company fields below are populated.
+  """
   customerType: CustomerType!
 
-  """Default address"""
+  """
+  Default address pre-selected in checkout pickers. Null when the customer has no saved addresses.
+  """
   defaultAddress: MailingAddress
 
-  """Display name"""
+  """
+  Display name — typically `firstName lastName`, with sensible fallback to email when neither is set. Render directly in the UI.
+  """
   displayName: String!
 
-  """Email address"""
+  """Customer email address (login identity)."""
   email: String!
 
-  """Email marketing consent state"""
+  """
+  Marketing consent state (NOT_SUBSCRIBED, PENDING, SUBSCRIBED, UNSUBSCRIBED, REDACTED, INVALID). Drive newsletter UI and opt-in / opt-out controls from this value.
+  """
   emailMarketing: EmailMarketingState!
 
-  """First name"""
+  """Customer first name."""
   firstName: String
 
-  """Unique identifier"""
+  """Stable identifier of the customer."""
   id: ID!
 
-  """Whether email is verified"""
+  """True when the customer has confirmed ownership of their email address."""
   isEmailVerified: Boolean!
 
-  """Last name"""
+  """Customer last name."""
   lastName: String
 
-  """Total orders count (UnsignedInt64 — BigInt-safe)"""
+  """
+  Total number of orders the customer has placed. Stringified for BigInt safety.
+  """
   orderCount: UnsignedInt64!
 
-  """Customer orders"""
+  """
+  Orders placed by this customer (Relay Connection). Use for the order history page.
+  """
   orders(after: String, first: Int = 10): OrderConnection!
 
-  """Phone number"""
+  """Customer phone number (free-form)."""
   phone: String
 
-  """Polish business registry number — REGON"""
+  """
+  Customer-wide Polish business registry number (REGON, 9 or 14 digits with checksum).
+  """
   regon: String
 
-  """Customer tags for segmentation (e.g. vip, wholesale, b2b)"""
+  """
+  Merchant-assigned segmentation tags (e.g. "vip", "wholesale", "b2b"). Use to customise UI / pricing rules on the storefront.
+  """
   tags: [String!]!
 
-  """Polish tax ID — NIP"""
+  """
+  Customer-wide Polish tax ID (NIP, 10 digits with checksum). Default for new addresses; can be overridden per address via `MailingAddress.taxId`.
+  """
   taxId: String
 
-  """Total amount spent"""
+  """Lifetime amount the customer has spent (sum of paid orders)."""
   totalSpent: Money!
 
-  """Last update date"""
+  """When the customer profile was last modified (ISO 8601)."""
   updatedAt: DateTime!
 
-  """EU VAT number"""
+  """
+  Customer-wide EU VAT number (e.g. `PL1234567890`). Default for new addresses; can be overridden per address via `MailingAddress.vatNumber`.
+  """
   vatNumber: String
 }
 
-"""Customer access token"""
+"""
+Access token returned by `customerLogin`, `customerSignup` and `customerRefreshToken`. Send it on subsequent requests in the `Authorization: Bearer <token>` header, or store it in an HTTP-only cookie via the SDK BFF helpers. Never write it to `localStorage`.
+"""
 type CustomerAccessToken {
-  """Access token string"""
+  """The access token string (JWT). Treat as sensitive — do not log."""
   accessToken: String!
 
-  """Token expiration (ISO 8601)"""
+  """
+  When the token stops being valid (ISO 8601). Call `customerRefreshToken` before this to obtain a fresh one.
+  """
   expiresAt: DateTime!
 }
 
-"""Input for customer login"""
+"""
+Input for `customerLogin` — exchanges email + password for an access token.
+"""
 input CustomerAccessTokenCreateInput {
-  """Email address"""
+  """Customer email address."""
   email: String!
 
-  """Password"""
+  """Customer password."""
   password: String!
 }
 
@@ -2101,31 +2411,35 @@ type CustomerAddAddressPayload {
   userErrors: [UserError!]!
 }
 
-"""Input for customer registration"""
+"""Input for `customerSignup` — registers a new customer."""
 input CustomerCreateInput {
   """
-  Opt-in to email marketing checkbox. true → state SUBSCRIBED (single opt-in) unless `marketingOptInLevel: CONFIRMED_OPT_IN` is also set (then PENDING + double opt-in confirmation email). false/null → no consent change.
+  Marketing opt-in checkbox. true → consent state SUBSCRIBED (single opt-in) unless `marketingOptInLevel: CONFIRMED_OPT_IN` is also sent (then PENDING and the server sends a double-opt-in confirmation email). false / null → no consent change.
   """
   acceptsMarketing: Boolean
 
-  """Email address"""
+  """
+  Email address — must be unique within the shop. Used as the login identity.
+  """
   email: String!
 
-  """First name"""
+  """First name."""
   firstName: String
 
-  """Last name"""
+  """Last name."""
   lastName: String
 
   """
-  Opt-in level. Default SINGLE_OPT_IN (signup = email proven implicitly). Set CONFIRMED_OPT_IN to force double opt-in via confirmation email.
+  Opt-in level. Defaults to SINGLE_OPT_IN (signup itself is treated as email proof). Pass CONFIRMED_OPT_IN to enforce double opt-in — the server then emails a confirmation link and leaves consent in PENDING until the buyer clicks it.
   """
   marketingOptInLevel: MarketingOptInLevel
 
-  """Password"""
+  """
+  Password (8 to 128 chars). The shop password policy may impose additional strength rules.
+  """
   password: String!
 
-  """Phone number"""
+  """Phone number (free-form)."""
   phone: String
 }
 
@@ -2150,38 +2464,44 @@ type CustomerGroup {
   taxExempt: Boolean!
 }
 
-"""Result of customer login"""
+"""Result of `customerLogin`."""
 type CustomerLoginPayload {
-  """Access token"""
+  """Access token on success; null when `userErrors` is non-empty."""
   customerAccessToken: CustomerAccessToken
 
   """
-  User errors (code is namespaced — e.g. CUSTOMER_NOT_FOUND, CUSTOMER_TOKEN_INVALID, CUSTOMER_PASSWORD_TOO_WEAK)
+  Errors carrying a stable `CustomerErrorCode` in `code` (e.g. `INVALID_CREDENTIALS`, `CUSTOMER_DISABLED`, `UNIDENTIFIED_CUSTOMER`).
   """
   userErrors: [UserError!]!
 }
 
-"""Result of token deletion (logout)"""
+"""
+Result of `customerLogout` — invalidates the current access token on the server.
+"""
 type CustomerLogoutPayload {
-  """Deleted access token"""
+  """
+  The token string that was invalidated. Useful for client-side cache clearing.
+  """
   deletedAccessToken: String
 
-  """Deleted token ID"""
+  """ID of the invalidated token record."""
   deletedCustomerAccessTokenId: String
 
   """
-  User errors (code is namespaced — e.g. CUSTOMER_NOT_FOUND, CUSTOMER_TOKEN_INVALID, CUSTOMER_PASSWORD_TOO_WEAK)
+  Errors carrying a stable `CustomerErrorCode` in `code` (e.g. `TOKEN_INVALID`, `TOKEN_EXPIRED`).
   """
   userErrors: [UserError!]!
 }
 
-"""Result of token renewal"""
+"""
+Result of `customerRefreshToken` — exchanges a valid current token for a fresh one with a later expiry.
+"""
 type CustomerRefreshTokenPayload {
-  """New access token"""
+  """Fresh access token on success; null when `userErrors` is non-empty."""
   customerAccessToken: CustomerAccessToken
 
   """
-  User errors (code is namespaced — e.g. CUSTOMER_NOT_FOUND, CUSTOMER_TOKEN_INVALID, CUSTOMER_PASSWORD_TOO_WEAK)
+  Errors carrying a stable `CustomerErrorCode` in `code` (e.g. `TOKEN_INVALID`, `TOKEN_EXPIRED`, `TOKEN_RENEWAL_FAILED`).
   """
   userErrors: [UserError!]!
 }
@@ -2230,16 +2550,18 @@ type CustomerSetDefaultAddressPayload {
   userErrors: [UserError!]!
 }
 
-"""Result of customer creation"""
+"""Result of `customerSignup`."""
 type CustomerSignupPayload {
-  """Created customer"""
+  """The created customer on success; null when `userErrors` is non-empty."""
   customer: Customer
 
-  """Access token for new customer"""
+  """
+  Access token for the new customer — saves a follow-up login round-trip.
+  """
   customerAccessToken: CustomerAccessToken
 
   """
-  User errors (code is namespaced — e.g. CUSTOMER_NOT_FOUND, CUSTOMER_TOKEN_INVALID, CUSTOMER_PASSWORD_TOO_WEAK)
+  Validation / business errors carrying a stable `CustomerErrorCode` in `code` (e.g. `TAKEN`, `INVALID`, `PASSWORD_TOO_WEAK`, `BAD_DOMAIN`).
   """
   userErrors: [UserError!]!
 }
@@ -2255,7 +2577,9 @@ input CustomerSubscribeToMarketingInput {
   marketingOptInLevel: MarketingOptInLevel
 }
 
-"""Customer business type — INDIVIDUAL (B2C) or COMPANY (B2B)."""
+"""
+Customer profile type — INDIVIDUAL (B2C buyer) or COMPANY (B2B buyer). Drives which company fields are required and which appear on tax documents.
+"""
 enum CustomerType {
   COMPANY
   INDIVIDUAL
@@ -2331,19 +2655,41 @@ Decimal money amount, JSON-serialized as String. Format: "{int}.{dec}" e.g. "10.
 """
 scalar Decimal
 
-"""Estimated delivery timeframe"""
+"""Estimated delivery window for a shipping method, in business days."""
 type DeliveryEstimate {
-  """Human-readable delivery estimate"""
+  """
+  Pre-formatted human-readable estimate (e.g. "1-2 business days"). Localised; render as-is.
+  """
   description: String
 
-  """Maximum delivery days"""
+  """Maximum expected delivery time in business days."""
   maxDays: Int
 
-  """Minimum delivery days"""
+  """Minimum expected delivery time in business days."""
   minDays: Int
 }
 
-"""Type of discount being applied"""
+"""
+Delivery destination type of a shipping method — signals whether the storefront must collect a pickup point.
+"""
+enum DeliveryType {
+  """Courier delivery to the street address — no pickup point required."""
+  HOME
+
+  """
+  Automated parcel locker — the buyer collects from a 24/7 self-service machine.
+  """
+  LOCKER
+
+  """
+  Staffed pickup point / parcel shop — the buyer collects the parcel at a counter.
+  """
+  PICKUP_POINT
+}
+
+"""
+Category of discount: `PERCENTAGE` (percent off), `FIXED_AMOUNT` (amount off), `FREE_SHIPPING` (zeroes shipping) or `BUY_X_GET_Y` (item-quantity-based).
+"""
 enum DiscountApplicationType {
   BUY_X_GET_Y
   FIXED_AMOUNT
@@ -2351,7 +2697,9 @@ enum DiscountApplicationType {
   PERCENTAGE
 }
 
-"""Error codes for discount validation"""
+"""
+Stable reasons why a discount code is not applicable to the current cart / customer.
+"""
 enum DiscountErrorCode {
   CUSTOMER_GROUP_NOT_ELIGIBLE
   CUSTOMER_NOT_ELIGIBLE
@@ -2367,42 +2715,58 @@ enum DiscountErrorCode {
   USAGE_LIMIT_REACHED
 }
 
-"""Information about a valid discount"""
+"""
+Details of a discount that the buyer entered and that is currently valid for the cart.
+"""
 type DiscountInfo {
-  """Discount code"""
+  """The discount code as entered."""
   code: String!
 
-  """Calculated discount amount"""
+  """
+  Calculated savings the discount produces against the current cart. Null when the savings cannot be computed without a cart context.
+  """
   discountAmount: Money
 
-  """Discount title"""
+  """Merchant-facing title of the discount (e.g. "Summer sale 10%")."""
   title: String!
 
-  """Type of discount"""
+  """
+  Category of the discount: `PERCENTAGE`, `FIXED_AMOUNT`, `FREE_SHIPPING` or `BUY_X_GET_Y`. Drives how `value` is interpreted.
+  """
   type: DiscountApplicationType!
 
-  """Discount value (percentage or amount)"""
+  """
+  Discount value — percent points for `PERCENTAGE`, amount (in major currency units) for `FIXED_AMOUNT`. Ignored for `FREE_SHIPPING` / `BUY_X_GET_Y`.
+  """
   value: Float!
 }
 
-"""Discount validation error"""
+"""
+Reason why a discount code is not valid for the current cart / customer.
+"""
 type DiscountValidationError {
-  """Error code"""
+  """
+  Stable reason code (e.g. `EXPIRED`, `USAGE_LIMIT_REACHED`, `MINIMUM_ORDER_NOT_MET`). Branch on this for UI behaviour.
+  """
   code: DiscountErrorCode!
 
-  """Error message"""
+  """Human-readable explanation of the validation failure."""
   message: String!
 }
 
-"""Result of validating a discount code"""
+"""
+Result of validating a discount code against a cart — preview only, no cart side effects.
+"""
 type DiscountValidationResult {
-  """Discount info (if valid)"""
+  """Discount details when `isValid` is true. Null otherwise."""
   discount: DiscountInfo
 
-  """Error details (if invalid)"""
+  """Validation failure details when `isValid` is false. Null otherwise."""
   error: DiscountValidationError
 
-  """Whether the discount code is valid"""
+  """
+  True when the code is currently applicable to the cart. When false, see `error` for the reason.
+  """
   isValid: Boolean!
 }
 
@@ -2418,7 +2782,9 @@ type Domain {
   url: URL!
 }
 
-"""Customer email marketing consent state (Prisma-derived)."""
+"""
+Email marketing consent state of a customer. NOT_SUBSCRIBED = never opted in. PENDING = single opt-in awaiting double opt-in confirmation. SUBSCRIBED = active opt-in. UNSUBSCRIBED = explicitly opted out. REDACTED = data erased on request. INVALID = email rejected (bounce / spam complaint).
+"""
 enum EmailMarketingState {
   INVALID
   NOT_SUBSCRIBED
@@ -2533,24 +2899,32 @@ type FilterValue {
   swatch: AttributeSwatch
 }
 
-"""Free shipping progress indicator"""
+"""
+Progress towards the free shipping threshold configured by the merchant — drives "Add X more to get free shipping" banners.
+"""
 type FreeShippingProgress {
-  """Current cart subtotal"""
+  """Current qualifying subtotal of the cart."""
   currentAmount: Money
 
-  """Human-readable progress message"""
+  """
+  Pre-formatted, localised banner message (e.g. "Add 15.00 PLN more for free shipping"). Render as-is when present.
+  """
   message: String
 
-  """Progress percentage (0-100)"""
+  """
+  Progress towards the threshold expressed as a percentage between 0 and 100. Use as the value of a progress bar.
+  """
   progressPercent: Float
 
-  """Whether free shipping is achieved"""
+  """True when the cart already qualifies for free shipping."""
   qualifies: Boolean!
 
-  """Amount remaining for free shipping"""
+  """
+  How much more the buyer needs to add to qualify. Zero when `qualifies` is true.
+  """
   remaining: Money
 
-  """Threshold for free shipping"""
+  """Subtotal threshold that unlocks free shipping."""
   threshold: Money
 }
 
@@ -2662,26 +3036,34 @@ type GiftCardValidation {
   isValid: Boolean!
 }
 
-"""Image with URL and metadata"""
+"""
+An image with its URL and presentation metadata. The URL accepts an `Image.url(transform: ...)` argument for responsive resizing / format selection.
+"""
 type Image {
-  """Alt text for accessibility"""
+  """
+  Alt text for accessibility / SEO. Null when the merchant has not provided one.
+  """
   altText: String
 
-  """Image height in pixels"""
+  """Native height of the source image in pixels."""
   height: Int
 
-  """Image ID"""
+  """
+  Stable image identifier. Null for ad-hoc images that are not stored as media library entries.
+  """
   id: ID
 
   """
-  ThumbHash placeholder for progressive loading (base64-encoded, ~40 chars). Decode with thumbHashToDataURL() on the client.
+  ThumbHash placeholder for progressive loading (base64-encoded, ~40 chars). Decode with `thumbHashToDataURL()` on the client to render an instant blurry preview while the full image loads.
   """
   thumbhash: String
 
-  """Image URL. Pass transform argument for resized/cropped CDN URLs."""
+  """
+  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!
 
-  """Image width in pixels"""
+  """Native width of the source image in pixels."""
   width: Int
 }
 
@@ -2761,7 +3143,7 @@ type Language {
   nativeName: String!
 }
 
-"""ISO 639-1 language code"""
+"""ISO 639-1 language code (2-letter uppercase, e.g. PL, EN, DE)."""
 enum LanguageCode {
   CS
   DA
@@ -3030,6 +3412,9 @@ type LoyaltyReward {
   """Discount percentage (if discount type)"""
   discountPercent: Float
 
+  """URL-friendly handle"""
+  handle: String!
+
   """Reward ID"""
   id: ID!
 
@@ -3048,9 +3433,6 @@ type LoyaltyReward {
   """Redemptions remaining (null = unlimited)"""
   redemptionsRemaining: Int
 
-  """URL-friendly slug"""
-  slug: String!
-
   """Minimum tier required"""
   tierRequired: LoyaltyTier
 
@@ -3180,86 +3562,99 @@ enum LoyaltyTransactionType {
   REFUND_REVERSAL
 }
 
-"""Customer mailing address"""
+"""
+A mailing address — shipping or billing — used on a cart, on the resulting order, or saved in a customer address book. Carries optional B2B fields (`taxId`, `vatNumber`) and an optional `pickupPoint` for parcel locker / collection-point delivery.
+"""
 type MailingAddress implements Node {
-  """City"""
+  """City / town."""
   city: String
 
-  """Company name"""
+  """Company name (relevant for B2B addresses)."""
   company: String
 
-  """Country"""
+  """
+  Country name in the request locale (e.g. "Poland", "Polska"). For machine logic use `countryCode`.
+  """
   country: String
 
-  """ISO 3166-1 alpha-2 country code"""
+  """ISO 3166-1 alpha-2 country code (e.g. PL, DE, US)."""
   countryCode: CountryCode
 
-  """First name"""
+  """Buyer first name."""
   firstName: String
 
   """
-  Country-aware ordered address lines. Format zależy od country: PL = [name, streetLine1, "postalCode city"]; US = [name, streetLine1, "city, state postalCode"]; default = [name, streetLine1, streetLine2, city, postalCode, country]. Use bezpośrednio jako lines w UI bez ręcznego konstruowania.
+  Country-aware ordered address lines, ready to render line by line in UI without manual formatting. The exact line layout depends on country (e.g. PL puts postal code before city, US after state).
   """
   formatted: [String!]!
 
   """
-  Single-line area summary, e.g. "Warszawa, MZ, Poland"
+  Single-line summary of the area, e.g. "Warszawa, MZ, Poland". Useful for compact display in lists.
   """
   formattedArea: String
 
-  """Unique identifier"""
+  """Stable identifier of the address."""
   id: ID!
 
-  """Whether this is default address (DoSwiftly extension)"""
+  """True when this is the default address for the owning customer."""
   isDefault: Boolean!
 
-  """Last name"""
+  """Buyer last name."""
   lastName: String
 
-  """Computed full name (firstName + " " + lastName)"""
+  """Convenience full name (`firstName` + " " + `lastName`)."""
   name: String
 
-  """Phone number"""
+  """Phone number associated with the address (free-form)."""
   phone: String
 
-  """Postal / ZIP code"""
+  """
+  Selected pickup point when the shipping method delivers to a parcel locker / collection point instead of the street address. Null for home delivery.
+  """
+  pickupPoint: PickupPoint
+
+  """Postal / ZIP code."""
   postalCode: String
 
-  """State / province"""
+  """State / province / region name."""
   state: String
 
-  """State / province code (ISO 3166-2 subdivision)"""
+  """State / province code (ISO 3166-2 subdivision, e.g. PL-MZ)."""
   stateCode: String
 
-  """First line of street address"""
+  """First line of the street address (street and house / building number)."""
   streetLine1: String
 
-  """Second line of street address"""
+  """
+  Second line of the street address (apartment, suite, floor — optional).
+  """
   streetLine2: String
 
   """
-  Per-address tax ID (Polish NIP, 10 digits z checksum). B2B use case: różne dane firmowe per adres — np. faktura na firmę matkę z NIP A, dostawa na oddział z NIP B. Distinct from `Customer.taxId` (customer-level globally).
+  Per-address buyer tax ID for B2B invoicing — Polish NIP, 10 digits with checksum. Lets B2B buyers invoice different addresses to different legal entities. Independent of `Customer.taxId` (which is the customer-wide default).
   """
   taxId: String
 
   """
-  Per-address EU VAT number (e.g. PL1234567890). B2B cross-border: różny VAT per adres dostawy. Distinct from `Customer.vatNumber` (customer-level globally).
+  Per-address EU VAT number (e.g. `PL1234567890`) for cross-border B2B. Independent of `Customer.vatNumber` (which is the customer-wide default).
   """
   vatNumber: String
 }
 
-"""Paginated mailing addresses (Relay Connection)"""
+"""Paginated list of mailing addresses (Relay Connection)."""
 type MailingAddressConnection {
-  """Address edges with cursors"""
+  """
+  Edges with the address and its cursor — use for cursor-based pagination.
+  """
   edges: [MailingAddressEdge!]!
 
-  """Address nodes (shortcut for edges.map(e => e.node))"""
+  """Address nodes — convenience shortcut for `edges.map(e => e.node)`."""
   nodes: [MailingAddress!]!
 
-  """Pagination info"""
+  """Cursor pagination info (`hasNextPage`, `endCursor`, etc.)."""
   pageInfo: PageInfo!
 
-  """Total count of addresses"""
+  """Total number of saved addresses for the customer across all pages."""
   totalCount: Int!
 }
 
@@ -3363,16 +3758,17 @@ type MenuItem {
   type: MenuItemType!
 
   """
-  Resolved URL path computed server-side (e.g., /categories/funko, /products/toy-1, /pages/about, /collections/sale). Static types resolve to /, /search, /products, /blog. HTTP type returns the manually stored URL. Null only when type is a resource link (CATEGORY/COLLECTION/PAGE/PRODUCT) and the resource was deleted.
+  Pre-resolved URL path computed server-side using a standard route convention: /categories/<handle>, /collections/<handle>, /pages/<handle>, /products/<handle>, /brands/<handle>. Static types resolve to /, /search, /products, /blog. HTTP returns the manually stored URL. Null when type is a resource link and the underlying resource was deleted. If your storefront uses non-standard routing (e.g. single-segment /<handle>), prefer reading the `resource` field instead and build URLs yourself from `resource.__typename` + `handle`.
   """
   url: URL
 }
 
-union MenuItemResource = Category | Collection | Product | ShopPage
+union MenuItemResource = Brand | Category | Collection | Product | ShopPage
 
 """Menu item link type"""
 enum MenuItemType {
   BLOG
+  BRAND
   CATALOG
   CATEGORY
   COLLECTION
@@ -3383,66 +3779,96 @@ enum MenuItemType {
   SEARCH
 }
 
-"""Monetary value with currency"""
+"""A monetary amount with its ISO 4217 currency code."""
 type Money {
-  """Decimal money amount"""
+  """
+  Amount as a decimal string in major currency units (e.g. "12.99"). String, not float — preserves precision across locales.
+  """
   amount: Decimal!
 
-  """ISO 4217 currency code"""
+  """ISO 4217 currency code (e.g. PLN, EUR, USD)."""
   currencyCode: CurrencyCode!
 }
 
 type Mutation {
-  """Add lines to cart"""
+  """
+  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!
 
-  """Apply gift card to cart"""
+  """
+  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!
 
   """
-  Complete cart → create Order (D6 — delegates do CartCompletionOrchestrator.processCart)
+  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!
 
-  """Create new cart"""
+  """
+  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!
 
-  """Apply discount codes"""
+  """
+  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!
 
-  """Remove gift card from cart"""
+  """
+  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!
 
-  """Remove lines from cart"""
+  """
+  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!
 
-  """Select payment method on cart"""
+  """
+  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.
+  """
   cartSelectPaymentMethod(input: CartSelectPaymentMethodInput!): CartSelectPaymentMethodPayload!
 
   """
-  Select shipping method on cart (D8 term unification — wcześniej cartSelectShippingRate)
+  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!
 
-  """Set billing address on cart"""
+  """
+  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!
 
-  """Set shipping address on cart"""
+  """
+  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!
 
-  """Update cart attributes"""
+  """
+  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!
 
-  """Update buyer identity"""
+  """
+  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!
 
-  """Set recipient info on gift card line item (personalised delivery)"""
+  """
+  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!
 
-  """Update cart lines"""
+  """
+  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!
 
-  """Update cart note"""
+  """
+  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!
 
   """
@@ -3458,13 +3884,19 @@ type Mutation {
   """Add customer address"""
   customerAddAddress(address: MailingAddressInput!): CustomerAddAddressPayload!
 
-  """Login customer"""
+  """
+  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!
 
-  """Logout customer (clears auth cookie)"""
+  """
+  Sign the current customer out. Invalidates the access token on the server; the SDK BFF auth helpers additionally clear the HTTP-only cookie.
+  """
   customerLogout: CustomerLogoutPayload!
 
-  """Refresh access token"""
+  """
+  Exchange a still-valid access token for a fresh one with a later expiry. Call before `expiresAt` to keep the session alive without prompting the buyer to log in again.
+  """
   customerRefreshToken: CustomerRefreshTokenPayload!
 
   """Remove customer address"""
@@ -3484,7 +3916,9 @@ type Mutation {
   """Set default address"""
   customerSetDefaultAddress(addressId: ID!): CustomerSetDefaultAddressPayload!
 
-  """Register new customer"""
+  """
+  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!
 
   """Subscribe an email to the newsletter (guest-friendly, double opt-in)."""
@@ -3506,7 +3940,7 @@ type Mutation {
   loyaltyRedeemReward(input: RedeemRewardInput!): RedeemRewardPayload!
 
   """
-  Initiate a payment session for an order — call after cartComplete when order.canCreatePayment is true
+  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!
 
@@ -3564,64 +3998,88 @@ enum NodeType {
   PRODUCT_VARIANT
 }
 
-"""Customer order summary"""
+"""
+A buyer order — the result of completing a cart. Carries totals, status, addresses, line items and the signals needed to drive payment (`canCreatePayment`, `paymentMethodType`) and a guest confirmation page (`accessToken`).
+"""
 type Order implements Node {
   """
-  Opaque access token (UUID v4) umożliwiający dostęp do podsumowania zamówienia bez sesji (guest order access via orderByToken query). Trwały per order — share dla forwarded receipts. Storefront powinien przechowywać HTTP-only cookie / sessionStorage (NIGDY localStorage). Defense-in-depth: orderByToken akceptuje opcjonalny email guard żeby ograniczyć blast radius kompromisu.
+  Opaque access token (UUID v4) that grants read access to the order summary without an authenticated session — pass it to the `orderByToken` query to build a guest confirmation page. Persistent for the lifetime of the order so it can be re-used in forwarded receipts. Store on the storefront in an HTTP-only cookie or `sessionStorage`; never in `localStorage`. As defense-in-depth, `orderByToken` also accepts an optional email guard to limit the blast radius if the token leaks.
   """
   accessToken: String!
 
   """Order custom field values (post-Opcja A unified custom fields)."""
   attributes(namespace: String): [EntityAttributeField!]!
 
-  """Czy storefront może zainicjować płatność dla tego order"""
+  """
+  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.
+  """
   canCreatePayment: Boolean!
 
-  """When order was cancelled"""
+  """When the order was cancelled. Null when not cancelled."""
   cancelledAt: DateTime
 
-  """When order was confirmed"""
+  """
+  When the order was confirmed (e.g. payment authorised / approved). Null until confirmation.
+  """
   confirmedAt: DateTime
 
-  """When order expired"""
+  """
+  When the order expired (e.g. pending payment timed out). Null when not expired.
+  """
   expiredAt: DateTime
 
-  """Fulfillment status"""
+  """
+  Fulfillment progress (UNFULFILLED, PARTIALLY_FULFILLED, FULFILLED, IN_TRANSIT, DELIVERED, PARTIALLY_RETURNED, RETURNED, LOST).
+  """
   fulfillmentStatus: OrderFulfillmentStatus!
 
-  """Unique identifier"""
+  """Stable identifier of the order."""
   id: ID!
 
-  """Line items count"""
+  """
+  Number of line items on the order (sum of distinct lines, not quantities).
+  """
   itemCount: Int!
 
   """
-  Pozycje zamówienia (top-level connection) — eliminuje N+1 vs Order.shipments.items
+  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!
 
-  """Order number (human-readable)"""
+  """
+  Human-readable order number shown to the buyer and the merchant (e.g. "1042"). Distinct from `id`.
+  """
   orderNumber: String!
 
-  """Kategoria payment method zmapowana z provider code"""
+  """
+  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).
+  """
   paymentMethodType: PaymentMethodType!
 
-  """Payment status"""
+  """
+  Payment progress (UNPAID, PENDING, AUTHORIZED, PAID, PARTIALLY_PAID, PARTIALLY_REFUNDED, REFUNDED, FAILED, CHARGEBACK, VOIDED, REFUND_PENDING).
+  """
   paymentStatus: OrderPaymentStatus!
 
-  """Order date (ISO 8601)"""
+  """
+  When the order was placed (ISO 8601). Use as the canonical "order date" in receipts.
+  """
   processedAt: DateTime!
 
   """Order shipments"""
   shipments: [Shipment!]!
 
-  """Shipping address"""
+  """
+  Shipping address snapshot at the moment the order was placed. Null for digital-only orders.
+  """
   shippingAddress: MailingAddress
 
-  """Order lifecycle status"""
+  """
+  High-level lifecycle status of the order (DRAFT, PENDING, CONFIRMED, PROCESSING, ON_HOLD, COMPLETED, CANCELLED, EXPIRED).
+  """
   status: StorefrontOrderStatus!
 
-  """Cost totals breakdown (subtotal/total/totalTax/totalShipping)"""
+  """Cost breakdown on the order (subtotal, total, tax, shipping)."""
   totals: OrderTotals!
 }
 
@@ -3649,7 +4107,9 @@ type OrderEdge {
   node: Order!
 }
 
-"""Fulfillment status of an order"""
+"""
+Fulfillment progress of an order. UNFULFILLED → PARTIALLY_FULFILLED → FULFILLED (items shipped) → IN_TRANSIT → DELIVERED. PARTIALLY_RETURNED / RETURNED reflect post-delivery returns; LOST marks a parcel that never reached the buyer.
+"""
 enum OrderFulfillmentStatus {
   DELIVERED
   FULFILLED
@@ -3724,7 +4184,9 @@ type OrderLineItemEdge {
   node: OrderLineItem!
 }
 
-"""Payment status of an order"""
+"""
+Payment status of an order. UNPAID = no payment recorded yet; PENDING = initiated, awaiting confirmation; AUTHORIZED = held but not captured; PAID = fully paid; PARTIALLY_PAID / PARTIALLY_REFUNDED = intermediate states; REFUNDED = fully refunded; FAILED, CHARGEBACK, VOIDED, REFUND_PENDING = terminal / in-flight unpaid states.
+"""
 enum OrderPaymentStatus {
   AUTHORIZED
   CHARGEBACK
@@ -3739,18 +4201,26 @@ enum OrderPaymentStatus {
   VOIDED
 }
 
-"""Order cost totals breakdown"""
+"""
+Cost totals on an order — symmetric with `CartCost` so the confirmation page renders the same breakdown the buyer saw at checkout.
+"""
 type OrderTotals {
-  """Order subtotal (before tax and shipping)"""
+  """Order subtotal — items only, before tax, shipping and discounts."""
   subtotal: Money!
 
-  """Order total (after tax and shipping)"""
+  """
+  Grand total the buyer was charged — includes taxes, shipping and discounts.
+  """
   total: Money!
 
-  """Total shipping cost"""
+  """
+  Total shipping cost on the order. Null for digital-only orders that did not go through shipping.
+  """
   totalShipping: Money
 
-  """Total tax amount"""
+  """
+  Total tax across the order. Null when the order has no taxable component.
+  """
   totalTax: Money
 }
 
@@ -3769,18 +4239,26 @@ input PackageDimensionsInput {
   width: Int
 }
 
-"""Pagination information"""
+"""Cursor pagination info for a Relay Connection."""
 type PageInfo {
-  """Cursor of last item"""
+  """
+  Cursor of the last item on the current page — opaque, base64-encoded. Echo as the `after` argument to fetch the next page.
+  """
   endCursor: String
 
-  """Whether there are more items after"""
+  """
+  True when more pages follow this one. Use to decide whether to enable a "load more" / next page action.
+  """
   hasNextPage: Boolean!
 
-  """Whether there are more items before"""
+  """
+  True when pages exist before this one (relevant for bidirectional pagination).
+  """
   hasPreviousPage: Boolean!
 
-  """Cursor of first item"""
+  """
+  Cursor of the first item on the current page — opaque, base64-encoded. Echo as the `before` argument to paginate backwards.
+  """
   startCursor: String
 }
 
@@ -3791,33 +4269,39 @@ enum PageSortKeys {
   UPDATED_AT
 }
 
-"""Input dla paymentCreate mutation"""
+"""
+Input for `paymentCreate` — initiates a payment for an order created by `cartComplete`. Idempotent on the order: a second call returns the existing still-valid session.
+"""
 input PaymentCreateInput {
   """
-  URL powrotu klienta po anulowaniu płatności — musi być na zweryfikowanej domenie sklepu
+  URL the gateway returns the buyer to after they cancel the payment. Must point to a verified domain of the shop.
   """
   cancelUrl: URL
 
-  """ID zamówienia (z cartComplete) do opłacenia"""
+  """ID of the order to pay for — `cartComplete.order.id`."""
   orderId: ID!
 
   """
-  URL powrotu klienta po płatności — musi być na zweryfikowanej domenie sklepu
+  URL the gateway returns the buyer to after a successful payment. Must point to a verified domain of the shop; rejected with `RETURN_URL_INVALID` otherwise.
   """
   returnUrl: URL
 }
 
-"""Wynik paymentCreate mutation"""
+"""Result of `paymentCreate`."""
 type PaymentCreatePayload {
-  """Utworzona sesja płatności (null gdy userErrors)"""
+  """
+  The created (or reused) payment session on success; null when `userErrors` is non-empty.
+  """
   payment: PaymentSession
 
-  """Błędy walidacji / biznesowe"""
+  """
+  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`).
+  """
   userErrors: [UserError!]!
 }
 
 """
-Sposób uruchomienia płatności po stronie klienta — storefront rozgałęzia krok po tej wartości
+How the storefront should launch the payment after `paymentCreate`. ONLINE_REDIRECT = redirect the browser to `redirectUrl`. ONLINE_EMBEDDED = render an in-page widget using `clientSecret`. INSTANT_DIRECT = the payment is already settled, check `status`. OFFLINE_MANUAL never appears here — when the order uses an offline method `canCreatePayment` is false and `paymentCreate` is not called.
 """
 enum PaymentInitiationFlow {
   INSTANT_DIRECT
@@ -3826,37 +4310,59 @@ enum PaymentInitiationFlow {
   ONLINE_REDIRECT
 }
 
-"""Payment method available for checkout"""
+"""
+A payment method offered to the buyer at checkout — what to render in the payment picker and pass to `cartSelectPaymentMethod`.
+"""
 type PaymentMethod {
-  """Description for customers"""
+  """
+  Optional buyer-facing description shown under the name (e.g. "Pay with your bank app").
+  """
   description: String
 
-  """Icon URL or path"""
+  """
+  Optional icon URL configured by the merchant. Use as the method tile artwork.
+  """
   icon: String
 
-  """Payment method ID"""
+  """
+  Stable ID of the payment method. Pass to `cartSelectPaymentMethod` to select it.
+  """
   id: ID!
 
-  """Whether this is the default payment method"""
+  """
+  True when the merchant has marked this method as the default. Pre-select it in the picker.
+  """
   isDefault: Boolean!
 
-  """Display name"""
+  """
+  Display name configured by the merchant (e.g. "BLIK", "Credit card", "Cash on delivery").
+  """
   name: String!
 
-  """Display position (lower = higher priority)"""
+  """
+  Merchant-configured display position — lower values come first in the picker.
+  """
   position: Float!
 
-  """Provider code (payu, stripe, p24, etc.)"""
+  """
+  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.
+  """
   provider: String!
 
-  """Supported currency codes"""
+  """
+  ISO 4217 currency codes the method accepts. Null when the method accepts the shop currency without restriction.
+  """
   supportedCurrencies: [String!]
 
-  """Type of payment method"""
+  """
+  Category of the method (CARD, BLIK, BANK_TRANSFER, CASH_ON_DELIVERY, OTHER). Drives iconography and copy.
+  """
   type: PaymentMethodType!
 }
 
-"""Type of payment method"""
+"""
+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.
+"""
 enum PaymentMethodType {
   BANK_TRANSFER
   BLIK
@@ -3865,30 +4371,44 @@ enum PaymentMethodType {
   OTHER
 }
 
-"""Sesja płatności utworzona dla zamówienia"""
+"""
+Payment session created for an order. Branch on `flow` to launch payment: ONLINE_REDIRECT → redirect to `redirectUrl`; ONLINE_EMBEDDED → render an in-page widget using `clientSecret`; INSTANT_DIRECT → the payment is already settled, check `status`.
+"""
 type PaymentSession {
-  """Token/secret do widgetu in-page — wypełniony dla flow ONLINE_EMBEDDED"""
+  """
+  Client secret / token for the in-page payment widget. Populated only when `flow` is ONLINE_EMBEDDED. Treat as sensitive — do not log.
+  """
   clientSecret: String
 
-  """Kiedy redirectUrl/clientSecret przestaje być ważny (ISO 8601)"""
+  """
+  When the `redirectUrl` / `clientSecret` stops being usable (ISO 8601). The storefront should call `paymentCreate` again to get a fresh session after this time.
+  """
   expiresAt: String
 
-  """Sposób uruchomienia — storefront robi switch(flow)"""
+  """
+  How the storefront should launch the payment — branch on this with `switch(flow)`.
+  """
   flow: PaymentInitiationFlow!
 
-  """ID rekordu płatności"""
+  """Stable identifier of the payment record."""
   id: ID!
 
-  """ID zamówienia"""
+  """ID of the order this payment is for."""
   orderId: ID!
 
-  """Kod providera płatności (np. PAYU)"""
+  """
+  Provider code of the integration behind the session (e.g. "PAYU", "STRIPE"). Use for analytics; do not branch UI on it — use `flow` and the order `paymentMethodType` instead.
+  """
   provider: String!
 
-  """URL hosted gateway — wypełniony dla flow ONLINE_REDIRECT"""
+  """
+  Hosted-gateway URL to redirect the buyer to. Populated only when `flow` is ONLINE_REDIRECT.
+  """
   redirectUrl: URL
 
-  """Status płatności zamówienia"""
+  """
+  Payment status of the order at the time the session was created. For INSTANT_DIRECT, this already reflects the settled outcome.
+  """
   status: OrderPaymentStatus!
 }
 
@@ -3909,6 +4429,46 @@ type PaymentSettings {
   paymentProviders: [String!]!
 }
 
+"""
+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.
+"""
+type PickupPoint {
+  """
+  Point address as a single human-readable line — show alongside the name on the confirmation page.
+  """
+  address: String
+
+  """Display name of the point as shown in the carrier widget."""
+  name: String
+
+  """
+  Identifier of the point within the provider network (e.g. an InPost parcel locker code such as `KRA010`). Pass back to `PickupPointInput.pointId` when attaching the same point to another address.
+  """
+  pointId: String!
+
+  """
+  Carrier network code that owns the point (e.g. `inpost`, `orlen`, `dpd`).
+  """
+  provider: String!
+}
+
+"""
+Pickup point (parcel locker / collection point) for a cart shipping address
+"""
+input PickupPointInput {
+  """Point address as a single line"""
+  address: String
+
+  """Human-readable point name"""
+  name: String
+
+  """Point identifier within the provider network"""
+  pointId: String!
+
+  """Courier network code (e.g. inpost, orlen, dpd)"""
+  provider: String!
+}
+
 """Points estimate for an order"""
 type PointsEstimate {
   """Base points to earn"""
@@ -4009,7 +4569,7 @@ type Product implements Node {
   """
   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.
   """
-  brand: BrandSummary
+  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.
@@ -4123,6 +4683,9 @@ type ProductAttributeDefinition {
   """Filling mode — MERCHANT | CUSTOMER | BOTH"""
   fillingMode: AttributeFillingMode!
 
+  """URL-friendly handle"""
+  handle: String!
+
   """Definition ID"""
   id: ID!
 
@@ -4149,9 +4712,6 @@ type ProductAttributeDefinition {
   """
   scopeProductId: ID
 
-  """URL-friendly slug"""
-  slug: String!
-
   """Tax class ID; null = inherit from variant"""
   taxClassId: ID
 
@@ -4424,7 +4984,9 @@ enum ProductSortKeys {
   VENDOR
 }
 
-"""Product type classification"""
+"""
+Product type classification. PHYSICAL = ships to an address (requires the shipping step). DIGITAL = delivered electronically. SERVICE = booking / appointment, no shipment. SUBSCRIPTION = recurring billing. GIFT_CARD = issues a redeemable card on completion.
+"""
 enum ProductTypeEnum {
   DIGITAL
   GIFT_CARD
@@ -4433,49 +4995,69 @@ enum ProductTypeEnum {
   SUBSCRIPTION
 }
 
-"""Product variant - purchasable unit"""
+"""
+A purchasable unit of a product — one variant out of the product variants list, identified by its `id` and described by its options.
+"""
 type ProductVariant {
   """Variant custom field values (post-Opcja A unified custom fields)."""
   attributes(namespace: String): [EntityAttributeField!]!
 
   """
-  Available stock (computed: stock - reserved). Null when track is disabled.
+  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).
   """
   availableStock: Int
 
-  """Barcode"""
+  """
+  Barcode (EAN/UPC/etc.) as set by the merchant. Null when not configured.
+  """
   barcode: String
 
-  """Compare at price (Money). Null gdy variant nie jest na promocji."""
+  """
+  Strike-through compare-at price when the variant is on sale. Null when the variant is not discounted; show the strike-through only when this is present and greater than `price`.
+  """
   compareAtPrice: Money
 
-  """Opt-in: compare-at price with conversion transparency."""
+  """Optional opt-in: `compareAtPrice` with full conversion transparency."""
   compareAtPriceWithConversion: PriceMoney
 
-  """Unique identifier"""
+  """
+  Stable identifier of the variant. Pass to `cartAddLines.variantId` to add the variant to a cart.
+  """
   id: ID!
 
-  """Variant image"""
+  """
+  Image specific to this variant. Null when the variant inherits the parent product image.
+  """
   image: Image
 
-  """Whether variant is available for purchase"""
+  """
+  True when the variant can be purchased right now (in stock, or backorder allowed by the merchant).
+  """
   isAvailable: Boolean!
 
-  """Variant price (Money). Default field — industry-standard schema."""
+  """
+  Current price of the variant in the buyer preferred currency (auto-converted from the shop base currency when multi-currency is enabled).
+  """
   price: Money!
 
   """
-  Opt-in: price with full conversion transparency. Use dla currency-converter UI.
+  Optional opt-in: `price` with full conversion transparency (original shop-currency amount, exchange rate, conversion timestamp). Use when building a currency-converter UI.
   """
   priceWithConversion: PriceMoney
 
-  """Selected options for this variant"""
+  """
+  Option values that define this variant (e.g. Size = Large, Color = Red).
+  """
   selectedOptions: [SelectedOption!]!
 
-  """SKU code"""
+  """
+  Stock-keeping unit code as set by the merchant. Null when not configured.
+  """
   sku: String
 
-  """Sort order among product variants"""
+  """
+  Display position of this variant within the parent product list. Lower values come first.
+  """
   sortOrder: Int
 
   """
@@ -4495,10 +5077,14 @@ type ProductVariant {
     near: GeoCoordinateInput
   ): StoreAvailabilityConnection
 
-  """Variant title (e.g., "Large / Red")"""
+  """
+  Display title of the variant (e.g. "Large / Red"). Composed from the variant options.
+  """
   title: String!
 
-  """Variant weight (canonical unit GRAMS — Prisma stores integer grams)"""
+  """
+  Variant weight with its unit. Stored in grams; pick a display unit on the storefront if needed. Null when the merchant has not set a weight.
+  """
   weight: Weight
 }
 
@@ -4537,10 +5123,19 @@ type Query {
   """List of all currencies supported by the system (ECB rates)"""
   allSupportedCurrencies: [Currency!]!
 
-  """Get available payment methods"""
+  """
+  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.
+  """
+  attributeOptionsSearch(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.
+  """
   availablePaymentMethods: AvailablePaymentMethods!
 
-  """Get available shipping methods for address"""
+  """
+  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!
 
   """Get live shipping rates from configured carriers"""
@@ -4554,11 +5149,11 @@ type Query {
 
   """Get single blog post"""
   blogPost(
+    """Post handle"""
+    handle: String
+
     """Post ID"""
     id: ID
-
-    """Post slug"""
-    slug: String
   ): BlogPost
 
   """List blog posts"""
@@ -4569,8 +5164,8 @@ type Query {
     """Filter by author ID"""
     authorId: String
 
-    """Filter by category slug"""
-    categorySlug: String
+    """Filter by category handle"""
+    categoryHandle: String
 
     """Filter featured posts only"""
     featured: Boolean
@@ -4584,17 +5179,21 @@ type Query {
     """Sort key"""
     sortKey: BlogPostSortKey = PUBLISHED_AT
 
-    """Filter by tag slug"""
-    tagSlug: String
+    """Filter by tag handle"""
+    tagHandle: String
   ): BlogPostConnection!
 
   """List blog tags"""
   blogTags(limit: Int = 50): [BlogTag!]!
 
-  """Get cart by ID"""
+  """
+  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
 
-  """Validate discount code preview (read-only, no cart side effects)"""
+  """
+  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!
 
   """
@@ -4624,11 +5223,11 @@ type Query {
 
   """Get category by ID or slug"""
   category(
+    """Category handle (URL-friendly)"""
+    handle: String
+
     """Category ID"""
     id: ID
-
-    """Category slug"""
-    slug: String
   ): Category
 
   """Get single collection"""
@@ -4679,13 +5278,17 @@ type Query {
     code: String!
   ): Currency
 
-  """Get authenticated customer (cookie / Authorization Bearer)"""
+  """
+  The authenticated customer for the current request. The request must carry a valid customer access token (in the `Authorization: Bearer ...` header or an HTTP-only auth cookie). Returns null for anonymous requests.
+  """
   customer: Customer
 
   """Get available customer groups"""
   customerGroups: [CustomerGroup!]
 
-  """Get single order for authenticated customer"""
+  """
+  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
 
   """Estimate points for an order amount"""
@@ -5353,17 +5956,19 @@ type SearchQuerySuggestion {
   text: String!
 }
 
-"""Selected product option"""
+"""
+One option of a product variant — e.g. `{ name: "Size", value: "Large" }`.
+"""
 type SelectedOption {
-  """Option name (e.g., "Size", "Color")"""
+  """Option name (e.g. "Size", "Color")."""
   name: String!
 
   """
-  Relational `ProductOptionValue.id` — stable FK reference. Null only for legacy variants whose option values have not yet been migrated to the relational model.
+  Stable ID of the option value — useful as a key when rendering variant selectors. Null only for legacy variants not yet migrated to relational option values.
   """
   optionValueId: ID
 
-  """Option value (e.g., "Large", "Red")"""
+  """Option value for this variant (e.g. "Large", "Red")."""
   value: String!
 }
 
@@ -5509,48 +6114,62 @@ enum ShipmentStatus {
   RETURNED
 }
 
-"""Address input for shipping calculation"""
+"""
+Destination address used to evaluate which shipping methods are available for a cart. Country is required; the rest are optional and improve carrier rate accuracy when provided.
+"""
 input ShippingAddressInput {
-  """City"""
+  """City / town."""
   city: String
 
-  """ISO 3166-1 alpha-2 country code"""
+  """
+  Destination country (ISO 3166-1 alpha-2). Required — drives carrier eligibility and tax/region rules.
+  """
   country: CountryCode!
 
-  """Email address"""
+  """
+  Buyer email — useful when the shipping carrier needs notification contact details.
+  """
   email: String
 
-  """First name"""
+  """Buyer first name."""
   firstName: String
 
-  """Last name"""
+  """Buyer last name."""
   lastName: String
 
-  """Phone number"""
+  """Buyer phone number (free-form)."""
   phone: String
 
-  """Postal / ZIP code"""
+  """Postal / ZIP code — required by most carriers for accurate rates."""
   postalCode: String
 
-  """State / province / region"""
+  """State / province / region."""
   state: String
 
-  """First line of street address"""
+  """First line of the street address (street and house / building number)."""
   streetLine1: String
 }
 
-"""Shipping carrier information"""
+"""
+Shipping carrier associated with a shipping method (e.g. InPost, DPD, DHL).
+"""
 type ShippingCarrier {
-  """Carrier provider ID"""
+  """
+  Stable carrier identifier. Null when the method does not map to a registered carrier (e.g. local pickup configured by the merchant).
+  """
   id: ID
 
-  """Carrier logo URL"""
+  """
+  URL of the carrier logo. Use for the method tile in the shipping picker.
+  """
   logoUrl: String
 
-  """Carrier name (e.g., InPost, DPD, DHL)"""
+  """Carrier display name (e.g. "InPost", "DPD", "DHL")."""
   name: String!
 
-  """Service code"""
+  """
+  Carrier service code as configured by the merchant (e.g. "inpost_paczkomat"). Useful when integrating carrier widgets.
+  """
   serviceCode: String
 }
 
@@ -5562,8 +6181,10 @@ type Shop {
   """Bot protection configuration (platform-level)"""
   botProtection: BotProtectionInfo
 
-  """Industry-standard brand metadata (logo + slogan + colors)"""
-  brand: Brand
+  """
+  Shop brand metadata (logo + slogan + colors). Tenant-scoped (vs canonical product `Brand` entity used in `Product.brand`).
+  """
+  brand: ShopBrand
 
   """Complete branding configuration"""
   branding: ShopBranding
@@ -5670,6 +6291,27 @@ type ShopAddress {
   streetLine2: String
 }
 
+"""Shop brand metadata (logo, colors, slogan)"""
+type ShopBrand {
+  """Primary + secondary brand colors"""
+  colors: BrandColors
+
+  """Cover image / hero banner"""
+  coverImage: Image
+
+  """Primary logo"""
+  logo: Image
+
+  """Short brand description"""
+  shortDescription: String
+
+  """Marketing slogan / tagline"""
+  slogan: String
+
+  """Square logo variant (favicons, app tiles)"""
+  squareLogo: Image
+}
+
 """Shop branding configuration"""
 type ShopBranding {
   """Brand colors"""
@@ -5860,7 +6502,9 @@ type StoreAvailabilityEdge {
   node: StoreAvailability!
 }
 
-"""Lifecycle status of an order"""
+"""
+High-level lifecycle of an order. DRAFT (not yet placed) → PENDING (placed, awaiting confirmation) → CONFIRMED → PROCESSING → COMPLETED. ON_HOLD pauses the order; CANCELLED and EXPIRED are terminal states.
+"""
 enum StorefrontOrderStatus {
   CANCELLED
   COMPLETED
@@ -5992,15 +6636,23 @@ type UrlRedirectConnection {
   pageInfo: PageInfo!
 }
 
-"""User-facing error from mutations"""
+"""
+A validation or business error returned alongside a mutation result. Surfaced as `userErrors[]`; the cart/order itself is null when the mutation could not be applied. Always branch on `code` for UI behaviour — `message` is translated and locale-dependent.
+"""
 type UserError {
-  """Error code"""
+  """
+  Stable machine-readable code (e.g. `CART_NOT_FOUND`, `NOT_ENOUGH_IN_STOCK`, `INVALID_DISCOUNT_CODE`). The list of possible codes is defined per mutation by `CartErrorCode`, `CustomerErrorCode`, `PaymentErrorCode`, etc.
+  """
   code: String
 
-  """Path to field that caused error"""
+  """
+  Path of the input field that caused the error (e.g. `["input", "lines", 0, "quantity"]`). Use to highlight the offending control in a form.
+  """
   field: [String!]
 
-  """Error message"""
+  """
+  Human-readable error message localised to the request locale (e.g. `Accept-Language`). For display only.
+  """
   message: String!
 }
 
@@ -6013,16 +6665,18 @@ input VariantOptionFilter {
   value: String!
 }
 
-"""Weight value with unit"""
+"""A weight value paired with its unit."""
 type Weight {
-  """Weight unit"""
+  """Unit of the weight (GRAMS, KILOGRAMS, OUNCES or POUNDS)."""
   unit: WeightUnit!
 
-  """Weight value"""
+  """Weight magnitude, interpreted according to `unit`."""
   value: Float!
 }
 
-"""Weight unit (GRAMS canonical, KILOGRAMS/OUNCES/POUNDS for display)"""
+"""
+Weight unit. GRAMS is the canonical storage unit; KILOGRAMS / OUNCES / POUNDS are display variants for shipping and checkout UI.
+"""
 enum WeightUnit {
   GRAMS
   KILOGRAMS