@doswiftly/storefront-operations 7.0.0 → 8.0.0

package/mutations.graphql

@@ -7,6 +7,7 @@
 # Cart Mutations
 # ============================================
 
+# Creates a new cart and optionally pre-populates it with line items. Cart ID is a UUID stored by the SDK in the `cart-id` cookie (30-day TTL); the cart itself expires server-side after 72 hours of inactivity. The `warnings` field is reserved for non-blocking issues — current implementation returns it empty in this path.
 mutation CartCreate($input: CartCreateInput) {
   cartCreate(input: $input) {
     cart {
@@ -21,6 +22,7 @@ mutation CartCreate($input: CartCreateInput) {
   }
 }
 
+# Adds line items to a cart. Each line is `{ merchandiseId, quantity, attributes?, attributeSelections? }`. If the same variant + identical attributes are added twice, quantities merge into one row instead of duplicating. Validates stock (`INSUFFICIENT_STOCK`) and configurator attributes (`ATTRIBUTE_REQUIRED`, `ATTRIBUTE_OPTION_INVALID`). Triggers cart re-pricing including discount recalculation.
 mutation CartAddLines($id: ID!, $lines: [CartLineInput!]!) {
   cartAddLines(id: $id, lines: $lines) {
     cart {
@@ -35,6 +37,7 @@ mutation CartAddLines($id: ID!, $lines: [CartLineInput!]!) {
   }
 }
 
+# Updates quantity and/or attributes of existing cart lines by `id`. Setting `quantity: 0` auto-deletes the line. Passing `attributes: []` clears them; omitting the field preserves existing values. Re-validates stock and re-prices the cart after each update.
 mutation CartUpdateLines($id: ID!, $lines: [CartLineUpdateInput!]!) {
   cartUpdateLines(id: $id, lines: $lines) {
     cart {
@@ -49,6 +52,7 @@ mutation CartUpdateLines($id: ID!, $lines: [CartLineUpdateInput!]!) {
   }
 }
 
+# Removes specific lines from cart by `lineIds[]`. Internally delegates to `cartUpdateLines` with `quantity: 0` — both endpoints are functionally equivalent; this one exists for API ergonomics when intent is explicit removal. Triggers cart re-pricing.
 mutation CartRemoveLines($id: ID!, $lineIds: [ID!]!) {
   cartRemoveLines(id: $id, lineIds: $lineIds) {
     cart {
@@ -63,6 +67,7 @@ mutation CartRemoveLines($id: ID!, $lineIds: [ID!]!) {
   }
 }
 
+# Replaces (NOT appends) the cart's discount codes with the given list. Pass `[]` to clear all codes. Each code is validated against `discounts` table (existence, active status); invalid codes appear in `userErrors[]` as `DISCOUNT_CODE_INVALID`. Triggers cart re-pricing — discount allocations are recomputed and stored in `cart.discountAmount`.
 mutation CartApplyDiscountCodes($id: ID!, $discountCodes: [String!]!) {
   cartApplyDiscountCodes(id: $id, discountCodes: $discountCodes) {
     cart {
@@ -77,6 +82,7 @@ mutation CartApplyDiscountCodes($id: ID!, $discountCodes: [String!]!) {
   }
 }
 
+# Associates a customer with the cart. Despite the input shape accepting `email`, `phone`, `countryCode`, `languageCode`, only `customerId` is currently persisted — other fields are silently ignored. Does NOT trigger tax / shipping recalculation; pure cart-to-customer linking. Use during login or guest-to-account upgrade.
 mutation CartUpdateBuyerIdentity($id: ID!, $buyerIdentity: CartBuyerIdentityInput!) {
   cartUpdateBuyerIdentity(id: $id, buyerIdentity: $buyerIdentity) {
     cart {
@@ -91,6 +97,7 @@ mutation CartUpdateBuyerIdentity($id: ID!, $buyerIdentity: CartBuyerIdentityInpu
   }
 }
 
+# Sets a free-text note on the cart (gift message, special instructions). Pass empty string to clear. Stored on the `Cart` row, propagated to the `Order` at checkout completion, visible to merchant in admin.
 mutation CartUpdateNote($id: ID!, $note: String!) {
   cartUpdateNote(id: $id, note: $note) {
     cart {
@@ -109,6 +116,7 @@ mutation CartUpdateNote($id: ID!, $note: String!) {
 # Customer Auth Mutations
 # ============================================
 
+# Registers a new customer. Returns `customerAccessToken` immediately — the customer record is created with status `ACTIVE` (no pending state). The activation email containing `customerActivate` token is sent for `emailVerified=true` confirmation, but is NOT required for login. Cookie: `customerAccessToken`, 30-day max-age, httpOnly. JWT TTL: 24h. Bot-protection guarded.
 mutation CustomerSignup($input: CustomerCreateInput!) {
   customerSignup(input: $input) {
     customer {
@@ -123,6 +131,7 @@ mutation CustomerSignup($input: CustomerCreateInput!) {
   }
 }
 
+# Logs in with email + password. JWT lifetime 24h; cookie max-age 30d (cookie outlives JWT — call `customerRefreshToken` before JWT expiry to extend session). Brute-force protected: 10 failed attempts per email = 15-min Redis-backed lockout. Failed attempts are recorded for non-existent emails too (timing-attack safe).
 mutation CustomerLogin($input: CustomerAccessTokenCreateInput!) {
   customerLogin(input: $input) {
     customerAccessToken {
@@ -134,6 +143,7 @@ mutation CustomerLogin($input: CustomerAccessTokenCreateInput!) {
   }
 }
 
+# Clears the `customerAccessToken` cookie. Note: the JWT itself is NOT server-side invalidated — it remains valid until its 24h expiry. Server-side token revocation is on the roadmap. Idempotent.
 mutation CustomerLogout {
   customerLogout {
     deletedAccessToken
@@ -144,6 +154,7 @@ mutation CustomerLogout {
   }
 }
 
+# Issues a fresh JWT (24h TTL) for the currently-authenticated customer. Reads identity from the current cookie/Bearer token; takes no input. Use proactively before JWT expiry or reactively on a 401 retry. The new token replaces the cookie value.
 mutation CustomerRefreshToken {
   customerRefreshToken {
     customerAccessToken {
@@ -159,6 +170,7 @@ mutation CustomerRefreshToken {
 # Customer Profile Mutations
 # ============================================
 
+# Updates the logged-in customer's profile. Supported fields include `firstName`, `lastName`, `phone`, marketing preferences, and B2B identity (`customerType`, `companyName`, `taxId`, `vatNumber`, `regon`). Concurrent updates from the storefront and the merchant admin are reconciled safely — the loser of a race retries against the latest version. Marketing consent changes are recorded separately for audit purposes.
 mutation CustomerUpdate($customer: CustomerUpdateInput!) {
   customerUpdate(customer: $customer) {
     customer {
@@ -174,6 +186,7 @@ mutation CustomerUpdate($customer: CustomerUpdateInput!) {
 # Customer Address Mutations
 # ============================================
 
+# Adds a new mailing address. If `isDefaultShipping` or `isDefaultBilling` is `true` in the input, the new address is set as default and any other address for this customer holding that flag is atomically cleared in the same transaction.
 mutation CustomerAddAddress($address: MailingAddressInput!) {
   customerAddAddress(address: $address) {
     address {
@@ -185,6 +198,7 @@ mutation CustomerAddAddress($address: MailingAddressInput!) {
   }
 }
 
+# Updates an existing address owned by the logged-in customer. If `isDefaultShipping` or `isDefaultBilling` toggles to `true`, default flag is atomically cleared on all other addresses for this customer.
 mutation CustomerUpdateAddress($id: ID!, $address: MailingAddressInput!) {
   customerUpdateAddress(id: $id, address: $address) {
     address {
@@ -196,6 +210,7 @@ mutation CustomerUpdateAddress($id: ID!, $address: MailingAddressInput!) {
   }
 }
 
+# Hard-deletes an address row from `customer_addresses`. Historical orders that referenced this address are unaffected (address is snapshotted into the order at checkout completion).
 mutation CustomerRemoveAddress($id: ID!) {
   customerRemoveAddress(id: $id) {
     deletedAddressId
@@ -205,6 +220,7 @@ mutation CustomerRemoveAddress($id: ID!) {
   }
 }
 
+# Marks the given address as the customer's default **shipping** address. Atomically clears the shipping-default flag from all other addresses. Note: there is no separate setter for default billing — set `isDefaultBilling: true` via `customerAddAddress` / `customerUpdateAddress` instead.
 mutation CustomerSetDefaultAddress($addressId: ID!) {
   customerSetDefaultAddress(addressId: $addressId) {
     customer {
@@ -220,6 +236,7 @@ mutation CustomerSetDefaultAddress($addressId: ID!) {
 # Customer Password Mutations
 # ============================================
 
+# Sends a password reset email. Always returns success regardless of whether the email exists (no account enumeration). The email is dispatched asynchronously, so a small delay between request and inbox arrival is normal. Rate-limited to 3 requests per 10 minutes.
 mutation CustomerRequestPasswordReset($email: String!) {
   customerRequestPasswordReset(email: $email) {
     userErrors {
@@ -228,6 +245,7 @@ mutation CustomerRequestPasswordReset($email: String!) {
   }
 }
 
+# Activates a newly-created account using the 64-hex activation token from the welcome email + a chosen password. Token TTL is 24h, single-use (atomically marked `used_at`). On success: sets `email_verified=true`, transitions status `INACTIVE`→`ACTIVE`, returns a fresh JWT for auto-login. Rate-limited.
 mutation CustomerActivate($token: String!, $password: String!) {
   customerActivate(token: $token, password: $password) {
     customer {
@@ -242,6 +260,7 @@ mutation CustomerActivate($token: String!, $password: String!) {
   }
 }
 
+# Resets the password using the 64-hex reset token from the password-reset email. Token TTL is 1h, single-use (atomically marked `used_at`). On success: updates the password hash and returns a fresh JWT for auto-login (no second login step needed). Rate-limited.
 mutation CustomerResetPassword($token: String!, $newPassword: String!) {
   customerResetPassword(token: $token, newPassword: $newPassword) {
     customer {
@@ -260,6 +279,7 @@ mutation CustomerResetPassword($token: String!, $newPassword: String!) {
 # Checkout Mutations
 # ============================================
 
+# Creates a new checkout session for the given cart (or a fresh cart if `cartId` is omitted). Inherits applied discounts and gift cards from the cart by reference (not snapshot). Errors: `CART_NOT_FOUND`, `EMPTY_CART`, `ALREADY_COMPLETED` (cart already converted to order). NOT idempotent — multiple calls create multiple checkouts.
 mutation CheckoutCreate($input: CheckoutCreateInput!) {
   checkoutCreate(input: $input) {
     checkout {
@@ -271,8 +291,9 @@ mutation CheckoutCreate($input: CheckoutCreateInput!) {
   }
 }
 
-mutation CheckoutShippingAddressUpdate($checkoutId: ID!, $shippingAddress: CheckoutAddressInput!) {
-  checkoutShippingAddressUpdate(checkoutId: $checkoutId, shippingAddress: $shippingAddress) {
+# Sets the shipping address (full replace, not patch). Triggers cart re-pricing. Address format is NOT validated here — full validation runs at `checkoutComplete`.
+mutation CheckoutUpdateShippingAddress($id: ID!, $shippingAddress: CheckoutAddressInput!) {
+  checkoutUpdateShippingAddress(id: $id, shippingAddress: $shippingAddress) {
     checkout {
       ...Checkout
     }
@@ -282,8 +303,9 @@ mutation CheckoutShippingAddressUpdate($checkoutId: ID!, $shippingAddress: Check
   }
 }
 
-mutation CheckoutBillingAddressUpdate($checkoutId: ID!, $billingAddress: CheckoutAddressInput!) {
-  checkoutBillingAddressUpdate(checkoutId: $checkoutId, billingAddress: $billingAddress) {
+# Sets the billing address (full replace). Independent of shipping address — pass it explicitly even when "billing same as shipping".
+mutation CheckoutUpdateBillingAddress($id: ID!, $billingAddress: CheckoutAddressInput!) {
+  checkoutUpdateBillingAddress(id: $id, billingAddress: $billingAddress) {
     checkout {
       ...Checkout
     }
@@ -293,8 +315,9 @@ mutation CheckoutBillingAddressUpdate($checkoutId: ID!, $billingAddress: Checkou
   }
 }
 
-mutation CheckoutEmailUpdate($checkoutId: ID!, $email: String!) {
-  checkoutEmailUpdate(checkoutId: $checkoutId, email: $email) {
+# Sets or updates the contact email on the checkout (used for guest checkout, order confirmation, and tracking emails). Validated against a regex; returns `INVALID` for malformed format.
+mutation CheckoutUpdateEmail($id: ID!, $email: String!) {
+  checkoutUpdateEmail(id: $id, email: $email) {
     checkout {
       ...Checkout
     }
@@ -304,8 +327,9 @@ mutation CheckoutEmailUpdate($checkoutId: ID!, $email: String!) {
   }
 }
 
-mutation CheckoutShippingLineUpdate($checkoutId: ID!, $shippingRateHandle: String!) {
-  checkoutShippingLineUpdate(checkoutId: $checkoutId, shippingRateHandle: $shippingRateHandle) {
+# Selects a shipping method by `rateId` (a stable shipping-method UUID, NOT an opaque per-request token). The id comes from `availableShippingMethods` query, computed for the current address + cart subtotal at request time.
+mutation CheckoutSelectShippingRate($id: ID!, $rateId: String!) {
+  checkoutSelectShippingRate(id: $id, rateId: $rateId) {
     checkout {
       ...Checkout
     }
@@ -315,8 +339,9 @@ mutation CheckoutShippingLineUpdate($checkoutId: ID!, $shippingRateHandle: Strin
   }
 }
 
-mutation CheckoutDiscountCodeApply($checkoutId: ID!, $discountCode: String!) {
-  checkoutDiscountCodeApply(checkoutId: $checkoutId, discountCode: $discountCode) {
+# Appends a discount code to the cart's `discount_codes` array. Note: while multiple codes can be stored, the pricing engine currently uses **only the first applied code** — codes do not stack. Validated for existence, active status, and customer usage limits.
+mutation CheckoutApplyDiscountCode($id: ID!, $discountCode: String!) {
+  checkoutApplyDiscountCode(id: $id, discountCode: $discountCode) {
     checkout {
       ...Checkout
     }
@@ -326,8 +351,9 @@ mutation CheckoutDiscountCodeApply($checkoutId: ID!, $discountCode: String!) {
   }
 }
 
-mutation CheckoutDiscountCodeRemove($checkoutId: ID!, $discountCode: String!) {
-  checkoutDiscountCodeRemove(checkoutId: $checkoutId, discountCode: $discountCode) {
+# Removes a code from the cart's `discount_codes` array (filters by exact match). Triggers re-pricing.
+mutation CheckoutRemoveDiscountCode($id: ID!, $discountCode: String!) {
+  checkoutRemoveDiscountCode(id: $id, discountCode: $discountCode) {
     checkout {
       ...Checkout
     }
@@ -337,8 +363,9 @@ mutation CheckoutDiscountCodeRemove($checkoutId: ID!, $discountCode: String!) {
   }
 }
 
-mutation CheckoutDiscountCodeValidate($checkoutId: ID!, $discountCode: String!) {
-  checkoutDiscountCodeValidate(checkoutId: $checkoutId, discountCode: $discountCode) {
+# READ-ONLY validation of a discount code against the current checkout — does NOT modify state. Returns `{ isValid, discount, error }` for previewing the effect (e.g. inline UI feedback as the user types).
+mutation CheckoutValidateDiscountCode($id: ID!, $discountCode: String!) {
+  checkoutValidateDiscountCode(id: $id, discountCode: $discountCode) {
     result {
       isValid
       discount {
@@ -362,8 +389,9 @@ mutation CheckoutDiscountCodeValidate($checkoutId: ID!, $discountCode: String!)
   }
 }
 
-mutation CheckoutPaymentMethodUpdate($checkoutId: ID!, $paymentMethodId: ID!) {
-  checkoutPaymentMethodUpdate(checkoutId: $checkoutId, paymentMethodId: $paymentMethodId) {
+# Selects a payment method by `paymentMethodId` (UUID from `availablePaymentMethods` query). Validates existence and active status; no pre-authorization is performed here.
+mutation CheckoutSelectPaymentMethod($id: ID!, $paymentMethodId: ID!) {
+  checkoutSelectPaymentMethod(id: $id, paymentMethodId: $paymentMethodId) {
     checkout {
       ...Checkout
     }
@@ -373,8 +401,9 @@ mutation CheckoutPaymentMethodUpdate($checkoutId: ID!, $paymentMethodId: ID!) {
   }
 }
 
-mutation CheckoutComplete($checkoutId: ID!, $input: CheckoutCompleteInput) {
-  checkoutComplete(checkoutId: $checkoutId, input: $input) {
+# Finalizes the checkout: creates the `Order`, deducts gift cards, sends order-created confirmation — all atomically. **Idempotent on `idempotencyKey`** (NOT on the checkout `id`); auto-generated if the caller omits it. The `paymentUrl` field is reserved but is NOT populated here — for hosted gateways (PayU, P24) the storefront calls a separate `paymentCreate` mutation after this returns.
+mutation CheckoutComplete($id: ID!, $input: CheckoutCompleteInput) {
+  checkoutComplete(id: $id, input: $input) {
     checkout {
       ...Checkout
     }
@@ -389,11 +418,12 @@ mutation CheckoutComplete($checkoutId: ID!, $input: CheckoutCompleteInput) {
 }
 
 # ============================================
-# Gift Card Checkout Mutations (GAP-001)
+# Gift Card Checkout Mutations
 # ============================================
 
-mutation CheckoutGiftCardApply($checkoutId: ID!, $giftCardCode: String!) {
-  checkoutGiftCardApply(checkoutId: $checkoutId, giftCardCode: $giftCardCode) {
+# 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 `checkoutComplete`. Errors: `GIFT_CARD_NOT_FOUND`, `GIFT_CARD_DEPLETED`, `GIFT_CARD_UNUSABLE`, `GIFT_CARD_ALREADY_APPLIED`.
+mutation CheckoutApplyGiftCard($id: ID!, $giftCardCode: String!) {
+  checkoutApplyGiftCard(id: $id, giftCardCode: $giftCardCode) {
     checkout {
       ...Checkout
     }
@@ -403,8 +433,9 @@ mutation CheckoutGiftCardApply($checkoutId: ID!, $giftCardCode: String!) {
   }
 }
 
-mutation CheckoutGiftCardRemove($checkoutId: ID!, $giftCardCode: String!) {
-  checkoutGiftCardRemove(checkoutId: $checkoutId, giftCardCode: $giftCardCode) {
+# Removes a gift card from the applied list and recalculates FIFO `appliedAmount` for the remaining cards. Since gift card balances are only debited at `checkoutComplete`, removing before completion has no effect on the underlying gift card balance.
+mutation CheckoutRemoveGiftCard($id: ID!, $giftCardCode: String!) {
+  checkoutRemoveGiftCard(id: $id, giftCardCode: $giftCardCode) {
     checkout {
       ...Checkout
     }
@@ -414,8 +445,9 @@ mutation CheckoutGiftCardRemove($checkoutId: ID!, $giftCardCode: String!) {
   }
 }
 
-mutation CheckoutGiftCardRecipientUpdate($input: CheckoutGiftCardRecipientInput!) {
-  checkoutGiftCardRecipientUpdate(input: $input) {
+# Sets per-line-item recipient details (name, email, message, delivery date) for digital gift card products in the cart (variants with `type: GIFT_CARD`). Required before `checkoutComplete` for any line item with a gift-card variant. Recipient details are associated with each gift-card line item and propagated to the resulting order.
+mutation CheckoutUpdateGiftCardRecipient($input: CheckoutGiftCardRecipientInput!) {
+  checkoutUpdateGiftCardRecipient(input: $input) {
     checkout {
       ...Checkout
     }
@@ -426,9 +458,10 @@ mutation CheckoutGiftCardRecipientUpdate($input: CheckoutGiftCardRecipientInput!
 }
 
 # ============================================
-# Return Mutations (R30 - Returns/RMA)
+# Return Mutations
 # ============================================
 
+# Creates an RMA in `REQUESTED` status (awaits merchant approval — NOT auto-approved). Input: `orderId`, `reason`, `items[{ variantId, quantity, reason, condition }]`, optional `compensationType` (REFUND or STORE_CREDIT) and `customerNote`. Validates the order's `fulfillmentStatus` permits returns and that requested quantities don't exceed already-shipped/unreturned quantities. Supports optional `idempotencyKey` for retry-safe creation.
 mutation ReturnCreate($input: ReturnCreateInput!) {
   returnCreate(input: $input) {
     return {
@@ -440,6 +473,7 @@ mutation ReturnCreate($input: ReturnCreateInput!) {
   }
 }
 
+# Cancels a return that is currently in `REQUESTED`, `APPROVED`, or `DRAFT` status (cancellation is allowed even AFTER merchant approval, as long as the return shipment hasn't been processed). Sets `cancelled_at` timestamp. Customer can only cancel returns they own.
 mutation ReturnCancel($id: ID!) {
   returnCancel(id: $id) {
     return {
@@ -452,17 +486,19 @@ mutation ReturnCancel($id: ID!) {
 }
 
 # ============================================
-# Loyalty Program Mutations (R8, R10.4)
+# Loyalty Program Mutations
 # ============================================
 
+# Redeems a loyalty reward by `rewardId`. Three reward types are supported, distinguished by which output field is populated: `discountCode` (issues a `LOYALTY-XXXX` code with 30-day expiry), `productDiscountCode` (issues a single-use 100%-off code for a specific product), or `giftCardCode` (creates a new gift card for the customer). Points are deducted atomically inside a transaction — if external creation (e.g. gift card service) fails after deduction, points are reversed.
 mutation RedeemLoyaltyReward($input: RedeemRewardInput!) {
-  redeemLoyaltyReward(input: $input) {
+  loyaltyRedeemReward(input: $input) {
     ...RedeemRewardPayload
   }
 }
 
+# Returns the customer's referral code, generating one on first call. Idempotent UPSERT — subsequent calls return the existing code from `customers.referral_code`. Format: `REF-XXXXXXXX` (8 random alphanumeric chars). Output also includes a `shareUrl` built from the shop's domain.
 mutation GenerateReferralCode {
-  generateReferralCode {
+  loyaltyGenerateReferralCode {
     ...GenerateReferralCodePayload
   }
 }
@@ -471,6 +507,7 @@ mutation GenerateReferralCode {
 # Review Mutations
 # ============================================
 
+# Submits a product review (rating 1-5, content 10-5000 chars, sanitized via `sanitizePlainText`). Default state is `PENDING` — review is hidden from public until merchant approves. If the input includes `orderId`, `isVerifiedPurchase` is auto-set to `true`. Bot-protected and rate-limited (10/min by default).
 mutation ReviewCreate($input: ReviewCreateInput!) {
   reviewCreate(input: $input) {
     review {
@@ -482,6 +519,7 @@ mutation ReviewCreate($input: ReviewCreateInput!) {
   }
 }
 
+# Records an upvote (helpful) on a review. UPSERT semantics — one `ReviewVote` row per `(reviewId, customerId)`. Calling upvote twice is a no-op; calling downvote afterwards replaces the vote. Increments `helpful_count` on the review (and decrements `unhelpful_count` if replacing a downvote).
 mutation ReviewUpvote($reviewId: ID!) {
   reviewUpvote(reviewId: $reviewId) {
     review {
@@ -493,6 +531,7 @@ mutation ReviewUpvote($reviewId: ID!) {
   }
 }
 
+# Records a downvote (unhelpful) on a review. Same UPSERT semantics as `reviewUpvote` — one vote row per `(reviewId, customerId)`, replacing any prior vote. Increments `unhelpful_count`.
 mutation ReviewDownvote($reviewId: ID!) {
   reviewDownvote(reviewId: $reviewId) {
     review {
@@ -508,39 +547,51 @@ mutation ReviewDownvote($reviewId: ID!) {
 # Wishlist Mutations
 # ============================================
 
+# Creates a new wishlist for the logged-in customer. `name` is optional (defaults to "My Wishlist"); name uniqueness is NOT enforced — customers can have multiple lists with the same name. Setting `isPublic: true` generates a 16-byte hex `shareToken` for public sharing.
 mutation WishlistCreate($input: WishlistCreateInput!) {
   wishlistCreate(input: $input) {
     wishlist {
       ...Wishlist
     }
-    userErrors
+    userErrors {
+      ...UserError
+    }
   }
 }
 
-mutation WishlistAddItem($wishlistId: ID!, $input: WishlistItemInput!) {
-  wishlistAddItem(wishlistId: $wishlistId, input: $input) {
+# Adds an item by `productId` (and optional `variantId`) to a wishlist. Idempotent on the `(wishlist_id, product_id, variant_id)` unique constraint — adding an already-present item is a silent no-op. Captures `priceAtAdd` for price-drop notifications.
+mutation WishlistAddItem($id: ID!, $input: WishlistItemInput!) {
+  wishlistAddItem(id: $id, input: $input) {
     wishlist {
       ...Wishlist
     }
-    userErrors
+    userErrors {
+      ...UserError
+    }
   }
 }
 
-mutation WishlistRemoveItem($wishlistId: ID!, $itemId: ID!) {
-  wishlistRemoveItem(wishlistId: $wishlistId, itemId: $itemId) {
+# Hard-deletes a wishlist item by `itemId` (the `WishlistItem` row id, NOT the product id).
+mutation WishlistRemoveItem($id: ID!, $itemId: ID!) {
+  wishlistRemoveItem(id: $id, itemId: $itemId) {
     wishlist {
       ...Wishlist
     }
-    userErrors
+    userErrors {
+      ...UserError
+    }
   }
 }
 
-mutation WishlistDelete($wishlistId: ID!) {
-  wishlistDelete(wishlistId: $wishlistId) {
+# Hard-deletes the wishlist row. All wishlist items are removed via cascade. No soft-delete; cannot be undone.
+mutation WishlistDelete($id: ID!) {
+  wishlistDelete(id: $id) {
     wishlist {
       ...Wishlist
     }
-    userErrors
+    userErrors {
+      ...UserError
+    }
   }
 }
 
@@ -548,6 +599,7 @@ mutation WishlistDelete($wishlistId: ID!) {
 # Cart Attributes
 # ============================================
 
+# Replaces (NOT merges) the cart's custom attributes — free-form `[{ key, value }]` pairs visible to merchant in admin. Use for delivery instructions, gift wrap flags, B2B PO numbers, etc. Limit: 250 pairs per cart (returns `CART_ATTRIBUTES_LIMIT_EXCEEDED`); each `key` max 255 chars.
 mutation CartUpdateAttributes($id: ID!, $attributes: [CartAttributeInput!]!) {
   cartUpdateAttributes(id: $id, attributes: $attributes) {
     cart {