@doswiftly/storefront-operations 16.0.0 → 17.0.0

package/llms-full.txt

@@ -1,7 +1,7 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **16.0.0**
-> 52 queries · 40 mutations · 102 fragments
+> Schema version: **17.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 `preferredProviderId` 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
+    }
   }
 }
 ```
@@ -3052,6 +3083,11 @@ fragment CartLine on CartLine {
   productHandle
   productType
   requiresShipping
+  giftCardRecipient {
+    recipientEmail
+    recipientName
+    message
+  }
 }
 ```
 
@@ -3166,6 +3202,7 @@ fragment Cart on Cart {
   selectedPaymentMethod {
     ...CartSelectedPaymentMethod
   }
+  selectedPaymentInstrumentCode
   appliedGiftCards {
     ...CartAppliedGiftCard
   }
@@ -3465,11 +3502,32 @@ fragment ShopConfigFields on Shop {
 }
 ```
 
+### Fragment: `PaymentMethodInstrument` on `PaymentMethodInstrument`
+
+**Section**: Payment Methods
+
+**Description**: A single concrete instrument exposed by a gateway provider (BLIK code, branded bank, wallet, card brand). Pass `instrumentCode` as `preferredInstrumentCode` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway. `displayHint` is a semantic UX hint (`PIN_ENTRY`, `WALLET_TAP`, `BANK_LIST`, `CARD_FORM`) — storefront branches rendering accordingly. `enabled: false` means the gateway reported the instrument as temporarily disabled — gray out, don't hide.
+
+**GraphQL**:
+```graphql
+fragment PaymentMethodInstrument on PaymentMethodInstrument {
+  providerCode
+  instrumentCode
+  type
+  displayName
+  displayHint
+  brandImageUrl
+  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, CASH_ON_DELIVERY, OTHER) — drive iconography here. `provider`, `providersAvailable`, `preferredProvider` are `ProviderCode` 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 `instrumentCode` as `preferredInstrumentCode` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway. Spread on the checkout payment step.
+
+**Uses fragments**: `PaymentMethodInstrument`
 
 **GraphQL**:
 ```graphql
@@ -3483,6 +3541,13 @@ fragment PaymentMethod on PaymentMethod {
   isDefault
   supportedCurrencies
   position
+  providersAvailable
+  preferredProvider
+  available
+  unavailableReason
+  instruments {
+    ...PaymentMethodInstrument
+  }
 }
 ```
 
@@ -3526,6 +3591,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

package/mutations.graphql

@@ -329,7 +329,11 @@ mutation CartSelectShippingMethod($input: CartSelectShippingMethodInput!) {
   }
 }
 
-# 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`.
+# Selects a payment method on the cart by category (`methodType` — BLIK, CARD, BANK_TRANSFER, ...).
+# Optional `preferredProviderId` 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`.
 mutation CartSelectPaymentMethod($input: CartSelectPaymentMethodInput!) {
   cartSelectPaymentMethod(input: $input) {
     cart {
@@ -404,7 +408,7 @@ mutation CartComplete($input: CartCompleteInput!) {
   }
 }
 
-# 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`.
+# 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).
 mutation PaymentCreate($input: PaymentCreateInput!) {
   paymentCreate(input: $input) {
     payment {
@@ -413,6 +417,24 @@ mutation PaymentCreate($input: PaymentCreateInput!) {
     userErrors {
       ...UserError
     }
+    warnings {
+      ...PaymentWarning
+    }
+  }
+}
+
+# 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.
+mutation CartClearPaymentSelection($input: CartClearPaymentSelectionInput!) {
+  cartClearPaymentSelection(input: $input) {
+    cart {
+      ...Cart
+    }
+    userErrors {
+      ...UserError
+    }
+    warnings {
+      ...CartWarning
+    }
   }
 }
 

package/operations.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "16.0.0",
+  "schemaVersion": "17.0.0",
   "queries": [
     {
       "name": "Shop",
@@ -1518,7 +1518,7 @@
       "name": "CartSelectPaymentMethod",
       "kind": "mutation",
       "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 `preferredProviderId` 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": [
         {
           "name": "input",
@@ -1613,7 +1613,7 @@
       "name": "PaymentCreate",
       "kind": "mutation",
       "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": [
         {
           "name": "input",
@@ -1623,9 +1623,29 @@
       ],
       "fragmentRefs": [
         "PaymentSession",
+        "PaymentWarning",
         "UserError"
       ],
-      "body": "mutation PaymentCreate($input: PaymentCreateInput!) {\n  paymentCreate(input: $input) {\n    payment {\n      ...PaymentSession\n    }\n    userErrors {\n      ...UserError\n    }\n  }\n}"
+      "body": "mutation PaymentCreate($input: PaymentCreateInput!) {\n  paymentCreate(input: $input) {\n    payment {\n      ...PaymentSession\n    }\n    userErrors {\n      ...UserError\n    }\n    warnings {\n      ...PaymentWarning\n    }\n  }\n}"
+    },
+    {
+      "name": "CartClearPaymentSelection",
+      "kind": "mutation",
+      "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": [
+        {
+          "name": "input",
+          "type": "CartClearPaymentSelectionInput!",
+          "defaultValue": null
+        }
+      ],
+      "fragmentRefs": [
+        "Cart",
+        "CartWarning",
+        "UserError"
+      ],
+      "body": "mutation CartClearPaymentSelection($input: CartClearPaymentSelectionInput!) {\n  cartClearPaymentSelection(input: $input) {\n    cart {\n      ...Cart\n    }\n    userErrors {\n      ...UserError\n    }\n    warnings {\n      ...CartWarning\n    }\n  }\n}"
     },
     {
       "name": "ReturnCreate",
@@ -2124,7 +2144,7 @@
         "CartLineCost",
         "ProductVariant"
       ],
-      "body": "fragment CartLine on CartLine {\n  id\n  quantity\n  variant {\n    ...ProductVariant\n  }\n  cost {\n    ...CartLineCost\n  }\n  attributes {\n    key\n    value\n  }\n  attributeSelections {\n    ...AttributeSelection\n  }\n  productId\n  productTitle\n  productHandle\n  productType\n  requiresShipping\n}",
+      "body": "fragment CartLine on CartLine {\n  id\n  quantity\n  variant {\n    ...ProductVariant\n  }\n  cost {\n    ...CartLineCost\n  }\n  attributes {\n    key\n    value\n  }\n  attributeSelections {\n    ...AttributeSelection\n  }\n  productId\n  productTitle\n  productHandle\n  productType\n  requiresShipping\n  giftCardRecipient {\n    recipientEmail\n    recipientName\n    message\n  }\n}",
       "onType": "CartLine"
     },
     {
@@ -2177,7 +2197,7 @@
         "MailingAddress",
         "PageInfo"
       ],
-      "body": "fragment Cart on Cart {\n  id\n  checkoutUrl\n  totalQuantity\n  cost {\n    ...CartCost\n  }\n  lines(first: 100) {\n    edges {\n      cursor\n      node {\n        ... on CartLine {\n          ...CartLine\n        }\n      }\n    }\n    nodes {\n      ... on CartLine {\n        ...CartLine\n      }\n    }\n    pageInfo {\n      ...PageInfo\n    }\n    totalCount\n  }\n  buyerIdentity {\n    ...CartBuyerIdentity\n  }\n  discountCodes {\n    ...CartDiscountCode\n  }\n  discountAllocations {\n    ...CartDiscountAllocation\n  }\n  note\n  attributes {\n    key\n    value\n  }\n  email\n  phone\n  shippingAddress {\n    ...MailingAddress\n  }\n  billingAddress {\n    ...MailingAddress\n  }\n  selectedShippingMethod {\n    ...CartShippingMethod\n  }\n  selectedPaymentMethod {\n    ...CartSelectedPaymentMethod\n  }\n  appliedGiftCards {\n    ...CartAppliedGiftCard\n  }\n  requiresShipping\n  createdAt\n  updatedAt\n  status\n  completedOrder {\n    id\n    orderNumber\n    accessToken\n    status\n    paymentStatus\n    fulfillmentStatus\n  }\n}",
+      "body": "fragment Cart on Cart {\n  id\n  checkoutUrl\n  totalQuantity\n  cost {\n    ...CartCost\n  }\n  lines(first: 100) {\n    edges {\n      cursor\n      node {\n        ... on CartLine {\n          ...CartLine\n        }\n      }\n    }\n    nodes {\n      ... on CartLine {\n        ...CartLine\n      }\n    }\n    pageInfo {\n      ...PageInfo\n    }\n    totalCount\n  }\n  buyerIdentity {\n    ...CartBuyerIdentity\n  }\n  discountCodes {\n    ...CartDiscountCode\n  }\n  discountAllocations {\n    ...CartDiscountAllocation\n  }\n  note\n  attributes {\n    key\n    value\n  }\n  email\n  phone\n  shippingAddress {\n    ...MailingAddress\n  }\n  billingAddress {\n    ...MailingAddress\n  }\n  selectedShippingMethod {\n    ...CartShippingMethod\n  }\n  selectedPaymentMethod {\n    ...CartSelectedPaymentMethod\n  }\n  selectedPaymentInstrumentCode\n  appliedGiftCards {\n    ...CartAppliedGiftCard\n  }\n  requiresShipping\n  createdAt\n  updatedAt\n  status\n  completedOrder {\n    id\n    orderNumber\n    accessToken\n    status\n    paymentStatus\n    fulfillmentStatus\n  }\n}",
       "onType": "Cart"
     },
     {
@@ -2330,13 +2350,25 @@
       "onType": "Shop"
     },
     {
-      "name": "PaymentMethod",
+      "name": "PaymentMethodInstrument",
       "kind": "fragment",
       "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": "A single concrete instrument exposed by a gateway provider (BLIK code, branded bank, wallet, card brand). Pass `instrumentCode` as `preferredInstrumentCode` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway. `displayHint` is a semantic UX hint (`PIN_ENTRY`, `WALLET_TAP`, `BANK_LIST`, `CARD_FORM`) — storefront branches rendering accordingly. `enabled: false` means the gateway reported the instrument as temporarily disabled — gray out, don't hide.",
       "variables": [],
       "fragmentRefs": [],
-      "body": "fragment PaymentMethod on PaymentMethod {\n  id\n  name\n  provider\n  type\n  icon\n  description\n  isDefault\n  supportedCurrencies\n  position\n}",
+      "body": "fragment PaymentMethodInstrument on PaymentMethodInstrument {\n  providerCode\n  instrumentCode\n  type\n  displayName\n  displayHint\n  brandImageUrl\n  enabled\n}",
+      "onType": "PaymentMethodInstrument"
+    },
+    {
+      "name": "PaymentMethod",
+      "kind": "fragment",
+      "section": "Payment Methods",
+      "description": "Single payment method enabled for the shop — method-centric. `type` is the category (CARD, BLIK, BANK_TRANSFER, CASH_ON_DELIVERY, OTHER) — drive iconography here. `provider`, `providersAvailable`, `preferredProvider` are `ProviderCode` 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 `instrumentCode` as `preferredInstrumentCode` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway. Spread on the checkout payment step.",
+      "variables": [],
+      "fragmentRefs": [
+        "PaymentMethodInstrument"
+      ],
+      "body": "fragment PaymentMethod on PaymentMethod {\n  id\n  name\n  provider\n  type\n  icon\n  description\n  isDefault\n  supportedCurrencies\n  position\n  providersAvailable\n  preferredProvider\n  available\n  unavailableReason\n  instruments {\n    ...PaymentMethodInstrument\n  }\n}",
       "onType": "PaymentMethod"
     },
     {
@@ -2361,6 +2393,16 @@
       "body": "fragment PaymentSession on PaymentSession {\n  id\n  orderId\n  flow\n  provider\n  redirectUrl\n  clientSecret\n  status\n  expiresAt\n}",
       "onType": "PaymentSession"
     },
+    {
+      "name": "PaymentWarning",
+      "kind": "fragment",
+      "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.",
+      "variables": [],
+      "fragmentRefs": [],
+      "body": "fragment PaymentWarning on PaymentWarning {\n  message\n  code\n  retryHint\n}",
+      "onType": "PaymentWarning"
+    },
     {
       "name": "ShipmentEvent",
       "kind": "fragment",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-operations",
-  "version": "16.0.0",
+  "version": "17.0.0",
   "description": "GraphQL operations for DoSwiftly Storefront - SSOT from backend",
   "homepage": "https://doswiftly.pl",
   "publishConfig": {