@doswiftly/storefront-operations

The DoSwiftly Storefront API catalog — a versioned, AI-friendly reference bundle of the GraphQL schema, named operations, and reusable fragments for building storefronts on the DoSwiftly platform.

This package is a reference catalog and AI knowledge base, not a runtime dependency. Install it as a devDependency. Nothing from this package is imported into your runtime bundle — your AI assistant reads it for context, and (optionally) your codegen reads schema.graphql for type generation.

AI agents (Cursor, Codex, Claude Code, GitHub Copilot, Aider, Gemini CLI): open AGENTS.md — the entry point with the critical conventions you need before generating queries. The full operation reference with descriptions, typed variables, and executable bodies lives in llms-full.txt. For structured / programmatic access (MCP servers, custom tools): operations.json.

Installation

pnpm add -D @doswiftly/storefront-operations
# or
npm install --save-dev @doswiftly/storefront-operations

It ships only .graphql source files plus Markdown / JSON / text reference documents — there is no JavaScript to import, no runtime code, no transitive runtime deps. Hence devDependencies.

What's in the package

| File | What it's for | | ---- | ------------- | | AGENTS.md | AI agent entry point — critical conventions, anti-hallucination notes | | llms-full.txt | Full operation reference: descriptions + variables + bodies | | operations.json | Same operations as structured JSON (MCP / programmatic tools) | | queries.graphql | All named queries — read as a catalog, copy what you need | | mutations.graphql | All named mutations — same | | fragments.graphql | Reusable fragments referenced by queries + mutations | | schema.graphql | Full GraphQL schema — point your codegen at this for type generation |

How to use it

The intended use is: install once, consume forever as inspiration + schema source. You write your own operations into your own src/graphql/ directory — either by hand from the catalog, or with an AI assistant reading this package's context. The package's .graphql operation files are reference patterns, not bind-time dependencies that ship into your build.

Primary: AI-assisted (recommended)

This is the intended primary path. Install the package, open your repo in an AI coding tool, and ask it to build a storefront feature.

AI tools that respect the AGENTS.md convention — Cursor, OpenAI Codex, Claude Code, Aider, Gemini CLI — auto-discover node_modules/@doswiftly/storefront-operations/AGENTS.md from your repo and pull it into context. The assistant then knows:

• Every operation name, its typed variables, the canonical GraphQL body
• Anti-hallucination conventions (cart mutations are cartAddLines NOT cartLinesAdd, userErrors[].code is String not enum, etc.)
• When to use which fragment (ProductCard vs ProductBase vs ProductFull)
• Auth and pagination conventions

You then ask it to write operations into your src/graphql/. No codegen config is required for this use case (though you'll likely want codegen for type-safe consumption — see below).

For AI tools that do NOT auto-discover AGENTS.md from node_modules (GitHub Copilot Chat, some Cody configurations), explicitly reference it in your prompt:

Read @doswiftly/storefront-operations/AGENTS.md and llms-full.txt, then
write me a product page query in src/graphql/product.graphql.

Or add a one-line pointer to your own workspace AGENTS.md:

## DoSwiftly storefront API

Operations + critical conventions live in
`node_modules/@doswiftly/storefront-operations/AGENTS.md` and `llms-full.txt`.
Read those before writing GraphQL.

Manual: open the catalog and copy what you need

If you're not using an AI assistant (or want to handle this yourself), open the .graphql files in node_modules and treat them as starter examples. Find the operation you need, copy it into your src/graphql/ directory, adapt the field selection to your UI.

For type safety on the operations you write, point GraphQL codegen at the package's schema (not at its operation files):

// codegen.ts — schema from the package, documents from YOUR repo only
import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: 'node_modules/@doswiftly/storefront-operations/schema.graphql',
  documents: ['src/graphql/**/*.graphql'],
  generates: {
    'src/generated/graphql.ts': {
      plugins: ['typescript', 'typescript-operations', 'typed-document-node'],
    },
  },
};
export default config;

The schema lives offline as a file in the package — no running backend needed for codegen.

Advanced: codegen the entire catalog (not recommended for custom storefronts)

You can hook the package's operation files directly into your codegen as additional documents: to get TypedDocumentNodes for all upstream operations. This is mainly useful for scaffolded starter templates that want a complete sample storefront out of the box.

We don't recommend this for custom storefronts because:

• Every operation upstream ends up in your codegen output, even ones you don't use (bundle bloat — tree-shaking helps but doesn't fully eliminate)
• Your generated types become coupled to every selection change upstream (a tweak to a fragment in this package can ripple through your generated files even though your code doesn't use it)
• Loses the catalog framing — you stop treating these as patterns and start treating them as a hard dependency

If you do choose this path:

// codegen.ts — both schema AND documents come from the package (advanced)
const config: CodegenConfig = {
  schema: 'node_modules/@doswiftly/storefront-operations/schema.graphql',
  documents: [
    'node_modules/@doswiftly/storefront-operations/{queries,mutations,fragments}.graphql',
    'src/**/*.graphql',
  ],
  // ...
};

Available operations

Tables below are auto-generated from the .graphql files in this package and regenerated on every release — they cannot drift from the schema.

Use them to scan what's available. Click through to llms-full.txt for the full executable body of each operation.

Queries

Shop

| Operation | Description | | --- | --- | | Shop | Returns shop configuration: name, base + supported currencies, supported locales, branding (logo, colors, fonts, social links), contact info, active payment methods, brand metadata, money format template, and the list of countries the shop ships to. Public; no auth required. Call once per session and cache — almost everything else is contextualized by the shop returned here. | | ShopConfig | Minimal Shop payload for <StorefrontProvider shopData={...}> from @doswiftly/storefront-sdk/react. Returns exactly the fields the SDK's ShopConfig interface declares — currency setup (with localeToCurrencyMap for browser-locale-based currency detection), language setup, and bot protection. Cache for the session; refetch when the merchant updates currency / language settings or you want to pick up new bot-protection rules. |

Products

| Operation | Description | | --- | --- | | Product | Fetches a single product by id or handle (URL-friendly identifier). Pass either — whichever is provided wins; if both are missing, returns null. Returns null if the product is not storefront-accessible (must be ACTIVE status with PUBLIC or BUNDLE_ONLY visibility). | | ProductConfigurator | Fetches a product together with its filtered attribute definitions, optimized for the configurator UI (e.g. customer-facing text fields, finishing options, scoped variants). fillingMode: "CUSTOMER" returns only customer-facing attributes; pass "BOTH" to also include attributes shared with the merchant admin. Single round-trip — saves a separate attributes query. | | Products | Paginated product list (Relay Connection, default page size 20, max 100). The query argument supports a structured search syntax — tag:summer, vendor:foo, product_type:shirts, variants.price:>10, plus AND/OR/NOT — falling back to free-text title/content search. The filters[] array uses multi-filter logic: same field name appears multiple times → OR; different fields → AND. Sort: RELEVANCE, TITLE, PRICE, NEWEST, OLDEST, BEST_SELLING. The response includes a filters block for faceted navigation (counts per filterable attribute value). | | ProductSearch | Full-text product search — $query is required. Functionally equivalent to Products with $query set, minus the sortKey argument (search defaults to relevance ranking). Use for the search results page; combine with filters[] for guided refinement. | | SearchSuggestions | Type-ahead suggestions for the storefront search input. Returns up to $limit matching products (hard cap 50) plus up to 5 styled query suggestions with <mark> tags around matched spans. Polish-language aware (handles morphology in suggestions). Run on each keystroke (debounce 200-300ms). The $query is capped at 100 characters server-side. |

Collections

| Operation | Description | | --- | --- | | Collection | Fetches a single collection by id or handle, with paginated products. Collections come in two types: MANUAL (curated — products explicitly added by the merchant) and AUTO (rule-based — products matched dynamically). Both surfaces use the same field selection. | | Collections | Paginated list of all active collections (default 20, max 100). Sort by TITLE or UPDATED_AT via sortKey. Note: the query argument is reserved for future text filtering — it is currently accepted but ignored. |

Categories

| Operation | Description | | --- | --- | | Category | Fetches a single category by id or handle with its parent and immediate children. Use for breadcrumbs and sub-navigation. Nested queries on parent / children are batched server-side — safe to use in lists without N+1 concerns. | | Categories | Returns active root categories for the shop. Each root exposes its children — build the tree client-side by walking those fields (server batches the lookups, no N+1). The hierarchy is not depth-capped server-side. Use for nav mega-menus and category pages. |

Cart

| Operation | Description | | --- | --- | | Cart | Fetches a cart by id (the value persisted by the SDK in the cart-id cookie). The cart query is public — no auth needed to read it — but once a customer logs in and gets associated with the cart, mutations enforce ownership. Returns line items (paginated up to 100), totals, applied discount codes, gift cards, buyer identity, note, attributes, and warnings. Refetch after every cart mutation. |

Customer (requires auth)

| Operation | Description | | --- | --- | | Customer | Full customer profile — basic info plus the first 10 addresses and first 10 orders. Heaviest customer query; for narrow use cases prefer CustomerProfile (no orders / addresses) or CustomerOrder (single order). Returns null if unauthenticated. | | CustomerProfile | Lightweight customer profile (no orders, no addresses list). Use for settings / profile pages that only need basic customer info — much cheaper than Customer. Returns null if unauthenticated. | | CustomerAddresses | Authenticated customer's saved address book — used on checkout to let the buyer pick a previously-used shipping / billing address instead of typing it. Each entry carries B2B invoicing fields (taxId, vatNumber) and the isDefault flag so the same list serves both as the shipping picker and as the billing/invoice picker. Returns up to 50 addresses (Relay Connection — buyers rarely keep more); for the unauthenticated case the connection is empty (no error). The default address is also surfaced as Customer.defaultAddress. | | CustomerOrder | Single order by orderId. Returns only orders that belong to the authenticated customer (cross-customer access returns null, not an error). Much cheaper than fetching the full Customer payload to access one order. Use on the order detail page. | | OrderByToken | Fetch a single order using its opaque access token (Order.accessToken) — designed for guest order summary pages where the buyer has not signed in. The token is returned in cartComplete.order.accessToken immediately after checkout completes; persist it in an HTTP-only cookie (preferred) or sessionStorage for the post-checkout page (NEVER localStorage). Optional email parameter adds defense-in-depth: when provided, it is matched case-insensitively against the order's buyer email; on mismatch the query returns null exactly like an invalid token (the response shape is identical, so an attacker cannot distinguish "token valid, wrong email" from "token invalid"). Rate-limited to 5 requests per minute per IP+shop combination to deter token enumeration; clients exceeding the limit receive a GraphQL error with extensions.code: THROTTLED. The response is marked Cache-Control: no-store so per-customer order data is never served from CDN or browser cache between users. Safe to retry; the token is permanent until the order is deleted. |

Discount Code Validation

| Operation | Description | | --- | --- | | CartValidateDiscountCode | Read-only validation of a discount code against an existing cart — does NOT modify cart state. Returns { isValid, discount, error } (DiscountValidationResult) for previewing the effect of a code (inline UI feedback as the user types, before they commit to applying via cartDiscountCodesUpdate). Validates: discount existence + active status + customer eligibility + minimum order amount + minimum quantity met. Errors: NOT_FOUND, INACTIVE, NOT_STARTED, EXPIRED, USAGE_LIMIT_REACHED, CUSTOMER_USAGE_LIMIT_REACHED, CUSTOMER_NOT_ELIGIBLE, MINIMUM_ORDER_NOT_MET, MINIMUM_QUANTITY_NOT_MET. |

Payment Methods

| Operation | Description | | --- | --- | | AvailablePaymentMethods | Returns the active payment methods for the shop, sorted by the merchant-configured display position. Shop-level — does NOT vary by cart amount or currency. Each method exposes type (CARD, BANK_TRANSFER, BLIK, PAYPAL, APPLE_PAY, GOOGLE_PAY, CASH_ON_DELIVERY, OTHER), provider, icon, description, and supported currencies. Use to render the payment step of checkout. |

Shipments / Tracking

| Operation | Description | | --- | --- | | Shipment | Fetches a shipment by id with status, tracking events, recipient address, and shipped/delivered timestamps. Auth required — customer access token plus ownership of the parent order. Wrapped response: { shipment, userErrors[] }. Error codes: INVALID_TOKEN, NOT_FOUND (also returned on ownership mismatch to prevent enumeration), FETCH_FAILED. | | ShipmentByTrackingNumber | Public shipment lookup by carrier tracking number — no auth required. Designed for "Track my order" landing pages reachable without login. Returns the basic shipment fragment including recipient address. Wrapped response: { shipment, userErrors[] }. Error codes: INVALID_INPUT, NOT_FOUND, FETCH_FAILED. |

Returns / RMA

| Operation | Description | | --- | --- | | Return | Fetches a single return (RMA) by id with line items, refund/compensation info, and history. Auth required — customer access token plus ownership of the return. Wrapped response: { return, userErrors[] }. Error codes: INVALID_TOKEN, NOT_FOUND (also returned on ownership mismatch), FETCH_FAILED. | | ReturnsByOrder | Lists returns for a given order (paginated, default page size 20, cursor-based). Auth required — customer access token plus ownership of the order; the connection is empty (no explicit error) on auth failure. Use on the order detail page to show return history. | | ReturnReasons | Returns the standard list of return reasons used by the RMA flow: DEFECTIVE, NOT_AS_DESCRIBED, WRONG_ITEM, CHANGED_MIND, BETTER_PRICE, DAMAGED_SHIPPING, OTHER. The list is fixed across all shops — not per-shop configurable. Public; no auth required. |

Gift Cards

| Operation | Description | | --- | --- | | GiftCard | Public gift-card lookup by code. Returns balance, currency, expiry, and maskedCode (first 4 + last 4 chars only — the full code never leaks back). Returns null if the code is unknown (rather than an explicit error, to limit enumeration). Rate-limited: 10 requests per 60 seconds per IP. | | GiftCardValidate | Validates whether a gift card is usable (and optionally for a given $amount). Checks status (DISABLED, USED, EXPIRED), expiry date, and — when $amount is provided — sufficient balance. Returns { validation: { isValid, availableBalance, error: { code, message } }, userErrors[] }. Validation error codes: NOT_FOUND, DISABLED, ALREADY_USED, EXPIRED, INSUFFICIENT_BALANCE. Rate-limited: 10 / 60s. |

Shipping Methods

| Operation | Description | | --- | --- | | AvailableShippingMethods | Returns shipping methods for a given destination address and cart shape (subtotal, total weight, currency). The query computes everything from the inputs alone — no existing cart is required, so it can be used for "shipping cost preview" UIs (e.g. product detail page shipping calculator) before the customer adds anything to a cart. Each method includes price, free-shipping progress ({ qualifies, currentAmount, threshold, remaining, progressPercent }), estimated delivery, and carrier metadata. Sorted by the merchant's sortOrder, then by price. For a cart-bound checkout flow (where the cart is already known and the storefront wants the resolver to skip non-physical items and surface a DIGITAL_ONLY_NO_SHIPPING user error for all-digital carts), use CartAvailableShippingMethods against cart.availableShippingMethods(address) instead. | | CartAvailableShippingMethods | Cart-aware shipping methods discovery. Returns shipping methods available for the cart's contents at the given destination, with subtotal and physical-item weight pulled from the cart aggregate (no need to compute them client-side). When the cart contains only non-physical items (digital, gift card, service, subscription), the response is methods: [] plus a DIGITAL_ONLY_NO_SHIPPING user error — use this as the signal to skip rendering the shipping picker step. Prefer this query over the standalone AvailableShippingMethods once a cart has been created (cartCreate). For pre-cart "shipping cost preview" UIs on product detail pages, the standalone query remains the right tool. |

Attribute Filters

| Operation | Description | | --- | --- | | ProductFilters | Returns the dynamic facet filters available for a listing context — pass collectionId, categoryId, searchQuery, optional available (boolean for the availability facet), and optional currentFilters (array of attribute filters currently applied by the UI). For each visible & filterable attribute, returns either discrete value counts (for SELECT / CHECKBOX types) or numeric range bounds (for SLIDER types). Plus priceRange, brands, per-category counts, activeCount (length of currentFilters), totalCount (products in context — Relay-aligned), and availableCount (boolean facet count for availableForSale). All per-facet counts use exclude-self aggregation: a facet's count IGNORES its own currently-applied filter and APPLIES other filters — so the count reflects "products if this facet were toggled" rather than "products currently visible". Untracked inventory (gift cards, digital, made-to-order) is always counted as available. Use to render filter sidebars on listing/search pages. |

Loyalty Program

| Operation | Description | | --- | --- | | LoyaltyMember | Returns the logged-in customer's loyalty membership: points (current, pending, redeemed, expired, expiring), current tier, tier progress, annual spend, last activity. Returns null if the customer is not enrolled — there is no auto-enrollment here (enrollment happens via signup or a first qualifying order). Auth required. | | LoyaltyTiers | Lists the loyalty tiers configured for the shop (BRONZE, SILVER, GOLD, PLATINUM, DIAMOND etc.) with their minPoints, minAnnualSpend, pointsMultiplier, and custom benefits. Sorted by minPoints ASC. Public; no auth required. | | LoyaltyRewards | Lists rewards customers can redeem (free shipping, percent off, free product, gift card). Filtered to active rewards only (is_active = true AND inside their starts_at/ends_at window). Public; no auth required. | | LoyaltyTransactions | Paginated history of loyalty point transactions for the logged-in customer (default 20). Transaction type enum: EARN_PURCHASE, EARN_SIGNUP, EARN_REFERRAL, EARN_REVIEW, EARN_BIRTHDAY, EARN_BONUS, REDEEM, EXPIRE, ADJUST, REFUND_REVERSAL. Auth required — empty connection if unauthenticated. | | LoyaltySettings | Returns the loyalty program configuration: isEnabled, pointsName (e.g. "stars"), pointsPerCurrency, pointsExpiryMonths, available earn actions, referral settings. Use this at app boot to decide whether to render any loyalty UI at all. Public; no auth required. | | EstimatePoints | Estimates how many loyalty points the customer would earn for an order of $orderTotal (in major currency units). When the customer is authenticated, the result accounts for their current tier's points multiplier. Use on cart/checkout to show "Earn X points with this order". | | ReferralStats | Returns the customer's referral statistics: referralCode, shareUrl, totalReferred, completedReferrals, pendingReferrals, totalPointsEarned. Auth required. Returns null if unauthenticated or if the referral program is disabled for the shop. |

Reviews

| Operation | Description | | --- | --- | | ProductReviews | Paginated list of customer reviews for a product, filtered to APPROVED reviews only (PENDING / REJECTED reviews are not exposed to the storefront). Sort by CREATED_AT (default), helpfulness, or rating. Public; no auth required. | | ReviewStats | Aggregate review statistics for a product: average rating, total count, distribution per star (1-5). Computed from APPROVED reviews only. Use for product card review summaries. Public; no auth required. |

Wishlists

| Operation | Description | | --- | --- | | Wishlists | Paginated list of the logged-in customer's wishlists (default 20). Auth required — empty connection if unauthenticated. Customers typically have a small set (<10). | | WishlistById | Fetches a single wishlist by id. Private wishlists are visible only to the owner; public wishlists are visible to anyone. Note: this query supports lookup by id only — there is currently no way to fetch a wishlist by its share token. |

Blog

| Operation | Description | | --- | --- | | BlogPosts | Paginated list of published blog posts. Filter by categoryHandle, tagHandle, or featured (boolean flag, not enum). Sort: PUBLISHED_AT (default), TITLE, VIEW_COUNT, or CREATED_AT. Public; no auth required. | | BlogPost | Fetches a single blog post by id or handle. Visibility-gated: returns null if the post is not yet PUBLISHED or if its publish date is in the future (scheduled posts stay hidden until their publish time). Side effect: fetching a post increments its view_count asynchronously (does not block the response). | | BlogCategories | Lists all blog categories with per-category postCount and SEO metadata. Use to render category navigation on blog pages. Public; no auth required. | | BlogTags | Lists blog tags with usage counts (postCount per tag). Use to render a tag cloud. Public; no auth required. |

Recommendations

| Operation | Description | | --- | --- | | ProductRecommendations | Returns up to $limit recommended products related to $productId. Default $intent: SIMILAR — products sharing categories or tags. Use on PDP "You may also like" sections. Public; no auth required. |

Content: Pages

| Operation | Description | | --- | --- | | Page | Fetches a single CMS page (About, Privacy, Returns Policy, Terms, etc.) by handle or id. Visibility-gated: returns null if the page is hidden or if its publish date is in the future. Public; no auth required. | | Pages | Paginated list of visible, already-published CMS pages. Use for sitemap, footer link list, or page directory. The query argument supports text search over the page title/handle. Public; no auth required. |

Content: Navigation Menus

| Operation | Description | | --- | --- | | Menu | Fetches a navigation menu by handle (e.g. "main-menu", "footer", "mobile"). Returns the nested item tree (up to 3 levels). Each item is typed as one of: HTTP, FRONTPAGE, SEARCH, CATALOG, BLOG, PRODUCT, COLLECTION, CATEGORY, PAGE, or BRAND — switch on the type to render the right link target. Each resource-linked item exposes both a pre-resolved url (standard /categories\|/collections\|/pages\|/products\|/brands/<handle> convention) and a typed resource union with the raw handle so storefronts with custom routing can construct their own paths instead. All resource lookups are batched per request — no N+1 even for deep menus. |

Content: URL Redirects

| Operation | Description | | --- | --- | | UrlRedirects | Returns the shop's URL redirects (legacy path → new target mappings). Use server-side at the edge or in SSR to issue 301 redirects for migrated routes (preserves SEO equity). Default page size 250 — most shops fit in a single page. |

Store Availability: per-location stock (BOPIS / multi-location)

| Operation | Description | | --- | --- | | ProductStoreAvailability | Fetches a product (by handle or id) along with per-variant availability across the merchant's physical locations — for the BOPIS / multi-location flow. The storeAvailability connection lives on each ProductVariant; its arguments (first, after, near, locationType) are set inside the VariantStoreAvailability fragment. The connection returns null for single-location shops (in which case the storefront can skip the store picker entirely). availableStock is null for anonymous users and an integer for authenticated customers. Apply @inContext(preferredLocationId: ...) on the operation to pin the customer's preferred location to the top of the result. |

Locations (store picker UI)

| Operation | Description | | --- | --- | | Locations | Paginated list of active store locations (default 20, max 100). Filters: near ({ latitude, longitude }) for proximity search — sorts ascending by distance; hasPickupEnabled for pickup-only filtering; locationType (RETAIL, WAREHOUSE, PICKUP_POINT). When near is omitted, results are sorted by the merchant's priority, then name. Use for the BOPIS store picker UI. Public; no auth required. | | Location | Fetches a single store location by id — full address, coordinates, business hours, pickup config (lead time, hours, timezone), and services. Returns null if the location is not found, not active, or owned by another shop. Use on the location detail page. Public; no auth required. |

Mutations

Cart Mutations

| Operation | Description | | --- | --- | | CartCreate | Creates a new cart and optionally pre-populates it with line items. Returns a one-time secret (the cart access capability) alongside the cart — the SDK persists it in the cart-id cookie and sends it as the x-cart-secret header on later cart operations; a direct API caller must store it immediately, as it cannot be retrieved again. The cart ID is a UUID; the cart 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. | | CartAddLines | 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. | | CartUpdateLines | 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. | | CartRemoveLines | 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. | | CartDiscountCodesUpdate | Replaces (NOT appends) the cart's discount codes with the given list. Pass [] to clear all codes. Each code is validated against the 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. Single canonical replace-all entry point — prior append/single-remove variants were removed in favor of this explicit caller-controlled list semantics. | | CartUpdateBuyerIdentity | Set the buyer's email and phone on the cart (guest checkout contact details). The cart is bound to a customer automatically from the authenticated session — there is no customerId input, so a guest cannot claim another shopper's account. Sign in and the cart attaches to that customer (re-binding overwrites, last-write-wins); the customerId is then readable on cart.buyerIdentity. Use during guest checkout to capture contact info and after login to attach the buyer. Does not trigger tax / shipping recalculation. | | CartMerge | Merge a guest cart into the signed-in customer's existing cart right after login. Pass the guest cart id; its secret travels in the cart credential header and the customer is taken from the authenticated session (never the client). Line quantities are summed per variant, the buyer's in-session checkout fields win, and the prior customer cart is discarded. The returned cart keeps the SAME id and secret as the guest cart, so the stored cart-id stays valid — no cookie re-issue. Requires authentication (returns CART_MERGE_REQUIRES_AUTH otherwise) and refuses carts held in different currencies (CART_CURRENCY_MISMATCH). | | CartDowngradeOnLogout | Downgrade a cart to guest on logout. Pass the cart id (its secret travels in the cart credential header). Clears the customer association, contact details, addresses and payment selection, but keeps line items, discount codes, the selected shipping method, currency and notes. The cart id and secret are unchanged (no rotation), so the stored cart-id stays valid and the buyer keeps their items as a guest. Call from the logout flow before tearing down the auth session so the next person on a shared device sees none of the previous buyer's data. Gated by the cart secret only (no auth) — a missing/wrong secret returns CART_NOT_FOUND. | | CartRecoveryRedeem | Redeem a signed cart recovery link (from an abandoned-cart email). Pass the token taken from the link's query parameter. On success the cart is recovered (made active again) and its access secret is ROTATED — the NEW secret is returned once in secret (persist it immediately; the previous secret stops working), and the SDK sets the cart-id cookie to the recovered cart. Buyer self-service: the merchant only sends the link, never takes over the cart. A bad link returns CART_RECOVERY_LINK_EXPIRED or CART_RECOVERY_LINK_INVALID without exposing any cart content; CART_NOT_FOUND if the cart no longer exists. | | CartUpdateNote | 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. |

Customer Auth Mutations

| Operation | Description | | --- | --- | | CustomerSignup | 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. | | CustomerLogin | 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). | | CustomerLogout | 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. | | CustomerRefreshToken | 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. |

Customer Profile Mutations

| Operation | Description | | --- | --- | | CustomerUpdate | 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. |

Customer Address Mutations

| Operation | Description | | --- | --- | | CustomerAddAddress | 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. | | CustomerUpdateAddress | 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. | | CustomerRemoveAddress | 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). | | CustomerSetDefaultAddress | 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. |

Customer Password Mutations

| Operation | Description | | --- | --- | | CustomerRequestPasswordReset | 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. | | CustomerActivate | 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. | | CustomerResetPassword | 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. |

Cart Completion Mutations

| Operation | Description | | --- | --- | | 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 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. | | 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, 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

| Operation | Description | | --- | --- | | ReturnCreate | 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. | | ReturnCancel | 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. |

Loyalty Program Mutations

| Operation | Description | | --- | --- | | RedeemLoyaltyReward | 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. | | GenerateReferralCode | 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. |

Review Mutations

| Operation | Description | | --- | --- | | ReviewCreate | 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). | | ReviewUpvote | 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). | | ReviewDownvote | 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. |

Wishlist Mutations

| Operation | Description | | --- | --- | | WishlistCreate | 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. | | WishlistAddItem | 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. | | WishlistRemoveItem | Hard-deletes a wishlist item by itemId (the WishlistItem row id, NOT the product id). | | WishlistDelete | Hard-deletes the wishlist row. All wishlist items are removed via cascade. No soft-delete; cannot be undone. |

Cart Attributes

| Operation | Description | | --- | --- | | CartUpdateAttributes | 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. |

Fragments

Common

| Fragment | On Type | Description | | --- | --- | --- | | PageInfo | PageInfo | Standard Relay Connection page metadata. Spread on every paginated query's pageInfo. | | UserError | UserError | Generic mutation error envelope — included in every mutation's userErrors[] field. Always check before consuming the happy-path payload. | | CartWarning | CartWarning | Non-blocking cart warning (e.g. low stock, partial availability). Cart mutations succeed but surface these for UI hints. | | Image | Image | Base image — original size, no transform. Use for logos, favicons, branding assets that are already sized correctly. ~few KB. | | ImageThumbnail | Image | Thumbnail — cart line items, variant swatches, author avatars (rendered ~96px on screen, transform delivers up to 300px for 3x DPI). Includes thumbhash for blurred placeholder. Format auto-negotiated from the Accept header. | | ImageCard | Image | Card — product cards, collection / category tiles, blog post previews (rendered ~400px, transform delivers up to 800px for 2x DPI). Includes thumbhash placeholder. | | ImageFull | Image | Full — product detail gallery, hero banners (rendered ~800px, transform delivers up to 1600px for 2x DPI). Includes thumbhash placeholder. | | Money | Money | Plain { amount, currencyCode } price. Use for compareAtPrice, totals, and any field where currency conversion transparency is not needed. amount is a String. | | SelectedOption | SelectedOption | Selected variant option (e.g. { name: "Color", value: "Red" }) on a ProductVariant. Use to render variant labels in cart / order summaries. |

Products

| Fragment | On Type | Description | | --- | --- | --- | | ProductVariant | ProductVariant | Single variant of a product — price, compare-at, stock flags, sort, image, selected options. Spread on cart line items, PDP variant selectors, search result rows that need price. | | ProductCard | Product | Minimal product shape for listing views (collection grids, search results, "you may also like"). Includes price range, featured image (card size), rating + review count, vendor, tags. Use for any list of products where you don't need variants/description. | | ProductBase | Product | ProductCard plus textual content (description, descriptionHtml), stock total, type, visibility flags, and timestamps. Use when you need full product copy but not the heavy variants/images lists. Sweet spot for blog post embeds, related-product cards with description. | | ProductFull | Product | Full product shape for the PDP — ProductBase plus the full image gallery (up to 20, full-size) and all variants (up to 100) with their pricing/stock. Spread on the product detail page. |

Collections

| Fragment | On Type | Description | | --- | --- | --- | | Collection | Collection | Collection (manual or rule-based product grouping) — title, description, hero image, SEO. Spread on collection landing pages and collection cards. Does NOT include products — query collection(id, handle).products separately for those. |

Categories

| Fragment | On Type | Description | | --- | --- | --- | | Category | Category | Category node in the shop's taxonomy — name, handle, hero image, depth level, materialized path, product count, sort order. Spread on category cards and breadcrumb segments. Does NOT include parent / children — query those fields separately and let the server batch them. |

Customer

| Fragment | On Type | Description | | --- | --- | --- | | PickupPoint | PickupPoint | Selected pickup point (parcel locker or collection point) attached to a delivery address. Returned on MailingAddress.pickupPoint when the buyer chose a non-home delivery method (deliveryType other than HOME). Null for home delivery. | | MailingAddress | MailingAddress | Customer mailing address — full street/city/state/country/postal code with names and phone. isDefault flips when this address is the default for shipping. Carries B2B invoicing fields (taxId, vatNumber, regon) and the selected pickupPoint for parcel locker / collection point deliveries. Spread on the address book UI, checkout shipping/billing forms, and order summaries. | | CustomerAccessToken | CustomerAccessToken | Customer access token returned by customerLogin / customerSignup / customerActivate / customerResetPassword / customerRefreshToken. The token's JWT TTL is 24h; cookie max-age is 30d. | | Customer | Customer | Customer profile — basic info plus B2B fields (taxId, vatNumber, regon, companyName), default address, lifetime stats (orderCount, totalSpent), marketing preferences. Use on profile / settings pages. | | Order | Order | Order summary — number, totals (cost / tax / shipping), payment + fulfillment status, shipping address, item count, lifecycle timestamps, plus payment capability signal (canCreatePayment + paymentMethodType) the storefront uses to decide post-completion payment flow without hard-coded provider checks. Spread on the order list, order detail, and the cartComplete mutation result. Line items are not included here. |

Cart

| Fragment | On Type | Description | | --- | --- | --- | | CartCost | CartCost | Cart-level totals — subtotal, total, tax, duty, discount, shipping, checkout charge. Spread inside the Cart fragment. | | CartLineCost | CartLineCost | Per-line cost breakdown — unit price, line subtotal/total, compare-at unit price (for showing strikethroughs). Spread inside CartLine. | | AttributeSelection | AttributeSelection | Typed snapshot of a customer-filled product attribute (configurator selection) on a cart line. Includes the chosen option / text value, fillingMode, billingMode, surcharge, tax class, and any linked variant. Distinct from CartLine.attributes which holds raw key-value line item properties (free-form, untyped). | | CartLine | CartLine | A single line in the cart — variant + quantity + per-line cost, plus dual attribute storage: attributes[] for free-form key-value properties (gift wrap, engraving notes), attributeSelections[] for typed configurator answers. | | CartBuyerIdentity | CartBuyerIdentity | Buyer identity associated with the cart. Note: only customerId is currently persisted server-side; email, phone, countryCode are accepted in the input but ignored. | | CartDiscountCode | CartDiscountCode | Discount code applied to the cart with its isApplicable flag — false means the code was kept on the cart but does not currently qualify (e.g. minimum spend not reached). | | CartDiscountAllocation | CartDiscountAllocation | Allocation of a discount code to the cart total — pairs the code with the actual money discounted. Use to show "saved X with code Y" in cart UI. | | 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 image (transformable), description, isDefault, supportedCurrencies. Storefront UI używa do iconography + selection display. |

Shop

| Fragment | On Type | Description | | --- | --- | --- | | ShopColors | ShopColors | Shop branding colors — primary, secondary, accent, background, text. Use to theme the storefront from server-side config. | | ShopFonts | ShopFonts | Shop branding fonts — body (primary) and heading font families. | | SocialLinks | SocialLinks | Social media links configured for the shop. Spread on the footer. | | ShopAddress | ShopAddress | Shop's physical / business address. Use on the contact page and footer. | | BusinessHour | BusinessHour | One day's business hours window. Spread inside Shop.businessHours[]. | | ShopBranding | ShopBranding | Full shop branding bundle — logo + favicon + colors + fonts + social links. Spread inside the Shop fragment. | | BotProtectionProvider | BotProtectionProviderInfo | Bot-protection provider config (provider name, site key, script URL) for storefront-side challenge widgets. | | BotProtection | BotProtectionInfo | Bot-protection setup for the shop — primary + fallback provider, and the list of protectedOperations (mutation names that require a challenge token). Spread inside Shop. | | Shop | Shop | The shop itself — name, primary domain, currencies + locales, branding, contact info, business hours, bot-protection config. Spread on the root shop query; cache for the session. | | ShopConfigFields | Shop | Minimal Shop fields consumed by <StorefrontProvider shopData={...}> from @doswiftly/storefront-sdk/react. Spread this in your shop query to get a response shape that matches the SDK ShopConfig interface 1:1 — no manual field selection, no drift when the SDK adds optional fields. Use the larger Shop fragment when you also need branding / contact / business hours for your UI. |

Payment Methods

| Fragment | On Type | Description | | --- | --- | --- | | 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

| Fragment | On Type | Description | | --- | --- | --- | | 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, 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. |

Returns / RMA

| Fragment | On Type | Description | | --- | --- | --- | | ReturnShippingLabel | ReturnShippingLabel | Return shipping label generated by the carrier — URL to download, carrier name, tracking number, expiry. Spread on the return detail page. | | ReturnItemPhoto | ReturnItemPhoto | Photo evidence attached to a return item (e.g. damage photo). Spread inside ReturnItem.photos[]. | | ReturnItem | ReturnItem | 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[]. | | Return | Return | Full return shape — number, parent order, status, reason, customer note, compensation type (REFUND / STORE_CREDIT), items, refund amount, shipping label, lifecycle timestamps. Spread on the return detail page. | | ReturnReasonOption | ReturnReasonOption | Single option in the return reasons dropdown — value enum, human-readable label, optional description. Returned by returnReasons query. |

Gift Cards

| Fragment | On Type | Description | | --- | --- | --- | | GiftCard | GiftCard | Gift card detail — masked code (first + last 4 chars), status, initial + remaining balance, expiry, recipient/message. Returned by giftCard($code) query. | | GiftCardError | GiftCardError | Validation error on a gift card check — code (NOT_FOUND / DISABLED / ALREADY_USED / EXPIRED / INSUFFICIENT_BALANCE) + human message. | | GiftCardValidation | GiftCardValidation | Result of giftCardValidate($code, $amount) — isValid flag, available balance, optional error (when invalid), and the matched gift card (when found). Use to inline-validate gift card inputs before applying. |

Shipping Methods

| Fragment | On Type | Description | | --- | --- | --- | | 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. For pickup methods, pickupConfig carries the public data needed to render the carrier point picker — selectionMode = WIDGET gives a widgetToken (e.g. the InPost Geowidget public token, never a carrier API secret) + scriptUrl to load the map; selectionMode = SEARCH means query points server-side. pickupConfig is null for HOME methods and when the merchant has not configured the carrier's public widget token (do not render a map then). Spread on the checkout shipping step. |

Attribute Filters

| Fragment | On Type | Description | | --- | --- | --- | | 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[]. | | PriceRangeFilter | PriceRange | Min / max price range across products in the current listing context. Use to bound the price slider. | | CategoryFilterOption | CategoryFilterOption | One category option in the categories filter — id, name, handle, count of products in this category within the current listing context, level + parentId for tree rendering. | | AvailableFilters | AvailableFilters | Full result of the productFilters($input) query — attribute filters, price range, category filters, brands, count of currently active filters, total products in context (Relay-aligned totalCount), and boolean facet count for availableForSale (availableCount). Spread on listing pages to render filter sidebars. Per-facet counts (attributes[].filterValues[].productCount, brands[].productCount, categories[].productCount, availableCount) use exclude-self aggregation: when a dimension is in input.currentFilters / input.available, its own facet count IGNORES that filter (shows "how many products would appear if this facet were toggled"), while OTHER dimensions APPLY their filters. This matches industry convention for accurate facet UX. |

Loyalty Program

| Fragment | On Type | Description | | --- | --- | --- | | LoyaltyPageInfo | LoyaltyPageInfo | Page metadata for the loyalty transactions connection (separate type from generic PageInfo for legacy reasons; identical shape). | | LoyaltyTier | LoyaltyTier | 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. | | LoyaltyPointsSummary | LoyaltyPointsSummary | Customer's points breakdown — total earned, currently spendable, pending (not yet vested), redeemed lifetime, expired lifetime, expiring soon, and the next expiry date. Spread inside LoyaltyMember. | | TierProgress | TierProgress | Custo