@doswiftly/storefront-operations 16.1.0 → 18.0.0

package/README.md

@@ -380,12 +380,13 @@ full executable body of each operation.
 | `CartSetShippingAddress` | Phase 3 unify-cart-graphql-surface: wszystkie fulfillment + payment + completion operations teraz na Cart aggregate (zamiast Checkout dual-aggregate). Klient robi typowy checkout flow: cart create/add items → setShipping/Billing/Method → selectPayment → (optional) applyGiftCard → cartComplete → Order created. Sets the shipping address on the cart (full replace, not patch). Triggers cart re-pricing (tax recalculation per address country/region). Address format validated against `CartAddressInput` constraints (firstName/lastName/streetLine1/city/country/postalCode required). Errors: `INVALID_ADDRESS`, `CART_NOT_FOUND`. |
 | `CartSetBillingAddress` | Sets the billing address on the cart (full replace). Independent of shipping address — pass it explicitly even when "billing same as shipping". Errors: `INVALID_ADDRESS`, `CART_NOT_FOUND`. |
 | `CartSelectShippingMethod` | Selects a shipping method by `shippingMethodId` (typed `ID!`, a stable shipping-method UUID — NOT a per-request token). The id comes from a list of methods available for the current address + cart subtotal (queryable separately). Errors: `SHIPPING_METHOD_REQUIRED`, `ZIP_CODE_NOT_SUPPORTED`, `CART_NOT_FOUND`. |
-| `CartSelectPaymentMethod` | Selects a payment method by `paymentMethodId` (UUID from `availablePaymentMethods` query). Validates existence + active status; no pre-authorization performed here. Errors: `PAYMENT_METHOD_REQUIRED`, `INVALID_PAYMENT`, `CART_NOT_FOUND`. |
+| `CartSelectPaymentMethod` | Selects a payment method on the cart by category (`methodType` — BLIK, CARD, BANK_TRANSFER, ...). Optional `preferredProvider` overrides the merchant priority when the buyer explicitly picks a gateway from `PaymentMethod.providersAvailable`. The backend resolves the gateway routing from `MerchantPaymentConfig` at `cartComplete`; the selection persisted here is the category. Errors: `PAYMENT_METHOD_REQUIRED`, `CART_NOT_FOUND`, `CART_UNAUTHENTICATED`. |
 | `CartApplyGiftCard` | Applies a gift card to the cart, stackable with discount codes. Consumption is FIFO: each card consumes `min(remainingBalance, paymentDue)` against the current cart total in the order they were applied. The gift card balance is NOT debited yet — actual deduction happens atomically at `cartComplete`. Errors: `GIFT_CARD_NOT_FOUND`, `GIFT_CARD_DEPLETED`, `GIFT_CARD_UNUSABLE`. |
 | `CartRemoveGiftCard` | Removes a gift card from the applied list and recalculates FIFO `appliedAmount` for the remaining cards. Since gift card balances are only debited at `cartComplete`, removing before completion has no effect on the underlying gift card balance. |
 | `CartUpdateGiftCardRecipient` | Sets per-line-item recipient details (name, email, message) for digital gift card products in the cart (line items where the variant represents a gift-card SKU). Required before `cartComplete` for any line item with a gift-card variant. Recipient details propagated to the resulting order. |
 | `CartComplete` | Finalizes the cart — creates the `Order`, deducts gift cards, sends order-created confirmation — all atomically. **Idempotent on `idempotencyKey`** (auto-generated from cartId + minute timestamp if caller omits it). Returns `order` field after completion. Note: `paymentUrl` is intentionally NOT in payload — for hosted gateways (online providers) the storefront calls a separate `paymentCreate` mutation after this returns (check `order.canCreatePayment` first). Errors: `EMAIL_REQUIRED`, `SHIPPING_ADDRESS_REQUIRED`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_REQUIRED`, `INSUFFICIENT_STOCK`, `ALREADY_COMPLETED`. |
-| `PaymentCreate` | Initiates a payment session for an order created by `cartComplete` — call this when `order.canCreatePayment` is `true` (orders with an offline payment method like cash-on-delivery skip this step). `orderId` is required; `returnUrl` / `cancelUrl` are optional and, when supplied, must point to a verified domain of the shop (open-redirect protected). Branch on the returned `payment.flow`: `ONLINE_REDIRECT` → redirect to `payment.redirectUrl`, `ONLINE_EMBEDDED` → render a widget with `payment.clientSecret`, `INSTANT_DIRECT` → already settled, read `payment.status`. Public, but ownership-checked — an authenticated customer cannot pay for another customer's order. **Idempotent** — calling it again for the same order returns the existing still-valid session instead of creating a duplicate (safe to retry). Rate limit: 5 requests/minute. `userErrors[].code`: `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `INVALID_ID_FORMAT`, `PAYMENT_FAILED`. |
+| `PaymentCreate` | Initiates a payment session for an order created by `cartComplete` — call this when `order.canCreatePayment` is `true` (orders with an offline payment method like cash-on-delivery skip this step). `orderId` is required; `returnUrl` / `cancelUrl` are optional and, when supplied, must point to a verified domain of the shop (open-redirect protected). Branch on the returned `payment.flow`: `ONLINE_REDIRECT` → redirect to `payment.redirectUrl`, `ONLINE_EMBEDDED` → render a widget with `payment.clientSecret`, `INSTANT_DIRECT` → already settled, read `payment.status`. Public, but ownership-checked — an authenticated customer cannot pay for another customer's order. **Idempotent** — calling it again for the same order returns the existing still-valid session instead of creating a duplicate (safe to retry). Rate limit: 5 requests/minute. `userErrors[].code`: `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `INVALID_ID_FORMAT`, `PAYMENT_FAILED`, `INSTRUMENT_PRESELECTION_FAILED`. `warnings[]` array zawiera `INSTRUMENT_CLEARED_FOR_RETRY` post-auto-clear instrument-specific failure (storefront retry hint: next attempt uses gateway default landing). |
+| `CartClearPaymentSelection` | Clears all payment selection state on the cart in a single atomic operation. Use for accordion "back to method picker" flows w storefront UI. Idempotent — calling twice yields the same end state. Cart MUSI być `ACTIVE` (CONVERTED carts reject z `ALREADY_COMPLETED`). Rate limit: 30 requests/minute per IP+shop. |
 
 #### Return Mutations
 
@@ -487,7 +488,7 @@ full executable body of each operation.
 | `Cart` | `Cart` | Full cart shape — totals, line items (paginated up to 100), buyer identity, applied discount codes + allocations, note, custom attributes, plus fulfillment fields (email/phone/addresses/shipping method/payment method/applied gift cards). Spread on the cart drawer / cart page; refetch after every cart mutation including completion lifecycle. |
 | `CartShippingMethod` | `CartShippingMethod` | Shipping method selected on a cart (D8 term unification — wcześniej ShippingRate). Returned przez `cart.selectedShippingMethod` po `cartSelectShippingMethod` mutation. |
 | `CartAppliedGiftCard` | `CartAppliedGiftCard` | Gift card applied to a cart — `id` is the stable handle the storefront passes to `cartRemoveGiftCard` (no need to keep the raw code around). Plus masked code for display, last 4 chars for matching, applied amount + remaining balance. Balance NIE debited yet — actual deduction atomically at `cartComplete`. |
-| `CartSelectedPaymentMethod` | `PaymentMethod` | Payment method (integration provider) selected on a cart — id, name, provider code, type category (CARD/BLIK/BANK_TRANSFER/etc.), icon, description, isDefault, supportedCurrencies. Storefront UI używa do iconography + selection display. |
+| `CartSelectedPaymentMethod` | `PaymentMethod` | Payment method (integration provider) selected on a cart — id, name, provider code, type category (CARD/BLIK/BANK_TRANSFER/etc.), icon image (transformable), description, isDefault, supportedCurrencies. Storefront UI używa do iconography + selection display. |
 
 #### Shop
 
@@ -508,9 +509,11 @@ full executable body of each operation.
 
 | Fragment | On Type | Description |
 | --- | --- | --- |
-| `PaymentMethod` | `PaymentMethod` | Single payment method enabled for the shop — type (CARD / BANK_TRANSFER / BLIK / PAYPAL / APPLE_PAY / GOOGLE_PAY / CASH_ON_DELIVERY / OTHER), provider, icon, supported currencies, default flag, sort position. Spread on the checkout payment step. |
+| `PaymentInstrument` | `PaymentInstrument` | A single concrete instrument exposed by a gateway provider (BLIK code, branded bank, wallet, card brand). Pass `code` as `preferredInstrument` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway. `displayHint` is a semantic UX hint (`PROMINENT_BUTTON`, `BRANDED_TILE`, `DROPDOWN_OPTION`, `RADIO_OPTION`) — storefront branches rendering accordingly. `enabled: false` means the gateway reported the instrument as temporarily disabled — gray out, don't hide. |
+| `PaymentMethod` | `PaymentMethod` | Single payment method enabled for the shop — method-centric. `type` is the category (CARD, BLIK, BANK_TRANSFER, INSTALLMENT, WALLET, CASH_ON_DELIVERY, OTHER) — drive iconography here. `provider`, `providersAvailable`, `preferredProvider` are `PaymentProvider` enum (UPPERCASE: `PAYU`, `PRZELEWY24`, ...). `available` is `false` when the resolving gateway is temporarily unavailable or reported the method as disabled — gray-out the tile, don't hide it; `unavailableReason` carries the diagnostic. `instruments` lists concrete gateway-side instruments (BLIK code, branded banks, wallets) when the gateway exposes granular data — pass `code` as `preferredInstrument` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway. Spread on the checkout payment step. |
 | `AvailablePaymentMethods` | `AvailablePaymentMethods` | Active payment methods list with the merchant's `defaultMethod`. Returned by the `availablePaymentMethods` query. |
 | `PaymentSession` | `PaymentSession` | Initiated payment session for an order — returned by the `paymentCreate` mutation. Branch on `flow`: `ONLINE_REDIRECT` (redirect the browser to `redirectUrl`), `ONLINE_EMBEDDED` (render an in-page widget with `clientSecret`), `INSTANT_DIRECT` (settled with no UI — read `status`). `expiresAt` is ISO 8601, present when the gateway session has a TTL. |
+| `PaymentWarning` | `PaymentWarning` | Non-blocking signal emitted alongside `userErrors[]` in `paymentCreate` payload — backend state change context (e.g. an auto-clear of preselected instrument after gateway rejection). Pre-translated by backend per shop locale. `code === 'INSTRUMENT_CLEARED_FOR_RETRY'` signals storefront that the next `paymentCreate` will land on the gateway default landing page (server-side cleared `Order.paymentInstrumentCode` after `INSTRUMENT_PRESELECTION_FAILED`). `retryHint` is optional context for UI dispatch — currently unused for `INSTRUMENT_CLEARED_FOR_RETRY`, reserved for future warning codes. |
 
 #### Shipments / Tracking
 
@@ -518,7 +521,7 @@ full executable body of each operation.
 | --- | --- | --- |
 | `ShipmentEvent` | `ShipmentEvent` | One tracking event in the shipment timeline — status, description, location, timestamp. Spread on the tracking page timeline. |
 | `ShipmentPackage` | `ShipmentPackage` | Physical package metadata (weight + dimensions). Used in the merchant's label generation; storefronts rarely render this directly. |
-| `ShipmentItem` | `ShipmentItem` | One item in a shipment — title, variant, sku, quantity, image URL. Spread inside `Shipment.items[]` for the tracking page item list. |
+| `ShipmentItem` | `ShipmentItem` | One item in a shipment — title, variant, sku, quantity, live variant image (transformable). Spread inside `Shipment.items[]` for the tracking page item list. `image` is live from the current variant (snapshot fallback when variant has been deleted since fulfillment — returns null, render a placeholder). |
 | `Shipment` | `Shipment` | Full shipment shape — provider, tracking number + URL, label URL, status, ETA, recipient address, packages, items, full event timeline. Spread on the tracking page. |
 | `ShipmentBasic` | `Shipment` | Lightweight shipment shape — id, tracking number + URL, status, dates. No items / events / address. Use for order summary cards or on the public `shipmentByTrackingNumber` query. |
 
@@ -544,7 +547,7 @@ full executable body of each operation.
 
 | Fragment | On Type | Description |
 | --- | --- | --- |
-| `ShippingCarrier` | `ShippingCarrier` | Carrier offering the shipping method — id, display name, logo URL, internal service code. |
+| `ShippingCarrier` | `ShippingCarrier` | Carrier offering the shipping method — id, display name, logo image (transformable), internal service code. |
 | `DeliveryEstimate` | `DeliveryEstimate` | Estimated delivery window — `minDays` to `maxDays` plus a human-readable description (e.g. "2-4 business days"). |
 | `FreeShippingProgress` | `FreeShippingProgress` | Free-shipping progress info — `qualifies` flag, current cart amount, threshold, remaining to qualify, percent progress, and a localized message ("Add 20 PLN more for free shipping"). Use to render a free-shipping progress bar in the cart drawer. |
 | `AvailableShippingMethod` | `AvailableShippingMethod` | One shipping method offered for the destination + cart — id, name, carrier, price, free-shipping progress, estimated delivery, sort order. `deliveryType` signals whether to render a pickup-point / locker picker (`HOME` vs `PICKUP_POINT` / `LOCKER`) so the storefront does not have to infer it from the method name. Spread on the checkout shipping step. |
@@ -553,7 +556,7 @@ full executable body of each operation.
 
 | Fragment | On Type | Description |
 | --- | --- | --- |
-| `AttributeSwatch` | `AttributeSwatch` | Visual swatch for an attribute filter value — color hex (for color filters) or image URL (for pattern/material swatches). |
+| `AttributeSwatch` | `AttributeSwatch` | Visual swatch for an attribute filter value — color hex (for color filters) or image (for pattern/material swatches). |
 | `AttributeRangeBounds` | `AttributeRangeBounds` | Numeric range bounds for slider-style filters — min, max, currency code (when relevant). |
 | `AttributeFilterValue` | `AttributeFilterValue` | One discrete value in a filterable attribute (e.g. "Red" for the Color filter). Includes `productCount` in the current listing context (for "(12)" badges next to filter values), optional swatch and price modifier. |
 | `AttributeDefinition` | `AttributeDefinition` | Filterable attribute exposed on the storefront — name, type (SELECT / CHECKBOX / SLIDER / etc.), filterability flags, display order, and either discrete `filterValues[]` or numeric `rangeBounds`. Spread inside `availableFilters.attributes[]`. |

package/fragments.graphql

@@ -510,6 +510,7 @@ fragment Cart on Cart {
   selectedPaymentMethod {
     ...CartSelectedPaymentMethod
   }
+  selectedPaymentInstrument
   appliedGiftCards {
     ...CartAppliedGiftCard
   }
@@ -549,13 +550,15 @@ fragment CartAppliedGiftCard on CartAppliedGiftCard {
   }
 }
 
-# Payment method (integration provider) selected on a cart — id, name, provider code, type category (CARD/BLIK/BANK_TRANSFER/etc.), icon, description, isDefault, supportedCurrencies. Storefront UI używa do iconography + selection display.
+# Payment method (integration provider) selected on a cart — id, name, provider code, type category (CARD/BLIK/BANK_TRANSFER/etc.), icon image (transformable), description, isDefault, supportedCurrencies. Storefront UI używa do iconography + selection display.
 fragment CartSelectedPaymentMethod on PaymentMethod {
   id
   name
   provider
   type
-  icon
+  icon {
+    ...ImageThumbnail
+  }
   description
   isDefault
   supportedCurrencies
@@ -700,17 +703,44 @@ fragment ShopConfigFields on Shop {
 # Payment Methods
 # ============================================
 
-# Single payment method enabled for the shop — type (CARD / BANK_TRANSFER / BLIK / PAYPAL / APPLE_PAY / GOOGLE_PAY / CASH_ON_DELIVERY / OTHER), provider, icon, supported currencies, default flag, sort position. Spread on the checkout payment step.
+# A single concrete instrument exposed by a gateway provider (BLIK code, branded bank, wallet, card brand). Pass `code` as `preferredInstrument` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway. `displayHint` is a semantic UX hint (`PROMINENT_BUTTON`, `BRANDED_TILE`, `DROPDOWN_OPTION`, `RADIO_OPTION`) — storefront branches rendering accordingly. `enabled: false` means the gateway reported the instrument as temporarily disabled — gray out, don't hide.
+fragment PaymentInstrument on PaymentInstrument {
+  provider
+  code
+  type
+  displayName
+  displayHint
+  brandImage {
+    ...ImageThumbnail
+  }
+  enabled
+}
+
+# Single payment method enabled for the shop — method-centric.
+# `type` is the category (CARD, BLIK, BANK_TRANSFER, INSTALLMENT, WALLET, CASH_ON_DELIVERY, OTHER) — drive iconography here.
+# `provider`, `providersAvailable`, `preferredProvider` are `PaymentProvider` enum (UPPERCASE: `PAYU`, `PRZELEWY24`, ...).
+# `available` is `false` when the resolving gateway is temporarily unavailable or reported the method as disabled — gray-out the tile, don't hide it; `unavailableReason` carries the diagnostic.
+# `instruments` lists concrete gateway-side instruments (BLIK code, branded banks, wallets) when the gateway exposes granular data — pass `code` as `preferredInstrument` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway.
+# Spread on the checkout payment step.
 fragment PaymentMethod on PaymentMethod {
   id
   name
   provider
   type
-  icon
+  icon {
+    ...ImageThumbnail
+  }
   description
   isDefault
   supportedCurrencies
   position
+  providersAvailable
+  preferredProvider
+  available
+  unavailableReason
+  instruments {
+    ...PaymentInstrument
+  }
 }
 
 # Active payment methods list with the merchant's `defaultMethod`. Returned by the `availablePaymentMethods` query.
@@ -735,6 +765,13 @@ fragment PaymentSession on PaymentSession {
   expiresAt
 }
 
+# Non-blocking signal emitted alongside `userErrors[]` in `paymentCreate` payload — backend state change context (e.g. an auto-clear of preselected instrument after gateway rejection). Pre-translated by backend per shop locale. `code === 'INSTRUMENT_CLEARED_FOR_RETRY'` signals storefront that the next `paymentCreate` will land on the gateway default landing page (server-side cleared `Order.paymentInstrumentCode` after `INSTRUMENT_PRESELECTION_FAILED`). `retryHint` is optional context for UI dispatch — currently unused for `INSTRUMENT_CLEARED_FOR_RETRY`, reserved for future warning codes.
+fragment PaymentWarning on PaymentWarning {
+  message
+  code
+  retryHint
+}
+
 # ============================================
 # Discount Code Validation
 # ============================================
@@ -767,14 +804,16 @@ fragment ShipmentPackage on ShipmentPackage {
   height
 }
 
-# One item in a shipment — title, variant, sku, quantity, image URL. Spread inside `Shipment.items[]` for the tracking page item list.
+# One item in a shipment — title, variant, sku, quantity, live variant image (transformable). Spread inside `Shipment.items[]` for the tracking page item list. `image` is live from the current variant (snapshot fallback when variant has been deleted since fulfillment — returns null, render a placeholder).
 fragment ShipmentItem on ShipmentItem {
   id
   title
   variantTitle
   sku
   quantity
-  imageUrl
+  image {
+    ...ImageThumbnail
+  }
 }
 
 # Full shipment shape — provider, tracking number + URL, label URL, status, ETA, recipient address, packages, items, full event timeline. Spread on the tracking page.
@@ -848,7 +887,9 @@ fragment ReturnItem on ReturnItem {
   productTitle
   variantTitle
   sku
-  imageUrl
+  image {
+    ...ImageThumbnail
+  }
   quantity
   reason
   condition
@@ -942,11 +983,13 @@ fragment GiftCardValidation on GiftCardValidation {
 # Shipping Methods
 # ============================================
 
-# Carrier offering the shipping method — id, display name, logo URL, internal service code.
+# Carrier offering the shipping method — id, display name, logo image (transformable), internal service code.
 fragment ShippingCarrier on ShippingCarrier {
   id
   name
-  logoUrl
+  logo {
+    ...ImageThumbnail
+  }
   serviceCode
 }
 
@@ -999,10 +1042,12 @@ fragment AvailableShippingMethod on AvailableShippingMethod {
 # Attribute Filters
 # ============================================
 
-# Visual swatch for an attribute filter value — color hex (for color filters) or image URL (for pattern/material swatches).
+# Visual swatch for an attribute filter value — color hex (for color filters) or image (for pattern/material swatches).
 fragment AttributeSwatch on AttributeSwatch {
   colorHex
-  imageUrl
+  image {
+    ...ImageThumbnail
+  }
 }
 
 # Numeric range bounds for slider-style filters — min, max, currency code (when relevant).
@@ -1105,7 +1150,9 @@ fragment LoyaltyTier on LoyaltyTier {
   customBenefits {
     name
     description
-    icon
+    icon {
+      ...ImageThumbnail
+    }
   }
 }
 
@@ -1262,7 +1309,9 @@ fragment ProductReview on ProductReview {
   content
   pros
   cons
-  images
+  images {
+    ...ImageThumbnail
+  }
   authorName
   isVerifiedPurchase
   helpfulCount
@@ -1510,7 +1559,7 @@ fragment MenuItem on MenuItem {
     ... on Collection { id handle title }
     ... on ShopPage { id handle title }
     ... on Product { id handle title }
-    ... on Brand { id handle name logo }
+    ... on Brand { id handle name logo { ...ImageThumbnail } }
   }
   image {
     ...Image
@@ -1527,7 +1576,7 @@ fragment MenuItem on MenuItem {
       ... on Collection { id handle title }
       ... on ShopPage { id handle title }
       ... on Product { id handle title }
-      ... on Brand { id handle name logo }
+      ... on Brand { id handle name logo { ...ImageThumbnail } }
     }
     items {
       id
@@ -1541,7 +1590,7 @@ fragment MenuItem on MenuItem {
         ... on Collection { id handle title }
         ... on ShopPage { id handle title }
         ... on Product { id handle title }
-        ... on Brand { id handle name logo }
+        ... on Brand { id handle name logo { ...ImageThumbnail } }
       }
     }
   }

package/llms-full.txt

@@ -1,7 +1,7 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **16.1.0**
-> 52 queries · 40 mutations · 102 fragments
+> Schema version: **18.0.0**
+> 52 queries · 41 mutations · 104 fragments
 
 Auto-generated from `.graphql` source files. Do not edit by hand — this file is
 regenerated on every release to match the published schema.
@@ -1975,7 +1975,7 @@ mutation CartSelectShippingMethod($input: CartSelectShippingMethodInput!) {
 
 **Section**: Cart Completion Mutations
 
-**Description**: Selects a payment method by `paymentMethodId` (UUID from `availablePaymentMethods` query). Validates existence + active status; no pre-authorization performed here. Errors: `PAYMENT_METHOD_REQUIRED`, `INVALID_PAYMENT`, `CART_NOT_FOUND`.
+**Description**: Selects a payment method on the cart by category (`methodType` — BLIK, CARD, BANK_TRANSFER, ...). Optional `preferredProvider` overrides the merchant priority when the buyer explicitly picks a gateway from `PaymentMethod.providersAvailable`. The backend resolves the gateway routing from `MerchantPaymentConfig` at `cartComplete`; the selection persisted here is the category. Errors: `PAYMENT_METHOD_REQUIRED`, `CART_NOT_FOUND`, `CART_UNAUTHENTICATED`.
 
 **Variables**:
 - `$input`: `CartSelectPaymentMethodInput!`
@@ -2115,12 +2115,12 @@ mutation CartComplete($input: CartCompleteInput!) {
 
 **Section**: Cart Completion Mutations
 
-**Description**: Initiates a payment session for an order created by `cartComplete` — call this when `order.canCreatePayment` is `true` (orders with an offline payment method like cash-on-delivery skip this step). `orderId` is required; `returnUrl` / `cancelUrl` are optional and, when supplied, must point to a verified domain of the shop (open-redirect protected). Branch on the returned `payment.flow`: `ONLINE_REDIRECT` → redirect to `payment.redirectUrl`, `ONLINE_EMBEDDED` → render a widget with `payment.clientSecret`, `INSTANT_DIRECT` → already settled, read `payment.status`. Public, but ownership-checked — an authenticated customer cannot pay for another customer's order. **Idempotent** — calling it again for the same order returns the existing still-valid session instead of creating a duplicate (safe to retry). Rate limit: 5 requests/minute. `userErrors[].code`: `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `INVALID_ID_FORMAT`, `PAYMENT_FAILED`.
+**Description**: Initiates a payment session for an order created by `cartComplete` — call this when `order.canCreatePayment` is `true` (orders with an offline payment method like cash-on-delivery skip this step). `orderId` is required; `returnUrl` / `cancelUrl` are optional and, when supplied, must point to a verified domain of the shop (open-redirect protected). Branch on the returned `payment.flow`: `ONLINE_REDIRECT` → redirect to `payment.redirectUrl`, `ONLINE_EMBEDDED` → render a widget with `payment.clientSecret`, `INSTANT_DIRECT` → already settled, read `payment.status`. Public, but ownership-checked — an authenticated customer cannot pay for another customer's order. **Idempotent** — calling it again for the same order returns the existing still-valid session instead of creating a duplicate (safe to retry). Rate limit: 5 requests/minute. `userErrors[].code`: `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `INVALID_ID_FORMAT`, `PAYMENT_FAILED`, `INSTRUMENT_PRESELECTION_FAILED`. `warnings[]` array zawiera `INSTRUMENT_CLEARED_FOR_RETRY` post-auto-clear instrument-specific failure (storefront retry hint: next attempt uses gateway default landing).
 
 **Variables**:
 - `$input`: `PaymentCreateInput!`
 
-**Fragments used**: `PaymentSession`, `UserError`
+**Fragments used**: `PaymentSession`, `PaymentWarning`, `UserError`
 
 **GraphQL**:
 ```graphql
@@ -2132,6 +2132,37 @@ mutation PaymentCreate($input: PaymentCreateInput!) {
     userErrors {
       ...UserError
     }
+    warnings {
+      ...PaymentWarning
+    }
+  }
+}
+```
+
+### Mutation: `CartClearPaymentSelection`
+
+**Section**: Cart Completion Mutations
+
+**Description**: Clears all payment selection state on the cart in a single atomic operation. Use for accordion "back to method picker" flows w storefront UI. Idempotent — calling twice yields the same end state. Cart MUSI być `ACTIVE` (CONVERTED carts reject z `ALREADY_COMPLETED`). Rate limit: 30 requests/minute per IP+shop.
+
+**Variables**:
+- `$input`: `CartClearPaymentSelectionInput!`
+
+**Fragments used**: `Cart`, `CartWarning`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CartClearPaymentSelection($input: CartClearPaymentSelectionInput!) {
+  cartClearPaymentSelection(input: $input) {
+    cart {
+      ...Cart
+    }
+    userErrors {
+      ...UserError
+    }
+    warnings {
+      ...CartWarning
+    }
   }
 }
 ```
@@ -3171,6 +3202,7 @@ fragment Cart on Cart {
   selectedPaymentMethod {
     ...CartSelectedPaymentMethod
   }
+  selectedPaymentInstrument
   appliedGiftCards {
     ...CartAppliedGiftCard
   }
@@ -3235,7 +3267,9 @@ fragment CartAppliedGiftCard on CartAppliedGiftCard {
 
 **Section**: Cart
 
-**Description**: Payment method (integration provider) selected on a cart — id, name, provider code, type category (CARD/BLIK/BANK_TRANSFER/etc.), icon, description, isDefault, supportedCurrencies. Storefront UI używa do iconography + selection display.
+**Description**: Payment method (integration provider) selected on a cart — id, name, provider code, type category (CARD/BLIK/BANK_TRANSFER/etc.), icon image (transformable), description, isDefault, supportedCurrencies. Storefront UI używa do iconography + selection display.
+
+**Uses fragments**: `ImageThumbnail`
 
 **GraphQL**:
 ```graphql
@@ -3244,7 +3278,9 @@ fragment CartSelectedPaymentMethod on PaymentMethod {
   name
   provider
   type
-  icon
+  icon {
+    ...ImageThumbnail
+  }
   description
   isDefault
   supportedCurrencies
@@ -3470,11 +3506,36 @@ fragment ShopConfigFields on Shop {
 }
 ```
 
+### Fragment: `PaymentInstrument` on `PaymentInstrument`
+
+**Section**: Payment Methods
+
+**Description**: A single concrete instrument exposed by a gateway provider (BLIK code, branded bank, wallet, card brand). Pass `code` as `preferredInstrument` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway. `displayHint` is a semantic UX hint (`PROMINENT_BUTTON`, `BRANDED_TILE`, `DROPDOWN_OPTION`, `RADIO_OPTION`) — storefront branches rendering accordingly. `enabled: false` means the gateway reported the instrument as temporarily disabled — gray out, don't hide.
+
+**Uses fragments**: `ImageThumbnail`
+
+**GraphQL**:
+```graphql
+fragment PaymentInstrument on PaymentInstrument {
+  provider
+  code
+  type
+  displayName
+  displayHint
+  brandImage {
+    ...ImageThumbnail
+  }
+  enabled
+}
+```
+
 ### Fragment: `PaymentMethod` on `PaymentMethod`
 
 **Section**: Payment Methods
 
-**Description**: Single payment method enabled for the shop — type (CARD / BANK_TRANSFER / BLIK / PAYPAL / APPLE_PAY / GOOGLE_PAY / CASH_ON_DELIVERY / OTHER), provider, icon, supported currencies, default flag, sort position. Spread on the checkout payment step.
+**Description**: Single payment method enabled for the shop — method-centric. `type` is the category (CARD, BLIK, BANK_TRANSFER, INSTALLMENT, WALLET, CASH_ON_DELIVERY, OTHER) — drive iconography here. `provider`, `providersAvailable`, `preferredProvider` are `PaymentProvider` enum (UPPERCASE: `PAYU`, `PRZELEWY24`, ...). `available` is `false` when the resolving gateway is temporarily unavailable or reported the method as disabled — gray-out the tile, don't hide it; `unavailableReason` carries the diagnostic. `instruments` lists concrete gateway-side instruments (BLIK code, branded banks, wallets) when the gateway exposes granular data — pass `code` as `preferredInstrument` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway. Spread on the checkout payment step.
+
+**Uses fragments**: `ImageThumbnail`, `PaymentInstrument`
 
 **GraphQL**:
 ```graphql
@@ -3483,11 +3544,20 @@ fragment PaymentMethod on PaymentMethod {
   name
   provider
   type
-  icon
+  icon {
+    ...ImageThumbnail
+  }
   description
   isDefault
   supportedCurrencies
   position
+  providersAvailable
+  preferredProvider
+  available
+  unavailableReason
+  instruments {
+    ...PaymentInstrument
+  }
 }
 ```
 
@@ -3531,6 +3601,21 @@ fragment PaymentSession on PaymentSession {
 }
 ```
 
+### Fragment: `PaymentWarning` on `PaymentWarning`
+
+**Section**: Payment Methods
+
+**Description**: Non-blocking signal emitted alongside `userErrors[]` in `paymentCreate` payload — backend state change context (e.g. an auto-clear of preselected instrument after gateway rejection). Pre-translated by backend per shop locale. `code === 'INSTRUMENT_CLEARED_FOR_RETRY'` signals storefront that the next `paymentCreate` will land on the gateway default landing page (server-side cleared `Order.paymentInstrumentCode` after `INSTRUMENT_PRESELECTION_FAILED`). `retryHint` is optional context for UI dispatch — currently unused for `INSTRUMENT_CLEARED_FOR_RETRY`, reserved for future warning codes.
+
+**GraphQL**:
+```graphql
+fragment PaymentWarning on PaymentWarning {
+  message
+  code
+  retryHint
+}
+```
+
 ### Fragment: `ShipmentEvent` on `ShipmentEvent`
 
 **Section**: Shipments / Tracking
@@ -3569,7 +3654,9 @@ fragment ShipmentPackage on ShipmentPackage {
 
 **Section**: Shipments / Tracking
 
-**Description**: One item in a shipment — title, variant, sku, quantity, image URL. Spread inside `Shipment.items[]` for the tracking page item list.
+**Description**: One item in a shipment — title, variant, sku, quantity, live variant image (transformable). Spread inside `Shipment.items[]` for the tracking page item list. `image` is live from the current variant (snapshot fallback when variant has been deleted since fulfillment — returns null, render a placeholder).
+
+**Uses fragments**: `ImageThumbnail`
 
 **GraphQL**:
 ```graphql
@@ -3579,7 +3666,9 @@ fragment ShipmentItem on ShipmentItem {
   variantTitle
   sku
   quantity
-  imageUrl
+  image {
+    ...ImageThumbnail
+  }
 }
 ```
 
@@ -3683,7 +3772,7 @@ fragment ReturnItemPhoto on ReturnItemPhoto {
 
 **Description**: Single line in a return request — variant identity, quantity requested, reason, condition, photos, status, approved quantity (set by merchant after review). Spread inside `Return.items[]`.
 
-**Uses fragments**: `Money`, `ReturnItemPhoto`
+**Uses fragments**: `ImageThumbnail`, `Money`, `ReturnItemPhoto`
 
 **GraphQL**:
 ```graphql
@@ -3693,7 +3782,9 @@ fragment ReturnItem on ReturnItem {
   productTitle
   variantTitle
   sku
-  imageUrl
+  image {
+    ...ImageThumbnail
+  }
   quantity
   reason
   condition
@@ -3830,14 +3921,18 @@ fragment GiftCardValidation on GiftCardValidation {
 
 **Section**: Shipping Methods
 
-**Description**: Carrier offering the shipping method — id, display name, logo URL, internal service code.
+**Description**: Carrier offering the shipping method — id, display name, logo image (transformable), internal service code.
+
+**Uses fragments**: `ImageThumbnail`
 
 **GraphQL**:
 ```graphql
 fragment ShippingCarrier on ShippingCarrier {
   id
   name
-  logoUrl
+  logo {
+    ...ImageThumbnail
+  }
   serviceCode
 }
 ```
@@ -3919,13 +4014,17 @@ fragment AvailableShippingMethod on AvailableShippingMethod {
 
 **Section**: Attribute Filters
 
-**Description**: Visual swatch for an attribute filter value — color hex (for color filters) or image URL (for pattern/material swatches).
+**Description**: Visual swatch for an attribute filter value — color hex (for color filters) or image (for pattern/material swatches).
+
+**Uses fragments**: `ImageThumbnail`
 
 **GraphQL**:
 ```graphql
 fragment AttributeSwatch on AttributeSwatch {
   colorHex
-  imageUrl
+  image {
+    ...ImageThumbnail
+  }
 }
 ```
 
@@ -4082,7 +4181,7 @@ fragment LoyaltyPageInfo on LoyaltyPageInfo {
 
 **Description**: Loyalty tier definition — name, type enum (`BRONZE` / `SILVER` / `GOLD` / `PLATINUM` / `DIAMOND`), entry threshold (`minPoints` and/or `minAnnualSpend`), points multiplier, custom benefits list. Returned by `loyaltyTiers` and embedded in member tier data.
 
-**Uses fragments**: `Money`
+**Uses fragments**: `ImageThumbnail`, `Money`
 
 **GraphQL**:
 ```graphql
@@ -4098,7 +4197,9 @@ fragment LoyaltyTier on LoyaltyTier {
   customBenefits {
     name
     description
-    icon
+    icon {
+      ...ImageThumbnail
+    }
   }
 }
 ```
@@ -4349,6 +4450,8 @@ fragment GenerateReferralCodePayload on GenerateReferralCodePayload {
 
 **Description**: Single product review — rating, title, body, optional pros/cons, image attachments, author, verified-purchase flag, helpful/unhelpful counts, optional merchant response. Only `APPROVED` reviews are exposed to the storefront.
 
+**Uses fragments**: `ImageThumbnail`
+
 **GraphQL**:
 ```graphql
 fragment ProductReview on ProductReview {
@@ -4359,7 +4462,9 @@ fragment ProductReview on ProductReview {
   content
   pros
   cons
-  images
+  images {
+    ...ImageThumbnail
+  }
   authorName
   isVerifiedPurchase
   helpfulCount
@@ -4717,7 +4822,7 @@ fragment ShopPage on ShopPage {
 
 **Description**: One menu item with up to 3 levels of nested children — title, URL, type (`HTTP` / `FRONTPAGE` / `SEARCH` / `CATALOG` / `BLOG` / `PRODUCT` / `COLLECTION` / `CATEGORY` / `PAGE` / `BRAND`), `resourceId` for typed items, optional image, and a typed `resource` union (Category / Collection / ShopPage / Product / Brand) carrying the linked resource's handle. Two ways to render the link target: (1) use the pre-resolved `url` if your storefront follows the standard `/categories|/collections|/pages|/products|/brands/<handle>` route convention; (2) read `resource.__typename` + the per-type `handle` and build your own paths if your storefront uses different routing. Switch on `type` to decide which static (FRONTPAGE/SEARCH/CATALOG/BLOG) or dynamic target to render.
 
-**Uses fragments**: `Image`
+**Uses fragments**: `Image`, `ImageThumbnail`
 
 **GraphQL**:
 ```graphql
@@ -4753,7 +4858,9 @@ fragment MenuItem on MenuItem {
       id
       handle
       name
-      logo
+      logo {
+        ...ImageThumbnail
+      }
     }
   }
   image {
@@ -4791,7 +4898,9 @@ fragment MenuItem on MenuItem {
         id
         handle
         name
-        logo
+        logo {
+          ...ImageThumbnail
+        }
       }
     }
     items {
@@ -4826,7 +4935,9 @@ fragment MenuItem on MenuItem {
           id
           handle
           name
-          logo
+          logo {
+            ...ImageThumbnail
+          }
         }
       }
     }