@vtex/faststore 0.0.1

package/dist/schema.graphql

@@ -0,0 +1,2953 @@
+# GENERATED by src/schema/emit.ts (pnpm run schema:emit) — do not edit by hand.
+# core version: 0.0.1
+schema {
+  query: Query
+  mutation: Mutation
+}
+
+"""
+Declares an HTTP cache policy for a type, field, or interface. Apollo Server
+aggregates every hint resolved by a query and emits a single `Cache-Control`
+header whose `max-age` is the minimum across hints and whose scope is the most
+restrictive (PRIVATE wins over PUBLIC). Mutations and error responses ignore
+these hints and always carry `Cache-Control: no-store`.
+"""
+directive @cacheControl(
+  """Longest time (in seconds) this data may live in a cache."""
+  maxAge: Int
+  """
+  Whether shared caches (CDN, proxy) may store the response. Defaults to
+  PUBLIC when another field or type sets a scope and nothing overrides it.
+  """
+  scope: CacheControlScope
+  """
+  When true, this field inherits its `maxAge` from the parent field rather
+  than contributing its own hint. Useful for wrapper/connection types.
+  """
+  inheritMaxAge: Boolean
+) on OBJECT | FIELD_DEFINITION | INTERFACE
+
+"""Visibility scope for an HTTP cache entry."""
+enum CacheControlScope {
+  """
+  The response may be stored by shared caches (CDN, proxy) and reused
+  across users.
+  """
+  PUBLIC
+  """
+  The response may only be stored by single-user caches (browser, service
+  worker). Shared caches must not store it.
+  """
+  PRIVATE
+}
+
+"""
+An [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) encoded UTC datetime.
+"""
+scalar DateTime
+
+"""
+An [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) encoded URI.
+"""
+scalar URI
+
+"""A string containing raw HTML markup."""
+scalar HTML
+
+"""
+An ISO 4217 currency amount represented as a decimal string (e.g. "29.99").
+"""
+scalar Decimal
+
+"""
+A [BCP 47](https://tools.ietf.org/html/bcp47) language tag (e.g. "en-US").
+"""
+scalar Locale
+
+"""An opaque cursor used for Relay-style pagination."""
+scalar Cursor
+
+"""
+The Relay `Node` interface. Every entity in the graph implements this so
+the client can refetch any object with a single `node(id: ID!)` query.
+"""
+interface Node {
+  """Globally unique identifier. Base64 of `entityType:rawId`."""
+  id: ID!
+}
+
+"""Metadata about the current page in a Relay connection."""
+type PageInfo {
+  """Whether more pages exist after the current page."""
+  hasNextPage: Boolean!
+  """Whether more pages exist before the current page."""
+  hasPreviousPage: Boolean!
+  """Cursor of the first edge in the current page."""
+  startCursor: Cursor
+  """Cursor of the last edge in the current page."""
+  endCursor: Cursor
+}
+
+"""Sort direction for orderBy arguments."""
+enum SortDirection {
+  """Ascending order."""
+  ASC
+  """Descending order."""
+  DESC
+}
+
+"""Represents a monetary amount with its currency."""
+type Money {
+  """Decimal amount (e.g. "49.99")."""
+  amount: Decimal!
+  """ISO 4217 currency code (e.g. "USD", "BRL")."""
+  currencyCode: CurrencyCode!
+}
+
+"""A price range, useful for showing "from – to" on product cards."""
+type PriceRange {
+  """Lowest price across all variants."""
+  min: Money!
+  """Highest price across all variants."""
+  max: Money!
+}
+
+"""ISO 4217 currency codes. Extend as needed."""
+enum CurrencyCode {
+  """United States Dollar."""
+  USD
+  """Euro."""
+  EUR
+  """British Pound Sterling."""
+  GBP
+  """Brazilian Real."""
+  BRL
+  """Argentine Peso."""
+  ARS
+  """Chilean Peso."""
+  CLP
+  """Colombian Peso."""
+  COP
+  """Mexican Peso."""
+  MXN
+  """Peruvian Sol."""
+  PEN
+  """Japanese Yen."""
+  JPY
+}
+
+"""An image resource associated with a product variant or other entity."""
+type Image {
+  """Source URL of the image."""
+  url: URI!
+  """Alt text for accessibility."""
+  altText: String
+}
+
+"""A video resource associated with a product."""
+type Video {
+  """Playback URL."""
+  url: URI!
+  """Alt text for accessibility."""
+  altText: String
+  """Preview / poster image."""
+  previewImage: Image
+}
+
+"""Any media attached to a product — image or video."""
+union Media = Image | Video
+
+"""Search engine optimization metadata for any displayable entity."""
+type SEO {
+  """Page title (`<title>` tag)."""
+  title: String
+  """Meta description."""
+  description: String
+}
+
+"""Root query type for the storefront API."""
+type Query {
+  """
+  Fetch any entity by its global ID.
+  Clients use this for refetching or cache normalization.
+  """
+  node(
+    """The globally unique ID."""
+    id: ID!
+  ): Node
+  """Fetch multiple entities by their global IDs."""
+  nodes(
+    """A list of globally unique IDs."""
+    ids: [ID!]!
+  ): [Node]!
+}
+
+extend type Query {
+  """Look up a single product by global ID."""
+  product(
+    """Global product ID."""
+    id: ID!
+  ): Product
+  """Look up a single product by its URL slug."""
+  productBySlug(
+    """URL-friendly handle (e.g. \"nike-zoom-janoski-red\")."""
+    slug: String!
+  ): Product
+  """Paginated, filterable list of products."""
+  products(
+    """Returns the first N elements."""
+    first: Int
+    """Returns elements after this cursor."""
+    after: Cursor
+    """Returns the last N elements."""
+    last: Int
+    """Returns elements before this cursor."""
+    before: Cursor
+    """Sorting criteria."""
+    orderBy: ProductSortingInput
+    """Filter criteria."""
+    filter: ProductsFilterInput
+  ): ProductsConnection!
+  """
+  Full-text product search with facets and filters.
+  Returns the same connection shape but is backed by the search engine
+  rather than the catalog database.
+  """
+  productSearch(
+    """Search query string."""
+    query: String!
+    """Returns the first N elements."""
+    first: Int
+    """Returns elements after this cursor."""
+    after: Cursor
+    """Returns the last N elements."""
+    last: Int
+    """Returns elements before this cursor."""
+    before: Cursor
+    """Sorting criteria."""
+    orderBy: ProductSortingInput
+    """Filter criteria."""
+    filter: ProductsFilterInput
+  ): ProductSearchResult!
+  """
+  Product recommendations based on a seed product (frequently bought
+  together, similar items, etc.).
+  """
+  productRecommendations(
+    """URL slug of the product to base recommendations on."""
+    slug: String!
+    """The recommendation strategy to use."""
+    intent: RecommendationIntent
+    """Maximum number of recommendations."""
+    first: Int = 10
+  ): [Product!]!
+  """Look up a single category by global ID."""
+  category(
+    """Global category ID."""
+    id: ID!
+  ): Category
+  """Look up a category by its URL slug."""
+  categoryBySlug(
+    """URL-friendly slug."""
+    slug: String!
+  ): Category
+  """
+  The full category tree starting from root departments.
+  Accepts a `maxDepth` to limit tree traversal (default: all levels).
+  """
+  categoryTree(
+    """Maximum depth of the tree to return. Maps to VTEX `categoryLevels`."""
+    maxDepth: Int
+  ): [Category!]!
+  """Paginated flat list of categories."""
+  categories(
+    """Returns the first N elements."""
+    first: Int
+    """Returns elements after this cursor."""
+    after: Cursor
+    """Returns the last N elements."""
+    last: Int
+    """Returns elements before this cursor."""
+    before: Cursor
+    """Sorting criteria."""
+    orderBy: CategorySortingInput
+  ): CategoriesConnection!
+  """Look up a single brand by global ID."""
+  brand(
+    """Global brand ID."""
+    id: ID!
+  ): Brand
+  """
+  All brands available in the store, derived from the search index.
+  Returns brands with their product counts.
+  """
+  brands(
+    """Returns the first N elements."""
+    first: Int
+    """Returns elements after this cursor."""
+    after: Cursor
+    """Returns the last N elements."""
+    last: Int
+    """Returns elements before this cursor."""
+    before: Cursor
+  ): BrandsConnection!
+  """Look up a single sales channel by global ID."""
+  salesChannel(
+    """Global sales channel ID."""
+    id: ID!
+  ): SalesChannel
+  """
+  Autocomplete suggestions for a partial search query.
+  Returns suggested terms with estimated result counts and facet attributes.
+  """
+  autocompleteSuggestions(
+    """Partial search query (e.g. \"choc\")."""
+    query: String!
+  ): [AutocompleteSuggestion!]!
+  """The most popular search terms in the last 14 days."""
+  topSearches: [TrendingSearch!]!
+  """
+  Spelling correction for a potentially misspelled search query.
+  Returns null if no correction is available.
+  """
+  searchCorrection(
+    """The potentially misspelled query."""
+    query: String!
+  ): SearchCorrection
+}
+
+extend type Query {
+  """
+  Resolve the active cart from the request context (x-order-form-id header,
+  then cookie). When no cart context is present, a new cart is created and
+  the x-order-form-id cookie is set on the response.
+  """
+  cart: Cart!
+}
+
+extend type Query {
+  """
+  Simulate available shipping options for a variant on a product detail page.
+  Returns delivery options with estimated times and prices for the given
+  postal code and item.
+  """
+  shippingSimulation(
+    """Simulation input: destination, SKU, quantity, and seller."""
+    input: ShippingSimulateInput!
+  ): ShippingSimulationPayload!
+  """
+  Simulate shipping options for the entire active cart. Reads the cart from the
+  x-order-form-id context and simulates all of its items against the
+  destination, returning the options common to every item with prices summed
+  across items. Never mints a cart: absent context returns a MISSING_CART_CONTEXT
+  userError.
+  """
+  cartShippingSimulation(
+    """Simulation input: destination only. Items come from the active cart."""
+    input: CartShippingSimulateInput!
+  ): CartShippingSimulationPayload!
+}
+
+extend type Query {
+  """
+  The shopper's profile for the active cart, resolved from the same order form
+  as `cart`. The entity always resolves; its fields are null when unset.
+  """
+  clientProfile: ClientProfile!
+  """
+  The shopper's preferences for the active cart, resolved from the same order
+  form as `cart`. The entity always resolves; its fields are null when unset.
+  """
+  clientPreferences: ClientPreferences!
+}
+
+extend type Query {
+  """
+  The cart's shipping state. Projected from the same order form as Query.cart.
+  """
+  shipping: Shipping!
+  """
+  Resolve the shopper's session state from the active order form (x-order-form-id
+  header, then cookie). Projects from the same order form fetch as `cart`.
+  """
+  session: Session!
+}
+
+extend type Query {
+  """Which authentication methods this account enables."""
+  sessionAuthProviders: SessionAuthProviders!
+}
+
+extend type Query {
+  """
+  The shopper's active region, or null when none has been set. Takes no
+  arguments by design: the postal code travels on the transport.
+  """
+  region: Region
+}
+
+extend type Query {
+  """
+  The signed-in shopper's own persistent profile. Takes no id — the identity
+  comes from the session. Non-null like `cart`/`session`: it always resolves to
+  the shopper's entity (a shell with null fields when the record is empty) or
+  throws UNAUTHORIZED / UPSTREAM_ERROR (ADR-00007), never returning null.
+  """
+  customerProfile: CustomerProfile!
+}
+
+"""
+Root mutation type. Cart and checkout operations are declared via
+`extend type Mutation` in the checkout module.
+"""
+type Mutation {
+  """
+  Exists only so `extend type Mutation` in feature modules is valid for schema
+  linters and subgraph composition; not intended for client use.
+  """
+  inertMutationPlaceholder: Boolean
+  """Placeholder field — removed once a real mutation is added via extend."""
+  empty: String @deprecated(reason: "Placeholder — will be dropped when the first real mutation is added.")
+}
+
+extend type Mutation {
+  """
+  Add an item to the cart. If the variant already exists in the cart, its
+  quantity is increased by the given amount.
+  """
+  cartItemAdd(
+    """Item details to add."""
+    input: CartItemAddInput!
+  ): CartItemAddPayload!
+  """Remove an item from the cart entirely (sets quantity to 0)."""
+  cartItemRemove(
+    """Item to remove."""
+    input: CartItemRemoveInput!
+  ): CartItemRemovePayload!
+  """
+  Remove multiple items from the cart in a single upstream write (each line's
+  quantity is set to 0). Tolerant: variants absent from the cart are skipped.
+  """
+  cartItemsRemove(
+    """Items to remove."""
+    input: CartItemsRemoveInput!
+  ): CartItemsRemovePayload!
+  """Increase the quantity of an existing cart item."""
+  cartItemQuantityIncrease(
+    """Item and quantity details."""
+    input: CartItemQuantityIncreaseInput!
+  ): CartItemQuantityIncreasePayload!
+  """
+  Decrease the quantity of an existing cart item.
+  If the resulting quantity would be zero or less, the item is removed.
+  """
+  cartItemQuantityDecrease(
+    """Item and quantity details."""
+    input: CartItemQuantityDecreaseInput!
+  ): CartItemQuantityDecreasePayload!
+  """
+  Apply a coupon code to the active cart. Appends to the existing set and returns
+  the recomputed cart, or typed errors when the code is rejected.
+  """
+  cartCouponApply(
+    """Coupon code to apply."""
+    input: CartCouponApplyInput!
+  ): CartCouponApplyPayload!
+  """
+  Remove a coupon code from the active cart. Idempotent when the code is not applied.
+  """
+  cartCouponRemove(
+    """Coupon code to remove."""
+    input: CartCouponRemoveInput!
+  ): CartCouponRemovePayload!
+  """
+  Re-check the active cart against the platform and return it with each line's
+  availability refreshed. Writes nothing: the cart is re-simulated and only
+  `items.variant.availability` is corrected, so a line the platform can no longer
+  fulfil comes back flagged for the shopper to remove. Quantities are never
+  altered, and totals stay as the cart reported them until that removal
+  recomputes them. Takes no arguments: the cart is resolved from the request
+  context and is never created.
+  """
+  cartValidate: CartValidatePayload!
+}
+
+extend type Mutation {
+  """
+  Write the provided profile fields to the active cart's clientProfileData
+  attachment. Partial: omitted fields are untouched. Never mints a cart.
+  """
+  clientProfileUpdate(
+    """Profile fields to write."""
+    input: ClientProfileUpdateInput!
+  ): ClientProfileUpdatePayload!
+  """
+  Write the provided preference flags to the active cart's clientPreferencesData
+  attachment. Partial: omitted flags are untouched. Never mints a cart.
+  """
+  clientPreferencesUpdate(
+    """Preference flags to write."""
+    input: ClientPreferencesUpdateInput!
+  ): ClientPreferencesUpdatePayload!
+  """
+  Set the full delivery address (delivery step). Auto-selects the cheapest SLA
+  when available. Never mints a cart.
+  """
+  shippingAddressUpdate(
+    """Address details to write."""
+    input: ShippingAddressUpdateInput!
+  ): ShippingAddressUpdatePayload!
+  """
+  Select one shipping option for the whole cart. Fans the selection out to
+  every item. Never mints a cart.
+  """
+  shippingOptionSelect(
+    """The option to select."""
+    input: ShippingOptionSelectInput!
+  ): ShippingOptionSelectPayload!
+}
+
+extend type Mutation {
+  """
+  Sign in with email and password. Returns the refreshed session, or typed
+  userErrors.
+  """
+  sessionLoginWithPassword(
+    """The email and password to authenticate with."""
+    input: SessionPasswordLoginInput!
+  ): SessionLoginPayload!
+  """
+  Request an email access code. Returns an opaque authenticationToken to
+  round-trip into validate.
+  """
+  sessionRequestAccessCode(
+    """The email to send the access code to."""
+    input: SessionRequestAccessCodeInput!
+  ): SessionRequestAccessCodePayload!
+  """
+  Validate an email access code with its authenticationToken. Returns the
+  refreshed session.
+  """
+  sessionValidateAccessCode(
+    """The email, access code, and authenticationToken to validate."""
+    input: SessionValidateAccessCodeInput!
+  ): SessionLoginPayload!
+  """
+  Sign out. Clears auth cookies and refreshes the order form to a guest session.
+  Idempotent.
+  """
+  sessionLogout: SessionLoginPayload!
+}
+
+extend type Mutation {
+  """
+  Set the shopper's active region from a postal code. Accepts the value as the
+  shopper typed it, including any mask; the server normalizes it and derives the
+  city.
+  """
+  regionUpdate(
+    """The postal code to activate, masked or bare."""
+    postalCode: String!
+  ): RegionUpdatePayload!
+}
+
+extend type Mutation {
+  """
+  Partially update the signed-in shopper's own profile. Upserts: succeeds whether or not a record exists.
+  """
+  customerProfileUpdate(
+    """The fields to write. Provide only what the shopper edited."""
+    input: CustomerProfileUpdateInput!
+  ): CustomerProfileUpdatePayload!
+}
+
+"""
+A manufacturer or designer brand.
+Maps to VTEX Brand entity.
+"""
+type Brand implements Node @cacheControl(maxAge: 300, scope: PUBLIC) {
+  """Globally unique identifier."""
+  id: ID!
+  """Human-readable brand name."""
+  name: String!
+  """URL-friendly slug."""
+  slug: String!
+  """Whether the brand is currently active in the storefront."""
+  isActive: Boolean!
+  """Brand logo image."""
+  logo: Image
+  """SEO metadata."""
+  seo: SEO
+  """Paginated list of products belonging to this brand."""
+  products(
+    """Returns the first N elements."""
+    first: Int
+    """Returns elements after this cursor."""
+    after: Cursor
+    """Returns the last N elements."""
+    last: Int
+    """Returns elements before this cursor."""
+    before: Cursor
+    """Sorting criteria."""
+    orderBy: ProductSortingInput
+    """Filter criteria."""
+    filter: ProductsFilterInput
+  ): ProductsConnection!
+}
+
+"""Paginated list of brands."""
+type BrandsConnection {
+  """A list of edges."""
+  edges: [BrandEdge!]!
+  """Information to aid in pagination."""
+  pageInfo: PageInfo!
+  """Total number of brands matching the query."""
+  totalCount: Int!
+}
+
+"""An edge in a connection."""
+type BrandEdge {
+  """A cursor for pagination."""
+  cursor: Cursor!
+  """The item at the end of the edge."""
+  node: Brand!
+}
+
+"""
+A hierarchical product classification level (department → category → subcategory).
+Maps to VTEX Category entity. The tree structure is modeled via parent/children
+references, allowing arbitrary depth.
+"""
+type Category implements Node @cacheControl(maxAge: 300, scope: PUBLIC) {
+  """Globally unique identifier."""
+  id: ID!
+  """Display name of the category."""
+  name: String!
+  """URL-friendly slug."""
+  slug: String!
+  """Full materialized path, e.g. \"/clothing/shirts/casual\"."""
+  path: String!
+  """Zero-indexed depth in the tree (0 = department)."""
+  level: Int!
+  """Whether this category is currently active."""
+  isActive: Boolean!
+  """Parent category. Null for top-level departments."""
+  parent: Category
+  """Direct children of this category."""
+  children: [Category!]!
+  """SEO metadata."""
+  seo: SEO
+  """Paginated products within this category."""
+  products(
+    """Returns the first N elements."""
+    first: Int
+    """Returns elements after this cursor."""
+    after: Cursor
+    """Returns the last N elements."""
+    last: Int
+    """Returns elements before this cursor."""
+    before: Cursor
+    """Sorting criteria."""
+    orderBy: ProductSortingInput
+    """Filter criteria."""
+    filter: ProductsFilterInput
+  ): ProductsConnection!
+  """Specification groups relevant to this category."""
+  specificationGroups: [SpecificationGroup!]!
+}
+
+"""Paginated list of categories."""
+type CategoriesConnection {
+  """A list of edges."""
+  edges: [CategoryEdge!]!
+  """Information to aid in pagination."""
+  pageInfo: PageInfo!
+  """Total number of categories matching the query."""
+  totalCount: Int!
+}
+
+"""An edge in a connection."""
+type CategoryEdge {
+  """A cursor for pagination."""
+  cursor: Cursor!
+  """The item at the end of the edge."""
+  node: Category!
+}
+
+"""
+A group of related specifications that apply to products in a category.
+Maps to VTEX Specification Group.
+"""
+type SpecificationGroup {
+  """Display name (e.g. \"Physical Attributes\", \"Technical Details\")."""
+  name: String!
+  """Specifications in this group."""
+  specifications: [Specification!]!
+}
+
+"""
+A product-level or variant-level specification field.
+Maps to VTEX Specification / Specification Field.
+Examples: "Material", "Warranty Period" (product-level);
+"Color", "Size" (variant-level / option axis).
+"""
+type Specification {
+  """Display label (e.g. \"Material\")."""
+  name: String!
+  """The assigned values for this specification."""
+  values: [String!]!
+  """How this spec was captured."""
+  fieldType: SpecificationFieldType!
+}
+
+"""A single breadcrumb entry in the product's navigation trail."""
+type BreadcrumbItem {
+  """Human-readable label (e.g. "Electronics", "Smartphones")."""
+  name: String!
+  """URL path for this breadcrumb level (e.g. "/electronics/smartphones")."""
+  url: String!
+  """1-based position in the breadcrumb trail."""
+  position: Int!
+}
+
+"""
+Discriminates how a specification value was captured.
+Maps to VTEX FieldType numeric codes.
+"""
+enum SpecificationFieldType {
+  """Free text."""
+  TEXT
+  """Multi-line free text."""
+  MULTI_LINE_TEXT
+  """Single-select dropdown."""
+  COMBO
+  """Single-select radio."""
+  RADIO
+  """Multi-select checkbox."""
+  CHECKBOX
+  """Rich text / HTML."""
+  RICH_TEXT
+}
+
+"""
+A named option axis on a product that differentiates variants.
+Think "Color" or "Size". Each option has a set of possible values.
+Similar to Shopify's ProductOption.
+"""
+type ProductOption {
+  """Option name (e.g. \"Color\")."""
+  name: String!
+  """
+  All values available across variants (e.g. [\"Red\", \"Blue\", \"Green\"]).
+  """
+  values: [String!]!
+}
+
+"""
+A concrete option/value pair selected on a specific variant.
+Example: { name: "Color", value: "Red" }.
+"""
+type SelectedOption {
+  """Option axis name."""
+  name: String!
+  """Selected value."""
+  value: String!
+}
+
+"""
+A purchasable unit of a product.
+Maps to VTEX SKU. In commerce, this is the concrete item a customer adds to cart —
+a specific size/color/voltage combination of a product.
+"""
+type Variant implements Node {
+  """Globally unique identifier."""
+  id: ID!
+  """Variant display name (e.g. \"Varsity Red — Size 10\")."""
+  name: String!
+  """Stock Keeping Unit code. Unique merchant-side identifier."""
+  sku: String!
+  """International Article Number (barcode). Maps to VTEX SKU EAN."""
+  ean: String
+  """Merchant reference code."""
+  referenceId: String
+  """Whether this variant is currently available for purchase."""
+  availableForSale: Boolean!
+  """Current selling price."""
+  price: Money!
+  """Original list price before promotions. Null when there is no discount."""
+  compareAtPrice: Money
+  """All option selections that define this variant."""
+  selectedOptions: [SelectedOption!]!
+  """Variant images. First image is the primary."""
+  images(
+    """Returns the first N elements."""
+    first: Int = 10
+    """Returns elements after this cursor."""
+    after: Cursor
+    """Returns the last N elements."""
+    last: Int
+    """Returns elements before this cursor."""
+    before: Cursor
+  ): ImagesConnection!
+  """Variant videos."""
+  videos: [Video!]!
+  """Quantity currently in stock. Null when inventory tracking is disabled."""
+  quantityAvailable: Int
+  """Unit of sale (e.g. \"un\", \"kg\", \"l\")."""
+  measurementUnit: String!
+  """
+  Multiplier for the measurement unit (e.g. 1.5 means each unit is 1.5 kg).
+  """
+  unitMultiplier: Float!
+  """The parent product."""
+  product: Product!
+  """Variant-level specifications (e.g. voltage, plug type)."""
+  specifications: [Specification!]!
+  """Add-on customizations available for this variant."""
+  customizations: [Customization!]!
+  """Sellers that fulfill this variant. Relevant in marketplace scenarios."""
+  sellers: [Seller!]!
+}
+
+"""Paginated list of variants."""
+type VariantsConnection {
+  """A list of edges."""
+  edges: [VariantEdge!]!
+  """Information to aid in pagination."""
+  pageInfo: PageInfo!
+  """Total number of variants matching the query."""
+  totalCount: Int!
+}
+
+"""An edge in a connection."""
+type VariantEdge {
+  """A cursor for pagination."""
+  cursor: Cursor!
+  """The item at the end of the edge."""
+  node: Variant!
+}
+
+"""
+A product is a generic item in the catalog (e.g. "Nike Zoom Janoski").
+Each product has one or more variants (SKUs) that are the purchasable units.
+Maps to the VTEX Product entity.
+"""
+type Product implements Node @cacheControl(maxAge: 60, scope: PUBLIC) {
+  """Globally unique identifier."""
+  id: ID!
+  """Product title as displayed in the storefront."""
+  title: String!
+  """URL-friendly handle / slug. Maps to VTEX `LinkId`."""
+  slug: String!
+  """Full marketing description."""
+  description: String
+  """Description rendered as HTML."""
+  descriptionHtml: HTML
+  """Vendor / manufacturer name. Shortcut for brand.name."""
+  vendor: String
+  """Whether this product is currently active on the storefront."""
+  isActive: Boolean!
+  """Whether to show the product even when out of stock."""
+  showWhenOutOfStock: Boolean!
+  """Date the product was first published."""
+  publishedAt: DateTime
+  """Release or launch date."""
+  releaseDate: DateTime
+  """Date the product was created in the system."""
+  createdAt: DateTime!
+  """Date the product was last updated."""
+  updatedAt: DateTime!
+  """Merchant reference ID. Maps to VTEX `RefId`."""
+  referenceId: String
+  """The brand this product belongs to."""
+  brand: Brand
+  """The primary (most specific) category."""
+  category: Category
+  """All ancestor categories up to the root department."""
+  categories: [Category!]!
+  """The price range across all variants."""
+  priceRange: PriceRange!
+  """The compare-at (original) price range across all variants."""
+  compareAtPriceRange: PriceRange
+  """Named option axes available on this product (e.g. Color, Size)."""
+  options: [ProductOption!]!
+  """Product-level specifications (e.g. material, care instructions)."""
+  specifications: [Specification!]!
+  """Specification groups with full detail."""
+  specificationGroups: [SpecificationGroup!]!
+  """All purchasable variants."""
+  variants(
+    """Returns the first N elements."""
+    first: Int
+    """Returns elements after this cursor."""
+    after: Cursor
+    """Returns the last N elements."""
+    last: Int
+    """Returns elements before this cursor."""
+    before: Cursor
+  ): VariantsConnection!
+  """Total number of variants."""
+  totalVariants: Int!
+  """Product images aggregated from all variants."""
+  images(
+    """Returns the first N elements."""
+    first: Int = 10
+    """Returns elements after this cursor."""
+    after: Cursor
+    """Returns the last N elements."""
+    last: Int
+    """Returns elements before this cursor."""
+    before: Cursor
+  ): ImagesConnection!
+  """All media (images + videos) for this product."""
+  media(
+    """Returns the first N elements."""
+    first: Int = 12
+    """Returns elements after this cursor."""
+    after: Cursor
+    """Returns the last N elements."""
+    last: Int
+    """Returns elements before this cursor."""
+    before: Cursor
+  ): MediaConnection!
+  """SEO metadata."""
+  seo: SEO
+  """Navigation breadcrumb trail from root category to this product."""
+  breadcrumbs: [BreadcrumbItem!]!
+  """User-generated review / rating summary."""
+  rating: Rating
+  """
+  Products related to this one (accessories, suggestions). Maps to VTEX SKU Complement.
+  """
+  relatedProducts(
+    """Returns the first N elements."""
+    first: Int = 10
+    """Returns elements after this cursor."""
+    after: Cursor
+    """Returns the last N elements."""
+    last: Int
+    """Returns elements before this cursor."""
+    before: Cursor
+  ): ProductsConnection!
+  """Collections this product belongs to."""
+  collections: [Collection!]!
+  """
+  Sales channels where this product is available. Maps to VTEX Trade Policy.
+  """
+  salesChannels: [SalesChannel!]!
+  """Bundle components if this product is a kit. Maps to VTEX SKU Kit."""
+  bundleItems: [BundleItem!]!
+}
+
+"""Paginated list of products."""
+type ProductsConnection {
+  """A list of edges."""
+  edges: [ProductEdge!]!
+  """Information to aid in pagination."""
+  pageInfo: PageInfo!
+  """Total number of products matching the query."""
+  totalCount: Int!
+}
+
+"""An edge in a connection."""
+type ProductEdge {
+  """A cursor for pagination."""
+  cursor: Cursor!
+  """The item at the end of the edge."""
+  node: Product!
+}
+
+"""Paginated list of images."""
+type ImagesConnection {
+  """A list of edges."""
+  edges: [ImageEdge!]!
+  """Information to aid in pagination."""
+  pageInfo: PageInfo!
+}
+
+"""An edge in a connection."""
+type ImageEdge {
+  """A cursor for pagination."""
+  cursor: Cursor!
+  """The item at the end of the edge."""
+  node: Image!
+}
+
+"""Paginated list of media."""
+type MediaConnection {
+  """A list of edges."""
+  edges: [MediaEdge!]!
+  """Information to aid in pagination."""
+  pageInfo: PageInfo!
+}
+
+"""An edge in a connection."""
+type MediaEdge {
+  """A cursor for pagination."""
+  cursor: Cursor!
+  """The item at the end of the edge."""
+  node: Media!
+}
+
+"""
+Aggregate review/rating summary for a product.
+Maps to VTEX Product Review Rate.
+"""
+type Rating {
+  """Average score (e.g. 4.3)."""
+  average: Float!
+  """Total number of reviews."""
+  count: Int!
+}
+
+"""
+A curated group of products. Maps to VTEX Collection (Beta) entity.
+Collections can be used for seasonal promotions, editorial picks, etc.
+"""
+type Collection implements Node {
+  """Globally unique identifier."""
+  id: ID!
+  """Collection title."""
+  title: String!
+  """URL-friendly slug."""
+  slug: String!
+  """Editorial description."""
+  description: String
+  """Whether the collection is currently active."""
+  isActive: Boolean!
+  """Hero / banner image."""
+  image: Image
+  """SEO metadata."""
+  seo: SEO
+  """Paginated products in this collection."""
+  products(
+    """Returns the first N elements."""
+    first: Int
+    """Returns elements after this cursor."""
+    after: Cursor
+    """Returns the last N elements."""
+    last: Int
+    """Returns elements before this cursor."""
+    before: Cursor
+    """Sorting criteria."""
+    orderBy: ProductSortingInput
+    """Filter criteria."""
+    filter: ProductsFilterInput
+  ): ProductsConnection!
+}
+
+"""Paginated list of collections."""
+type CollectionsConnection {
+  """A list of edges."""
+  edges: [CollectionEdge!]!
+  """Information to aid in pagination."""
+  pageInfo: PageInfo!
+  """Total number of collections matching the query."""
+  totalCount: Int!
+}
+
+"""An edge in a connection."""
+type CollectionEdge {
+  """A cursor for pagination."""
+  cursor: Cursor!
+  """The item at the end of the edge."""
+  node: Collection!
+}
+
+"""
+A seller / merchant that fulfills orders for one or more variants.
+Maps to VTEX Seller entity.
+"""
+type Seller implements Node {
+  """Globally unique identifier."""
+  id: ID!
+  """Seller display name."""
+  name: String!
+  """Whether this is the default (1P) seller."""
+  isDefault: Boolean!
+  """Seller logo."""
+  logo: Image
+  """
+  The seller's commercial offer for this variant (price, availability, installments).
+  """
+  offer: Offer
+}
+
+"""
+A seller's commercial offer for a specific variant — includes pricing,
+availability, and available payment/installment options.
+"""
+type Offer {
+  """Current selling price."""
+  price: Money!
+  """Original list price before promotions."""
+  listPrice: Money!
+  """
+  Best cash/immediate-payment price (e.g. Pix discount). Equals price when there is no spot discount.
+  """
+  spotPrice: Money!
+  """Price before any cart-level or coupon discounts."""
+  priceWithoutDiscount: Money!
+  """Available quantity from this seller."""
+  availableQuantity: Int!
+  """Tax amount."""
+  tax: Money!
+  """
+  Tax as a percentage of the price (e.g. 0.18 for 18%). Null when not applicable.
+  """
+  taxPercentage: Float
+  """Loyalty / reward points value earned on this purchase."""
+  rewardValue: Float!
+  """
+  ISO 8601 timestamp after which this price is no longer guaranteed. Null when open-ended.
+  """
+  priceValidUntil: DateTime
+  """SKU IDs of free gifts included with this offer."""
+  giftSkuIds: [String!]!
+  """
+  Named discount labels applied to this offer (e.g. \"10% off\", \"Black Friday\").
+  """
+  discountHighlights: [String!]!
+  """Available installment plans grouped by payment method."""
+  installmentPlans: [InstallmentPlan!]!
+  """
+  Active promotions applicable to this offer (e.g. bundle discounts, buy-X-get-Y).
+  """
+  promotions: [Promotion!]!
+}
+
+"""
+A group of installment options for a single payment method (e.g. "Visa", "Pix").
+"""
+type InstallmentPlan {
+  """Payment method name (e.g. \"Visa\", \"Mastercard\", \"Pix\")."""
+  paymentMethod: String!
+  """Payment method category."""
+  paymentType: PaymentType!
+  """
+  Available installment tiers, sorted by number of installments ascending.
+  """
+  installments: [Installment!]!
+}
+
+"""
+A single installment tier within a payment method.
+Example: 6 × R$ 61.65 at 0% interest.
+"""
+type Installment {
+  """Number of installments (1 = single payment)."""
+  count: Int!
+  """Amount per installment."""
+  value: Money!
+  """Total amount including any interest."""
+  totalAmount: Money!
+  """Annual interest rate as a percentage (0 = interest-free)."""
+  interestRate: Float!
+  """Whether this tier is interest-free."""
+  interestFree: Boolean!
+}
+
+"""Broad category of a payment method."""
+enum PaymentType {
+  """Credit card (Visa, Mastercard, Amex, etc.)."""
+  CREDIT_CARD
+  """Debit card."""
+  DEBIT_CARD
+  """Instant / real-time payment (Pix, etc.)."""
+  INSTANT
+  """Bank slip / boleto."""
+  BANK_SLIP
+  """Digital wallet or store-specific payment."""
+  DIGITAL_WALLET
+  """Other / unknown payment type."""
+  OTHER
+}
+
+"""
+An active promotion or incentive applicable to an offer.
+Examples: "Buy 3 for R$14.99", "9% Pix discount".
+"""
+type Promotion {
+  """Human-readable promotion name / headline."""
+  name: String!
+  """Conditions that must be met for the promotion to apply."""
+  conditions: PromotionConditions!
+  """Effects applied when conditions are met."""
+  effects: PromotionEffects!
+}
+
+"""Conditions required for a promotion to activate."""
+type PromotionConditions {
+  """Minimum quantity of items required (0 = no minimum)."""
+  minimumQuantity: Int!
+  """
+  Additional condition parameters (e.g. required payment method, collection membership).
+  """
+  parameters: [PromotionParameter!]!
+}
+
+"""Effects granted when a promotion's conditions are satisfied."""
+type PromotionEffects {
+  """Effect parameters describing the discount or benefit."""
+  parameters: [PromotionParameter!]!
+}
+
+"""
+A key-value parameter describing a promotion condition or effect.
+Common keys: \"PercentualDiscount\", \"MaximumUnitPriceDiscount\",
+\"PaymentMethodId\", \"CollectionsIdsList\".
+"""
+type PromotionParameter {
+  """Parameter key."""
+  name: String!
+  """Parameter value."""
+  value: String!
+}
+
+"""
+A trade policy / sales channel through which products are sold.
+Maps to VTEX Trade Policy / Sales Channel.
+"""
+type SalesChannel implements Node @cacheControl(maxAge: 3600, scope: PUBLIC) {
+  """Globally unique identifier."""
+  id: ID!
+  """Channel name."""
+  name: String!
+  """ISO 4217 default currency for this channel."""
+  currencyCode: CurrencyCode!
+  """BCP 47 locale for this channel."""
+  locale: Locale
+  """Whether the channel is active."""
+  isActive: Boolean!
+}
+
+"""
+An optional, free-form customization that can be attached to a variant.
+Maps to VTEX Attachment. Examples: gift wrapping, engraving, custom message.
+"""
+type Customization implements Node {
+  """Globally unique identifier."""
+  id: ID!
+  """Display name (e.g. \"Gift Message\")."""
+  name: String!
+  """Whether this customization is required."""
+  isRequired: Boolean!
+  """Allowed keys and their constraints."""
+  fields: [CustomizationField!]!
+}
+
+"""A single input field within a customization."""
+type CustomizationField {
+  """Field key (e.g. \"message\")."""
+  key: String!
+  """Maximum allowed characters."""
+  maxLength: Int
+  """Regex or enum-based validation domain."""
+  allowedValues: [String!]
+}
+
+"""
+A component of a product bundle / kit.
+Maps to VTEX SKU Kit.
+"""
+type BundleItem {
+  """The variant included in the bundle."""
+  variant: Variant!
+  """Quantity of this variant in the bundle."""
+  quantity: Int!
+}
+
+"""Filter criteria for product queries."""
+input ProductsFilterInput {
+  """Full-text search term."""
+  searchTerm: String
+  """Include only products in these category IDs."""
+  categoryIds: [ID!]
+  """Include only products from these brand IDs."""
+  brandIds: [ID!]
+  """Minimum price filter."""
+  priceMin: Decimal
+  """Maximum price filter."""
+  priceMax: Decimal
+  """Include only available (in-stock) products."""
+  availableOnly: Boolean
+  """Filter by product type / taxonomy label."""
+  productType: String
+  """
+  Filter by specification values, e.g. {name: \"Color\", values: [\"Red\", \"Blue\"]}.
+  """
+  specifications: [SpecificationFilterInput!]
+  """Filter by sales channel ID."""
+  salesChannelId: ID
+  """Filter by collection ID."""
+  collectionId: ID
+  """Include only products published after this date."""
+  publishedAfter: DateTime
+  """Include only products published before this date."""
+  publishedBefore: DateTime
+  """Filter by tags / keywords."""
+  tags: [String!]
+}
+
+"""Allows filtering products by specification name and values."""
+input SpecificationFilterInput {
+  """Specification name (e.g. \"Color\")."""
+  name: String!
+  """Accepted values (OR semantics within, AND across different specs)."""
+  values: [String!]!
+}
+
+"""Sorting input for product queries."""
+input ProductSortingInput {
+  """Field to sort on."""
+  field: ProductSortField!
+  """Sort direction."""
+  direction: SortDirection!
+}
+
+"""Fields available for sorting products."""
+enum ProductSortField {
+  """Alphabetical by title."""
+  TITLE
+  """By price (uses min variant price)."""
+  PRICE
+  """By creation date."""
+  CREATED_AT
+  """By last update date."""
+  UPDATED_AT
+  """By release date."""
+  RELEASE_DATE
+  """By relevance / scoring."""
+  RELEVANCE
+  """By number of sales."""
+  BEST_SELLING
+}
+
+"""Filter criteria for collection queries."""
+input CollectionsFilterInput {
+  """Full-text search term."""
+  searchTerm: String
+  """Include only active collections."""
+  activeOnly: Boolean
+}
+
+"""Sorting input for collection queries."""
+input CollectionSortingInput {
+  """Field to sort on."""
+  field: CollectionSortField!
+  """Sort direction."""
+  direction: SortDirection!
+}
+
+"""Fields available for sorting collections."""
+enum CollectionSortField {
+  """Alphabetical by title."""
+  TITLE
+  """By creation date."""
+  CREATED_AT
+  """By last update date."""
+  UPDATED_AT
+}
+
+"""Sorting input for brand queries."""
+input BrandSortingInput {
+  """Field to sort on."""
+  field: BrandSortField!
+  """Sort direction."""
+  direction: SortDirection!
+}
+
+"""Fields available for sorting brands."""
+enum BrandSortField {
+  """Alphabetical by name."""
+  NAME
+  """By creation date."""
+  CREATED_AT
+}
+
+"""Sorting input for category queries."""
+input CategorySortingInput {
+  """Field to sort on."""
+  field: CategorySortField!
+  """Sort direction."""
+  direction: SortDirection!
+}
+
+"""Fields available for sorting categories."""
+enum CategorySortField {
+  """Alphabetical by name."""
+  NAME
+  """By depth level in the tree."""
+  LEVEL
+}
+
+"""
+The result of a full-text product search, including facets for building
+filter UI.
+"""
+type ProductSearchResult {
+  """Paginated product results."""
+  products(
+    """Returns the first N elements."""
+    first: Int
+    """Returns elements after this cursor."""
+    after: Cursor
+    """Returns the last N elements."""
+    last: Int
+    """Returns elements before this cursor."""
+    before: Cursor
+  ): ProductsConnection!
+  """Available facets/filters derived from the result set."""
+  facets: [SearchFacet!]!
+  """Corrected or suggested query if the original had a typo."""
+  suggestedQuery: String
+  """Spelling correction details for the query."""
+  correction: SearchCorrection
+}
+
+"""Spelling correction information returned by the search engine."""
+type SearchCorrection {
+  """Whether the original query was corrected."""
+  corrected: Boolean!
+  """Whether the original query was misspelled."""
+  misspelled: Boolean!
+  """The corrected query text."""
+  text: String
+  """The corrected text with `<em>` tags highlighting the changed parts."""
+  highlighted: String
+}
+
+"""A facet returned from search, representing a filterable dimension."""
+type SearchFacet {
+  """Facet name (e.g. \"Brand\", \"Color\", \"Price Range\")."""
+  name: String!
+  """
+  Facet key used in filter parameters (e.g. \"brand\", \"category-1\", \"price\").
+  """
+  key: String!
+  """Type discriminator for rendering the correct UI control."""
+  type: SearchFacetType!
+  """Whether this facet should be hidden from the UI."""
+  hidden: Boolean!
+  """Total number of values in this facet."""
+  quantity: Int!
+  """Individual values within this facet."""
+  values: [SearchFacetValue!]!
+}
+
+"""Discriminates the facet UI control type."""
+enum SearchFacetType {
+  """A list of discrete values (brand, color, size)."""
+  LIST
+  """A numeric range (price)."""
+  RANGE
+}
+
+"""A single value within a search facet."""
+type SearchFacetValue {
+  """Display label."""
+  label: String!
+  """Value to send back in the filter."""
+  value: String!
+  """Number of products matching this facet value."""
+  count: Int!
+  """Whether the user has currently selected this value."""
+  isSelected: Boolean!
+  """For RANGE facets: the lower bound."""
+  rangeFrom: Float
+  """For RANGE facets: the upper bound."""
+  rangeTo: Float
+  """Navigable href for this facet selection."""
+  href: String
+}
+
+"""Recommendation strategy hint."""
+enum RecommendationIntent {
+  """Products related by purchase history."""
+  RELATED
+  """Products frequently bought together."""
+  COMPLEMENTARY
+  """Similar products (same category / specs)."""
+  SIMILAR
+}
+
+"""An autocomplete suggestion returned for a partial search query."""
+type AutocompleteSuggestion {
+  """The suggested search term."""
+  term: String!
+  """Estimated number of results for this term."""
+  count: Int!
+  """
+  Suggested facet filters associated with this term (e.g. department, category).
+  """
+  attributes: [AutocompleteAttribute!]!
+}
+
+"""A facet attribute suggested alongside an autocomplete term."""
+type AutocompleteAttribute {
+  """Attribute key (e.g. \"category-1\")."""
+  key: String!
+  """Attribute value (e.g. \"alimentos-e-bebidas\")."""
+  value: String!
+  """Human-readable label for the key (e.g. \"Departamento\")."""
+  labelKey: String!
+  """Human-readable label for the value (e.g. \"Alimentos e bebidas\")."""
+  labelValue: String!
+}
+
+"""A trending search term."""
+type TrendingSearch {
+  """The search term."""
+  term: String!
+  """Number of searches in the recent period."""
+  count: Int!
+}
+
+"""
+A shopping cart representing items a customer intends to purchase.
+Maps to the VTEX orderForm entity.
+"""
+type Cart implements Node @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """Globally unique identifier (Relay Node ID)."""
+  id: ID!
+  """Line items currently in the cart."""
+  items: [CartItem!]!
+  """Aggregated totals (items, shipping, discounts, etc.)."""
+  totalizers: [CartTotalizer!]!
+  """Total cart value."""
+  total: Money!
+  """
+  Server messages from cart processing (e.g. promotions applied, stock warnings).
+  """
+  messages: [CartMessage!]!
+  """
+  The coupon codes currently applied to the cart. Empty when none are applied.
+  """
+  appliedCoupons: [AppliedCoupon!]!
+  """
+  Cart-level discounts as labeled lines: one per promotion or coupon, plus a
+  residual for whatever they do not account for. Always a list (possibly empty),
+  never null.
+  
+  The itemized companion to the aggregated "Discounts" totalizer, which stays on
+  `totalizers` unchanged: these entries sum to it, so a summary built on them
+  cannot under-report. Distinct from the per-line `CartItem.discounts`, which is
+  featured-only and itemized per price tag rather than per promotion.
+  """
+  discounts: [CartDiscount!]!
+  """
+  Aggregate item-level catalog markdown: the sum of `(listPrice - price) * quantity`
+  across non-gift lines, clamped at zero (in cents from VTEX, exposed as Money). This
+  is the reduction from each line's list price down to the price the "Items" subtotal
+  is built on — the catalog "de/por" savings baked into the price before any
+  cart-level promotion runs.
+  
+  Distinct money from the cart-level promotions and coupons on the "Discounts"
+  totalizer and `discounts` (those are `price - sellingPrice`, the reduction below the
+  subtotal): item markdown sits *above* the subtotal, so it is never part of
+  `totalizers` and never summed into `total`. It is an informational savings figure and
+  is zero when no line is marked down. Gift lines are excluded — a gift's value is
+  already a promotion entry in `discounts`.
+  """
+  itemMarkdownTotal: Money!
+  """
+  Progress toward the cart's nearest free-shipping promotion. Null when no
+  eligible free-shipping promotion is identified for this cart.
+  """
+  freeShippingProgress: FreeShippingProgress
+  """
+  Non-null when the cart belongs to a different sales channel than the request's active context. The
+  cart is left exactly as it was: nothing here reprices it or removes an item. Converging it is a
+  write, and the first write that carries the active channel makes Checkout reprocess the same
+  orderForm — prices, promotions, coupons and logistics are recomputed and items not sellable in the
+  destination channel are removed by Checkout, while orderFormId, attachments and addresses survive.
+  """
+  salesChannelMismatch: CartSalesChannelMismatch
+}
+
+"""
+The two sales channels that disagree. Both are trade-policy identifiers.
+"""
+type CartSalesChannelMismatch {
+  """The channel the cart is currently on."""
+  cartSalesChannel: String!
+  """The channel the request's active context resolves to."""
+  activeSalesChannel: String!
+}
+
+"""
+Progress toward the cart's nearest free-shipping promotion, derived from the
+promotion teasers on a checkout simulation run with the cart's destination.
+Null until the cart has a destination, and when no eligible free-shipping
+promotion is identified for this cart (none configured, none teaser-emitting,
+empty cart, or unreadable promotion data) — absence is a normal state, never
+an error.
+"""
+type FreeShippingProgress {
+  """
+  Minimum qualifying cart total for the promotion. Null when the cart already
+  qualifies: the promotion teaser disappears once met, so the threshold is no
+  longer reported upstream.
+  """
+  threshold: Money
+  """Amount still to add to qualify. Zero when the cart qualifies."""
+  remaining: Money!
+  """Whether the cart currently qualifies for free shipping."""
+  qualified: Boolean!
+}
+
+"""
+One labeled cart-level discount line, attributed to the promotion or coupon that
+granted it. Amounts are summed from the cart's price tags and reconciled against
+the aggregated "Discounts" totalizer.
+"""
+type CartDiscount {
+  """
+  The promotion's name, or the coupon code exactly as the shopper entered it.
+  Null when nothing upstream names this amount: always for OTHER, and for a
+  promotion the platform left unnamed. The consumer supplies the label in that
+  case; an internal promotion identifier is never exposed here.
+  """
+  name: String
+  """
+  Amount taken off by this line, as a positive monetary value. The minus sign is
+  presentational and applied by the UI. Never zero: a promotion that took nothing
+  off this cart is omitted rather than reported as an empty line.
+  """
+  value: Money!
+  """
+  Where this line came from: an automatic promotion, a coupon, or the residual.
+  """
+  kind: CartDiscountKind!
+}
+
+"""Origin of a cart-level discount line."""
+enum CartDiscountKind {
+  """An automatically applied promotion."""
+  PROMOTION
+  """A promotion matched by a coupon code the shopper entered."""
+  COUPON
+  """
+  The part of the aggregate discount that no named promotion or coupon accounts
+  for — a promotion the merchant did not feature, a discount the platform never
+  itemized, or rounding. At most one entry, always last.
+  """
+  OTHER
+}
+
+"""
+A coupon code applied to the cart, with whether its promotion conditions matched.
+"""
+type AppliedCoupon {
+  """The coupon code, stored verbatim as the shopper entered it."""
+  code: String!
+  """
+  True when the code is on the cart but its promotion conditions did not match
+  (no discount granted).
+  """
+  isUnmatchedCondition: Boolean!
+}
+
+"""
+A single line item in the cart. Carries a historical snapshot of the variant
+and product at the time it was added: cart-line value objects describe what
+the customer actually has, not what the catalog says about it today.
+"""
+type CartItem {
+  """
+  Cart-scoped line identifier (opaque, stable across mutations for the same line).
+  Encoded as Base64("CartItem:<orderFormId>:<uniqueId>"). Not a Relay Node; this id
+  exists only to serve as a stable cache key for clients doing optimistic UI.
+  """
+  id: ID!
+  """
+  Variant snapshot for this line. Built from the order line itself, not from
+  a live catalog read.
+  """
+  variant: CartVariant!
+  """
+  Product snapshot for this line. Built from the order line itself, not from
+  a live catalog read.
+  """
+  product: CartProduct!
+  """Quantity of this variant in the cart."""
+  quantity: Int!
+  """Unit price (in cents from VTEX, exposed as Money)."""
+  price: Money!
+  """Original list price before discounts."""
+  listPrice: Money!
+  """Final selling price after discounts."""
+  sellingPrice: Money!
+  """Whether this line is a gift item."""
+  gift: Boolean!
+  """
+  Discounts applied to this line, one entry per featured promotion price tag that
+  carries a currency amount. Always a list (possibly empty), never null. The
+  per-line, itemized companion to the aggregated "Discounts" totalizer on Cart —
+  not a replacement for it.
+  
+  Percentage-configured promotions are absent: their price tag carries a rate
+  rather than an amount, so there is no monetary value to report per line. Use
+  `Cart.discounts` for a breakdown that accounts for every discount, naming what
+  it can and reporting the rest as a residual.
+  """
+  discounts: [CartItemDiscount!]!
+  """
+  Upstream line identifier (order-form uniqueId). The stable per-line address:
+  with customizations, the same variant can appear as several distinct lines,
+  so variantId is not unique per line. Stable across cart mutations.
+  """
+  lineId: String!
+  """
+  This line's own total (own unit selling price × quantity, rounding-exact),
+  excluding composition children.
+  """
+  ownTotal: Money!
+  """
+  This line's total including all nested composition children, recursively.
+  Equals ownTotal when the line has no compositions.
+  """
+  total: Money!
+  """
+  Form-based customizations applied to this line (personalization text,
+  selections, uploaded-file URLs). Empty when the line has none.
+  """
+  customizations: [CartItemCustomization!]!
+  """
+  Child products added to this line by bundle/assembly choices. Children are
+  not top-level cart lines; they ship, and are removed, with their parent.
+  """
+  compositions: [CartItemComposition!]!
+  """
+  This item's own available delivery options (not intersected across the cart).
+  Excludes pickup options; delivery channel only.
+  """
+  shippingOptions: [ItemShippingOption!]!
+  """
+  This item's own currently selected delivery option, or null when no selection
+  is persisted or the persisted selection is a pickup option.
+  """
+  selectedShippingOption: ItemShippingOption
+}
+
+"""
+One customization group applied to a cart line, keyed by the upstream
+assembly id. Entries are the shopper's submitted key/value pairs.
+"""
+type CartItemCustomization {
+  """Upstream assembly identifier (e.g. "Engraving", "Optional features")."""
+  id: String!
+  """
+  Submitted values, one entry per input field. File uploads carry the file URL
+  as the value.
+  """
+  entries: [CartItemCustomizationEntry!]!
+}
+
+"""A single submitted customization field."""
+type CartItemCustomizationEntry {
+  """Field name as defined by the assembly (e.g. "Text")."""
+  name: String!
+  """Submitted value, stringified. File uploads carry the file URL."""
+  value: String!
+}
+
+"""
+A child product nested under a cart line by a bundle/assembly choice. Slim by
+design: children are not independently addressable cart lines. May carry its
+own children (nested assemblies).
+"""
+type CartItemComposition {
+  """
+  Cart-scoped identifier for this child line (same opaque encoding as
+  CartItem.id). Cache key only; not independently mutable.
+  """
+  id: ID!
+  """Display name as recorded on the order line."""
+  name: String!
+  """Quantity of this child in the composition."""
+  quantity: Int!
+  """Unit selling price of the child."""
+  price: Money!
+  """
+  The child's own availability. The parent's variant.availability already
+  reflects the worst state across the whole composition.
+  """
+  availability: CartItemAvailability!
+  """
+  The assembly group that added this child (upstream parentAssemblyBinding,
+  e.g. "Material Product_Material").
+  """
+  assemblyId: String!
+  """This child's own total, excluding its nested children."""
+  ownTotal: Money!
+  """This child's total including its nested children, recursively."""
+  total: Money!
+  """
+  Form-based customizations applied to this child. A composition child is
+  itself an order-form line and can carry its own input assemblies. Empty
+  when it has none.
+  """
+  customizations: [CartItemCustomization!]!
+  """Nested composition children of this child. Empty when it has none."""
+  compositions: [CartItemComposition!]!
+}
+
+"""
+A single discount applied to a cart line, broken out from that line's price tags.
+Sourced from items[].priceTags filtered to featured promotions carrying a currency
+amount; the aggregate discount total stays on the Cart "Discounts" totalizer.
+"""
+type CartItemDiscount {
+  """
+  Human-readable label resolved from the matched promotion (e.g. "Black Friday").
+  Falls back to the price tag identifier when the promotion has no name.
+  """
+  name: String!
+  """
+  Amount taken off by this discount, as a positive monetary value. The minus
+  sign is presentational and applied by the UI.
+  """
+  value: Money!
+  """
+  Always false. A price tag expressing a percentage carries a rate rather than a
+  currency amount, so it has no value this type can report and is excluded from
+  the list. Retained for compatibility; branching on it gains nothing.
+  """
+  isPercentual: Boolean!
+}
+
+"""
+Stock availability status for a cart line. Mapped from the upstream
+order-form availability strings; UNKNOWN absorbs values we haven't classified.
+"""
+enum CartItemAvailability {
+  """In stock and shippable."""
+  AVAILABLE
+  """Known to be out of stock."""
+  OUT_OF_STOCK
+  """
+  Other known-bad states (cannot deliver, fulfillment unavailable, etc.).
+  """
+  UNAVAILABLE
+  """Upstream returned a state we don't recognize yet."""
+  UNKNOWN
+}
+
+"""
+Cart-line snapshot of a Variant. Value object: holds the line-level facts
+recorded at add-to-cart time. Does not implement Node; refetch the live
+catalog Variant via Query.node(variantId) when needed.
+"""
+type CartVariant {
+  """
+  Relay Node ID of the catalog Variant this line refers to. Use it with
+  Query.node to refetch the live Variant.
+  """
+  variantId: ID!
+  """Stock-keeping unit code as recorded on the order line."""
+  sku: String!
+  """
+  Display name as recorded on the order line (e.g. "Classic T-Shirt - Red / M").
+  """
+  name: String!
+  """
+  Single image captured at add-to-cart time. Null when no image URL was recorded.
+  """
+  image: Image
+  """
+  International Article Number (barcode). May be empty for items without one.
+  """
+  ean: String
+  """Merchant SKU reference code."""
+  referenceId: String
+  """Availability classification of this line."""
+  availability: CartItemAvailability!
+  """Unit of sale (e.g. "un", "kg")."""
+  measurementUnit: String!
+  """Multiplier for the measurement unit."""
+  unitMultiplier: Float!
+  """Seller fulfilling this line."""
+  seller: CartSellerRef!
+  """
+  Variations selected on this cart line (e.g. Cor: Vermelho, Tamanho: M). [] when the SKU has
+  no variations, never null. Resolved server-side from catalog data (ADR-00012); use this field
+  instead of a Query.node(variantId) refetch to read a line's selected options.
+  """
+  selectedOptions: [SelectedOption!]!
+}
+
+"""
+Cart-line snapshot of a Product. Value object: holds the line-level facts
+recorded at add-to-cart time. Does not implement Node; refetch the live
+catalog Product via Query.node(productId) when needed.
+"""
+type CartProduct {
+  """
+  Relay Node ID of the catalog Product. Use it with Query.node to refetch
+  the live Product.
+  """
+  productId: ID!
+  """Product title as recorded on the order line."""
+  title: String!
+  """Product detail URL as recorded on the order line."""
+  detailUrl: String!
+  """Categories root-to-leaf as recorded on the order line."""
+  categories: [CartCategoryRef!]!
+  """
+  Brand reference as recorded on the order line. Null when the product has no brand.
+  """
+  brand: CartBrandRef
+}
+
+"""
+Lightweight reference to a Category captured on a cart line. Carries enough
+identity to deep-link back to the live Category via Query.node.
+"""
+type CartCategoryRef {
+  """Relay Node ID of the catalog Category."""
+  categoryId: ID!
+  """Category name as recorded on the order line."""
+  name: String!
+}
+
+"""Lightweight reference to a Brand captured on a cart line."""
+type CartBrandRef {
+  """Relay Node ID of the catalog Brand."""
+  brandId: ID!
+  """Brand name as recorded on the order line."""
+  name: String!
+}
+
+"""Lightweight reference to a Seller captured on a cart line."""
+type CartSellerRef {
+  """Relay Node ID of the catalog Seller."""
+  sellerId: ID!
+  """Seller display name as recorded on the order line."""
+  name: String!
+}
+
+"""
+An aggregated total section in the cart (e.g. Items, Shipping, Discounts).
+"""
+type CartTotalizer {
+  """Totalizer key (e.g. "Items", "Shipping", "Discounts")."""
+  id: String!
+  """Human-readable label."""
+  name: String!
+  """Totalizer value."""
+  value: Money!
+}
+
+"""
+A server message attached to the cart (promotions applied, warnings, etc.).
+"""
+type CartMessage {
+  """Message code identifier."""
+  code: String
+  """Human-readable message text."""
+  text: String!
+  """Message severity (e.g. "info", "warning", "error")."""
+  status: String!
+}
+
+"""Input for adding an item to a cart."""
+input CartItemAddInput {
+  """The variant's global Node ID to add."""
+  variantId: ID!
+  """Quantity to add. Defaults to 1."""
+  quantity: Int = 1
+  """
+  The seller's global Node ID. Defaults to the first-party seller (Seller:1).
+  """
+  seller: ID = "U2VsbGVyOjE="
+}
+
+"""Input for removing an item from a cart."""
+input CartItemRemoveInput {
+  """The variant's global Node ID to remove."""
+  variantId: ID!
+}
+
+"""Input for removing multiple items from a cart in one call."""
+input CartItemsRemoveInput {
+  """The variants' global Node IDs to remove. Duplicates are collapsed."""
+  variantIds: [ID!]!
+}
+
+"""Input for increasing the quantity of a cart item."""
+input CartItemQuantityIncreaseInput {
+  """The variant's global Node ID whose quantity to increase."""
+  variantId: ID!
+  """Amount to add to the current quantity. Defaults to 1."""
+  quantityToAdd: Int = 1
+}
+
+"""Input for decreasing the quantity of a cart item."""
+input CartItemQuantityDecreaseInput {
+  """The variant's global Node ID whose quantity to decrease."""
+  variantId: ID!
+  """Amount to subtract from the current quantity. Defaults to 1."""
+  quantityToRemove: Int = 1
+}
+
+"""Input for applying a coupon code to the cart."""
+input CartCouponApplyInput {
+  """The coupon code to apply, sent verbatim."""
+  code: String!
+}
+
+"""Input for removing a coupon code from the cart."""
+input CartCouponRemoveInput {
+  """The coupon code to remove from the applied set."""
+  code: String!
+}
+
+"""Error codes for cart item add operations."""
+enum CartItemAddErrorCode {
+  """No cart context was provided (x-order-form-id header/cookie)."""
+  MISSING_CART_CONTEXT
+  """The quantity must be a positive integer."""
+  INVALID_QUANTITY
+  """The cart was not found."""
+  CART_NOT_FOUND
+  """The provided variant ID is not a valid Variant Node ID."""
+  INVALID_VARIANT_ID
+  """The provided seller ID is not a valid Seller Node ID."""
+  INVALID_SELLER_ID
+}
+
+"""Error codes for cart item remove operations."""
+enum CartItemRemoveErrorCode {
+  """No cart context was provided (x-order-form-id header/cookie)."""
+  MISSING_CART_CONTEXT
+  """The specified variant was not found in the cart."""
+  ITEM_NOT_FOUND
+  """The cart was not found."""
+  CART_NOT_FOUND
+  """The provided variant ID is not a valid Variant Node ID."""
+  INVALID_VARIANT_ID
+}
+
+"""Error codes for cart items batch remove operations."""
+enum CartItemsRemoveErrorCode {
+  """No cart context was provided (x-order-form-id header/cookie)."""
+  MISSING_CART_CONTEXT
+  """None of the specified variants were found in the cart."""
+  ITEM_NOT_FOUND
+  """The cart was not found."""
+  CART_NOT_FOUND
+  """A provided variant ID is not a valid Variant Node ID."""
+  INVALID_VARIANT_ID
+  """The input contained no variant IDs."""
+  NO_VARIANT_IDS_PROVIDED
+  """The upstream checkout API returned an unusable response."""
+  UPSTREAM_ERROR
+}
+
+"""Error codes for cart item quantity increase operations."""
+enum CartItemQuantityIncreaseErrorCode {
+  """No cart context was provided (x-order-form-id header/cookie)."""
+  MISSING_CART_CONTEXT
+  """The quantity must be a positive integer."""
+  INVALID_QUANTITY
+  """The specified variant was not found in the cart."""
+  ITEM_NOT_FOUND
+  """The cart was not found."""
+  CART_NOT_FOUND
+  """The provided variant ID is not a valid Variant Node ID."""
+  INVALID_VARIANT_ID
+}
+
+"""Error codes for cart item quantity decrease operations."""
+enum CartItemQuantityDecreaseErrorCode {
+  """No cart context was provided (x-order-form-id header/cookie)."""
+  MISSING_CART_CONTEXT
+  """The quantity must be a positive integer."""
+  INVALID_QUANTITY
+  """The specified variant was not found in the cart."""
+  ITEM_NOT_FOUND
+  """The cart was not found."""
+  CART_NOT_FOUND
+  """The provided variant ID is not a valid Variant Node ID."""
+  INVALID_VARIANT_ID
+}
+
+"""A domain error returned from a cart item add mutation."""
+type CartItemAddError {
+  """Machine-readable error code."""
+  code: CartItemAddErrorCode!
+  """Human-readable error message."""
+  message: String!
+}
+
+"""A domain error returned from a cart item remove mutation."""
+type CartItemRemoveError {
+  """Machine-readable error code."""
+  code: CartItemRemoveErrorCode!
+  """Human-readable error message."""
+  message: String!
+}
+
+"""A domain error returned from a cart items batch remove mutation."""
+type CartItemsRemoveError {
+  """Machine-readable error code."""
+  code: CartItemsRemoveErrorCode!
+  """Human-readable error message."""
+  message: String!
+}
+
+"""A domain error returned from a cart item quantity increase mutation."""
+type CartItemQuantityIncreaseError {
+  """Machine-readable error code."""
+  code: CartItemQuantityIncreaseErrorCode!
+  """Human-readable error message."""
+  message: String!
+}
+
+"""A domain error returned from a cart item quantity decrease mutation."""
+type CartItemQuantityDecreaseError {
+  """Machine-readable error code."""
+  code: CartItemQuantityDecreaseErrorCode!
+  """Human-readable error message."""
+  message: String!
+}
+
+"""Payload returned by the cartItemAdd mutation."""
+type CartItemAddPayload {
+  """The updated cart, or null if errors occurred."""
+  cart: Cart
+  """Domain errors that occurred during the operation."""
+  userErrors: [CartItemAddError!]!
+}
+
+"""Payload returned by the cartItemRemove mutation."""
+type CartItemRemovePayload {
+  """The updated cart, or null if errors occurred."""
+  cart: Cart
+  """Domain errors that occurred during the operation."""
+  userErrors: [CartItemRemoveError!]!
+}
+
+"""Payload returned by the cartItemsRemove mutation."""
+type CartItemsRemovePayload {
+  """The updated cart, or null if errors occurred."""
+  cart: Cart
+  """Domain errors that occurred during the operation."""
+  userErrors: [CartItemsRemoveError!]!
+}
+
+"""Payload returned by the cartItemQuantityIncrease mutation."""
+type CartItemQuantityIncreasePayload {
+  """The updated cart, or null if errors occurred."""
+  cart: Cart
+  """Domain errors that occurred during the operation."""
+  userErrors: [CartItemQuantityIncreaseError!]!
+}
+
+"""Payload returned by the cartItemQuantityDecrease mutation."""
+type CartItemQuantityDecreasePayload {
+  """The updated cart, or null if errors occurred."""
+  cart: Cart
+  """Domain errors that occurred during the operation."""
+  userErrors: [CartItemQuantityDecreaseError!]!
+}
+
+"""Error codes for cart coupon apply operations."""
+enum CartCouponApplyErrorCode {
+  """No cart context was provided (x-order-form-id header/cookie)."""
+  MISSING_CART_CONTEXT
+  """The cart was not found."""
+  CART_NOT_FOUND
+  """The coupon code is empty, unknown, or not accepted by this cart."""
+  COUPON_NOT_FOUND
+  """The coupon code has expired."""
+  COUPON_EXPIRED
+}
+
+"""Error codes for cart coupon remove operations."""
+enum CartCouponRemoveErrorCode {
+  """No cart context was provided (x-order-form-id header/cookie)."""
+  MISSING_CART_CONTEXT
+  """The cart was not found."""
+  CART_NOT_FOUND
+  """
+  A surviving coupon was rejected by the cart after the removal (unknown or not accepted).
+  """
+  COUPON_NOT_FOUND
+  """A surviving coupon has expired."""
+  COUPON_EXPIRED
+}
+
+"""A domain error returned from a cart coupon apply mutation."""
+type CartCouponApplyError {
+  """Machine-readable error code."""
+  code: CartCouponApplyErrorCode!
+  """Human-readable error message."""
+  message: String!
+}
+
+"""A domain error returned from a cart coupon remove mutation."""
+type CartCouponRemoveError {
+  """Machine-readable error code."""
+  code: CartCouponRemoveErrorCode!
+  """Human-readable error message."""
+  message: String!
+}
+
+"""Payload returned by the cartCouponApply mutation."""
+type CartCouponApplyPayload {
+  """The updated cart, or null if errors occurred."""
+  cart: Cart
+  """Domain errors that occurred during the operation."""
+  userErrors: [CartCouponApplyError!]!
+}
+
+"""Payload returned by the cartCouponRemove mutation."""
+type CartCouponRemovePayload {
+  """The updated cart, or null if errors occurred."""
+  cart: Cart
+  """Domain errors that occurred during the operation."""
+  userErrors: [CartCouponRemoveError!]!
+}
+
+"""Error codes for cart validation operations."""
+enum CartValidateErrorCode {
+  """No cart context was provided (x-order-form-id header/cookie)."""
+  MISSING_CART_CONTEXT
+  """The cart was not found."""
+  CART_NOT_FOUND
+  """
+  The upstream checkout API could not be reached or returned an unusable response.
+  """
+  UPSTREAM_ERROR
+}
+
+"""A domain error returned from a cart validate mutation."""
+type CartValidateError {
+  """Machine-readable error code."""
+  code: CartValidateErrorCode!
+  """Human-readable error message."""
+  message: String!
+}
+
+"""Payload returned by the cartValidate mutation."""
+type CartValidatePayload {
+  """The re-checked cart, or null if errors occurred."""
+  cart: Cart
+  """Domain errors that occurred during the operation."""
+  userErrors: [CartValidateError!]!
+}
+
+"""The delivery channel for a shipping option."""
+enum DeliveryChannel {
+  """Home delivery."""
+  DELIVERY
+  """Pickup in store or pickup point."""
+  PICKUP
+  """Unrecognised delivery channel returned by the fulfillment provider."""
+  UNKNOWN
+}
+
+"""The unit of a shipping time estimate."""
+enum ShippingEstimateUnit {
+  """Calendar days (e.g. "7d")."""
+  DAYS
+  """Business days, excluding weekends and holidays (e.g. "5bd")."""
+  BUSINESS_DAYS
+  """Hours (e.g. "7h")."""
+  HOURS
+  """Minutes (e.g. "119m")."""
+  MINUTES
+}
+
+"""
+Parsed shipping time estimate (e.g. "5bd" → { value: 5, unit: BUSINESS_DAYS }).
+"""
+type ShippingEstimate {
+  """Numeric quantity of the estimate."""
+  value: Int!
+  """Time unit for the estimate."""
+  unit: ShippingEstimateUnit!
+}
+
+"""
+A shipping option as it applies to one specific cart item — carries that
+item's own price for the option, distinct from the cart-wide ShippingOption.
+"""
+type ItemShippingOption {
+  """
+  Opaque delivery option identifier, encoded to distinguish per-item options
+  from cart-wide options so the Apollo cache never conflates them.
+  """
+  id: ID!
+  """
+  Human-readable option name (e.g. "Standard Delivery"). Derived from a Checkout simulation, which
+  sends no `Accept-Language` and keys its SKU cache without a locale, so this text is NOT localized:
+  it may read in the account's default culture on a non-default binding.
+  """
+  name: String!
+  """Delivery channel: home delivery or pickup."""
+  channel: DeliveryChannel!
+  """Estimated shipping time."""
+  shippingEstimate: ShippingEstimate!
+  """Shipping cost for this item. Zero when free shipping applies."""
+  price: Money!
+  """Shipping list price for this item before any promotions."""
+  listPrice: Money!
+}
+
+"""A shipping option available for a given item and destination."""
+type ShippingOption {
+  """Opaque delivery option identifier."""
+  id: ID!
+  """
+  Human-readable option name (e.g. "Standard Delivery"). Derived from a Checkout simulation, which
+  sends no `Accept-Language` and keys its SKU cache without a locale, so this text is NOT localized:
+  it may read in the account's default culture on a non-default binding.
+  """
+  name: String!
+  """Delivery channel: home delivery or pickup."""
+  channel: DeliveryChannel!
+  """Estimated shipping time."""
+  shippingEstimate: ShippingEstimate!
+  """Shipping cost. Zero when free shipping applies."""
+  price: Money!
+  """Shipping list price before any promotions."""
+  listPrice: Money!
+  """Cart items for which this option is currently available."""
+  items: [CartItem!]!
+}
+
+"""Error codes for shipping simulation operations."""
+enum ShippingSimulateErrorCode {
+  """The postal code was not found or rejected by the fulfillment provider."""
+  INVALID_POSTAL_CODE
+  """The provided variant ID is not a valid Variant Node ID."""
+  INVALID_VARIANT_ID
+  """The provided seller ID is not a valid Seller Node ID."""
+  INVALID_SELLER_ID
+  """
+  No active cart in context: the cartShippingSimulation query requires an x-order-form-id and never mints a cart.
+  """
+  MISSING_CART_CONTEXT
+}
+
+"""A domain error returned from the shippingSimulation query."""
+type ShippingSimulateError {
+  """Machine-readable error code."""
+  code: ShippingSimulateErrorCode!
+  """Human-readable error message."""
+  message: String!
+}
+
+"""Payload returned by the shippingSimulation query."""
+type ShippingSimulationPayload {
+  """
+  Available shipping options for the given item and destination.
+  Null when userErrors is non-empty.
+  """
+  shippingOptions: [ShippingOption!]
+  """Domain errors that occurred during the operation."""
+  userErrors: [ShippingSimulateError!]!
+}
+
+"""Input for simulating shipping options for a single variant on a PDP."""
+input ShippingSimulateInput {
+  """Postal code of the delivery destination."""
+  postalCode: String!
+  """ISO 3166-1 alpha-3 country code (e.g. "BRA")."""
+  country: String!
+  """The variant's global Node ID to simulate shipping for."""
+  variantId: ID!
+  """Quantity of the variant. Must be at least 1."""
+  quantity: Int!
+  """The seller's global Node ID responsible for the variant."""
+  seller: ID!
+}
+
+"""
+Input for simulating shipping for the whole active cart. Carries the
+destination only; items are sourced from the cart in the x-order-form-id
+context, so there is no variant, quantity, or seller.
+"""
+input CartShippingSimulateInput {
+  """Postal code of the delivery destination."""
+  postalCode: String!
+  """ISO 3166-1 alpha-3 country code (e.g. "BRA")."""
+  country: String!
+}
+
+"""Payload returned by the cartShippingSimulation query."""
+type CartShippingSimulationPayload {
+  """
+  Shipping options available for every item in the cart, prices summed across
+  items. Empty when the cart is empty or no option is common to all items.
+  Null when userErrors is non-empty.
+  """
+  shippingOptions: [ShippingOption!]
+  """Domain errors that occurred during the operation."""
+  userErrors: [ShippingSimulateError!]!
+}
+
+"""
+The shopper's profile, projected from the order form's clientProfileData.
+A sibling of Cart, not nested under it. Individual (B2C) only.
+"""
+type ClientProfile implements Node @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """
+  Globally unique identifier (Relay Node ID), encoded from the order form ID.
+  """
+  id: ID!
+  """
+  Contact email as recorded on the order form. Null when no profile is set.
+  """
+  email: String
+  """Given name. Null when unset."""
+  firstName: String
+  """Family name. Null when unset."""
+  lastName: String
+  """Contact phone in the order form's stored format. Null when unset."""
+  phone: String
+  """Tax document (CPF for Individual shoppers). Null when unset."""
+  document: String
+}
+
+"""
+The shopper's preference opt-ins, projected from the order form's
+clientPreferencesData. A sibling of Cart, not nested under it.
+"""
+type ClientPreferences implements Node @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """
+  Globally unique identifier (Relay Node ID), encoded from the order form ID.
+  """
+  id: ID!
+  """Newsletter opt-in. Null when the shopper has not chosen."""
+  optinNewsLetter: Boolean
+  """Save-personal-data opt-in. Null when the shopper has not chosen."""
+  savePersonalData: Boolean
+}
+
+"""
+Partial profile update. Provide only the fields to write; omitted fields are
+left unchanged.
+"""
+input ClientProfileUpdateInput {
+  """Contact email to write. Omit to leave unchanged."""
+  email: String
+  """Given name to write. Omit to leave unchanged."""
+  firstName: String
+  """Family name to write. Omit to leave unchanged."""
+  lastName: String
+  """Contact phone to write. Omit to leave unchanged."""
+  phone: String
+  """Tax document to write. Omit to leave unchanged."""
+  document: String
+}
+
+"""
+Partial preferences update. Provide only the flags to write; omitted flags are
+left unchanged.
+"""
+input ClientPreferencesUpdateInput {
+  """Newsletter opt-in to write. Omit to leave unchanged."""
+  optinNewsLetter: Boolean
+  """Save-personal-data opt-in to write. Omit to leave unchanged."""
+  savePersonalData: Boolean
+}
+
+"""Error codes for client profile update operations."""
+enum ClientProfileUpdateErrorCode {
+  """No cart context was provided (x-order-form-id header/cookie)."""
+  MISSING_CART_CONTEXT
+  """The cart was not found."""
+  CART_NOT_FOUND
+  """The input contained no profile fields to write."""
+  NO_PROFILE_FIELD_PROVIDED
+}
+
+"""Error codes for client preferences update operations."""
+enum ClientPreferencesUpdateErrorCode {
+  """No cart context was provided (x-order-form-id header/cookie)."""
+  MISSING_CART_CONTEXT
+  """The cart was not found."""
+  CART_NOT_FOUND
+  """The input contained no preferences to write."""
+  NO_PREFERENCE_PROVIDED
+}
+
+"""A domain error returned from a client profile update mutation."""
+type ClientProfileUpdateError {
+  """Machine-readable error code."""
+  code: ClientProfileUpdateErrorCode!
+  """Human-readable error message."""
+  message: String!
+}
+
+"""A domain error returned from a client preferences update mutation."""
+type ClientPreferencesUpdateError {
+  """Machine-readable error code."""
+  code: ClientPreferencesUpdateErrorCode!
+  """Human-readable error message."""
+  message: String!
+}
+
+"""Payload returned by the clientProfileUpdate mutation."""
+type ClientProfileUpdatePayload {
+  """The updated profile, or null if a context/validation error occurred."""
+  clientProfile: ClientProfile
+  """
+  The session after the write, reflecting the now-current isIdentified derived from
+  clientProfileData.email. Null alongside clientProfile on a context/validation error.
+  """
+  session: Session
+  """Domain errors that occurred during the operation."""
+  userErrors: [ClientProfileUpdateError!]!
+}
+
+"""Payload returned by the clientPreferencesUpdate mutation."""
+type ClientPreferencesUpdatePayload {
+  """
+  The updated preferences, or null if a context/validation error occurred.
+  """
+  clientPreferences: ClientPreferences
+  """Domain errors that occurred during the operation."""
+  userErrors: [ClientPreferencesUpdateError!]!
+}
+
+"""
+The delivery address, saved addresses, and shipping options for the cart.
+A read-only sibling of Cart, projected from the same order form fetch.
+Null fields project explicitly (never undefined), allowing partial queries.
+"""
+type Shipping implements Node @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """
+  Globally unique identifier (Relay Node ID), encoded from the order form ID.
+  """
+  id: ID!
+  """The delivery address on the cart. Null until the shopper provides one."""
+  address: Address
+  """The logged-in shopper's saved addresses. Empty for anonymous shoppers."""
+  savedAddresses: [Address!]!
+  """
+  Delivery-channel shipping options common to all cart items for the current address, prices summed.
+  """
+  options: [ShippingOption!]!
+  """
+  The selected option, when one selection applies to the whole cart. Null when items disagree or the persisted selection is a pickup-channel SLA.
+  """
+  selectedOptionId: ID
+}
+
+"""A delivery address or saved-address reference."""
+type Address {
+  """Saved-address reference. Null for addresses entered in this session."""
+  id: ID
+  """Recipient name for this address."""
+  recipientName: String
+  """
+  Postal code. Required when persisting an address via the mutation inputs, but nullable here:
+  pickup/search/disposable addresses and legacy saved addresses can come back without one.
+  """
+  postalCode: String
+  """
+  ISO 3166-1 alpha-3 country code. Required when persisting an address via the mutation inputs,
+  but nullable here for the same reason as postalCode.
+  """
+  country: String
+  """Street name."""
+  street: String
+  """Street number."""
+  number: String
+  """Additional address detail (apartment, suite, etc.)."""
+  complement: String
+  """Neighborhood / district."""
+  neighborhood: String
+  """City name."""
+  city: String
+  """State / province code."""
+  state: String
+}
+
+"""
+The shopper's session and authentication state for the active order form.
+A read-only sibling of Cart, projected from the same order form fetch. Carries
+no profile data — profile fields live on ClientProfile.
+"""
+type Session implements Node @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """
+  Globally unique identifier (Relay Node ID), encoded from the order form ID.
+  """
+  id: ID!
+  """
+  Whether the shopper holds an authenticated VTEX session. A guest is `false` — a normal state, never an error.
+  """
+  loggedIn: Boolean!
+  """
+  Whether the shopper may edit their identity data. Lets Controls render editable vs. identified-but-masked fields.
+  """
+  canEditData: Boolean!
+  """
+  Server-computed: whether a profile is attached to the order form (clientProfileData.email is present and non-empty). Identification is distinct from authentication.
+  """
+  isIdentified: Boolean!
+}
+
+"""Input for updating the delivery address on the cart."""
+input ShippingAddressUpdateInput {
+  """
+  Saved address reference. Present when the shopper picked (and possibly edited) a saved address.
+  """
+  savedAddressId: ID
+  """Recipient name for the delivery address."""
+  recipientName: String!
+  """Postal code for the delivery address."""
+  postalCode: String!
+  """ISO 3166-1 alpha-3 country code (e.g. "BRA")."""
+  country: String!
+  """Street name."""
+  street: String
+  """Street number."""
+  number: String
+  """Additional address detail (apartment, suite, etc.)."""
+  complement: String
+  """Neighborhood / district."""
+  neighborhood: String
+  """City name."""
+  city: String
+  """State / province code."""
+  state: String
+}
+
+"""Error codes for shipping address update operations."""
+enum ShippingAddressUpdateErrorCode {
+  """No cart context was provided (x-order-form-id header/cookie)."""
+  MISSING_CART_CONTEXT
+  """The cart was not found."""
+  CART_NOT_FOUND
+  """The recipient name is blank."""
+  MISSING_RECIPIENT_NAME
+  """The provided saved address ID does not match any available addresses."""
+  INVALID_SAVED_ADDRESS_ID
+  """The postal code is invalid or not found."""
+  INVALID_POSTAL_CODE
+  """The address is invalid."""
+  INVALID_ADDRESS
+}
+
+"""A domain error returned from a shipping address update mutation."""
+type ShippingAddressUpdateError {
+  """Machine-readable error code."""
+  code: ShippingAddressUpdateErrorCode!
+  """Human-readable error message."""
+  message: String!
+}
+
+"""Payload returned by the shippingAddressUpdate mutation."""
+type ShippingAddressUpdatePayload {
+  """The updated shipping state, or null if errors occurred."""
+  shipping: Shipping
+  """The updated cart, or null if errors occurred."""
+  cart: Cart
+  """Domain errors that occurred during the operation."""
+  userErrors: [ShippingAddressUpdateError!]!
+}
+
+"""Input for selecting a shipping option for the whole cart."""
+input ShippingOptionSelectInput {
+  """
+  The shipping option ID to select. Must be available for all items in the cart.
+  """
+  optionId: ID!
+}
+
+"""Error codes for shipping option select operations."""
+enum ShippingOptionSelectErrorCode {
+  """No cart context was provided (x-order-form-id header/cookie)."""
+  MISSING_CART_CONTEXT
+  """The cart was not found."""
+  CART_NOT_FOUND
+  """The option is not available for all items in the cart."""
+  OPTION_UNAVAILABLE
+  """No delivery address is persisted on the cart."""
+  MISSING_SHIPPING_ADDRESS
+}
+
+"""A domain error returned from a shipping option select mutation."""
+type ShippingOptionSelectError {
+  """Machine-readable error code."""
+  code: ShippingOptionSelectErrorCode!
+  """Human-readable error message."""
+  message: String!
+}
+
+"""Payload returned by the shippingOptionSelect mutation."""
+type ShippingOptionSelectPayload {
+  """The updated shipping state, or null if errors occurred."""
+  shipping: Shipping
+  """The updated cart, or null if errors occurred."""
+  cart: Cart
+  """Domain errors that occurred during the operation."""
+  userErrors: [ShippingOptionSelectError!]!
+}
+
+"""
+The authentication methods an account enables, read before rendering a sign-in form.
+"""
+type SessionAuthProviders {
+  """Whether classic email and password sign-in is enabled."""
+  passwordAuthentication: Boolean!
+  """Whether email access-code (passwordless) sign-in is enabled."""
+  accessKeyAuthentication: Boolean!
+}
+
+"""
+A typed, expected failure of a login attempt. Distinct from the top-level
+UNAUTHORIZED gate: this is a domain outcome (the request was understood, the
+business rejected it), never an infrastructure failure.
+"""
+type SessionError {
+  """Machine-readable error code for the login-attempt failure."""
+  code: SessionErrorCode!
+  """Human-readable message describing the failure."""
+  message: String!
+}
+
+"""The set of login-attempt failure codes a session mutation can return."""
+enum SessionErrorCode {
+  """Email or password was not accepted by VTEX ID."""
+  INVALID_CREDENTIALS
+  """The access code was wrong or expired."""
+  INVALID_ACCESS_CODE
+  """Too many access codes were requested for this email."""
+  ACCESS_CODE_SEND_LIMIT
+  """The user is blocked by VTEX ID."""
+  BLOCKED
+  """
+  BFF-side guard: the request lacked the auth context it needed (e.g. a missing
+  authenticationToken). Not a VTEX outcome.
+  """
+  MISSING_AUTH_CONTEXT
+}
+
+"""
+The login / logout result, projected from the one refreshed order form. session,
+cart, clientProfile and clientPreferences are normalized Relay Nodes (keyed on
+the orderFormId) so Apollo merges them into the cache and the client updates
+reactively with no refetch.
+"""
+type SessionLoginPayload {
+  """The session after the attempt; loggedIn is true only on success."""
+  session: Session!
+  """The cart projected from the refreshed order form."""
+  cart: Cart!
+  """
+  The client profile projected from the refreshed order form; the entity always
+  resolves, its fields are null when unset.
+  """
+  clientProfile: ClientProfile!
+  """
+  The client preferences projected from the refreshed order form; the entity
+  always resolves, its fields are null when unset.
+  """
+  clientPreferences: ClientPreferences!
+  """Typed login-attempt failures. Empty on success."""
+  userErrors: [SessionError!]!
+}
+
+"""The result of requesting an email access code."""
+type SessionRequestAccessCodePayload {
+  """
+  Opaque token to hand back to sessionValidateAccessCode. Null when the request
+  failed.
+  """
+  authenticationToken: String
+  """Typed request failures. Empty on success."""
+  userErrors: [SessionError!]!
+}
+
+"""Credentials for a classic email + password sign-in."""
+input SessionPasswordLoginInput {
+  """The shopper's email address."""
+  email: String!
+  """
+  The shopper's password. Proxied to VTEX ID over TLS, never logged or persisted.
+  """
+  password: String!
+}
+
+"""The email to send an access code to."""
+input SessionRequestAccessCodeInput {
+  """The shopper's email address the access code is sent to."""
+  email: String!
+}
+
+"""An access code plus the authenticationToken it was issued against."""
+input SessionValidateAccessCodeInput {
+  """The shopper's email address."""
+  email: String!
+  """The access code the shopper received by email."""
+  accessCode: String!
+  """
+  The opaque token returned by sessionRequestAccessCode, handed back unchanged.
+  """
+  authenticationToken: String!
+}
+
+"""
+The shopper's active region. Both fields are nullable: a shopper who has never
+submitted a postal code has no region, and a submitted postal code does not
+always resolve to a known city.
+"""
+type Region @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """
+  Stable identity for cache normalization. Not a Relay Node ID: a region is
+  session-scoped shopper state, never addressable by global id.
+  """
+  id: ID!
+  """The active postal code, formatted for display. Null when none is set."""
+  postalCode: String
+  """
+  The city the postal code resolves to. Null when the postal code is unknown to
+  the resolver, which is a normal state and not an error.
+  """
+  city: String
+}
+
+"""
+Why a region write was refused. Stable across locales, so a client can render
+each case in the shopper's language instead of echoing the server's message.
+"""
+enum RegionErrorCode {
+  """The value did not normalize to a complete postal code."""
+  INVALID_POSTAL_CODE
+  """The postal code is complete but falls outside the served ranges."""
+  UNSERVED_POSTAL_CODE
+}
+
+"""
+A typed, expected failure of a region write: the request was understood and the
+business rejected it. Distinct from an infrastructure failure, which surfaces as
+a top-level GraphQL error.
+"""
+type RegionError {
+  """Which rule refused the postal code."""
+  code: RegionErrorCode!
+  """
+  Human-readable message describing why the postal code was rejected. Written in
+  English by the server; a client should key its copy on `code` instead.
+  """
+  message: String!
+}
+
+"""The result of submitting a postal code."""
+type RegionUpdatePayload {
+  """
+  The region after the write. Null when the postal code was rejected, leaving
+  any previously active region untouched.
+  """
+  region: Region
+  """Typed rejections. Empty on success."""
+  errors: [RegionError!]!
+}
+
+"""
+A shopper's persistent, cart-independent profile. Distinct from checkout's
+order-form-scoped ClientProfile.
+"""
+type CustomerProfile @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """
+  Stable identity for cache normalization. Not a Relay Node ID: the profile is
+  session-scoped shopper state, derived from the session and never addressable
+  by a global id (no id argument, no Query.node entry — IDOR-safe).
+  """
+  id: ID!
+  """Given name. Null when unset."""
+  firstName: String
+  """Family name. Null when unset."""
+  lastName: String
+  """
+  The shopper's login identifier. Read-only — excluded from the update input by construction.
+  """
+  email: String
+  """Primary contact phone. Null when unset."""
+  homePhone: String
+  """Mobile contact phone. Null when unset."""
+  mobilePhone: String
+  """National tax ID. Null when unset."""
+  document: String
+  """
+  The tax ID's type, so the control can adapt to the shopper's region. Null when unset.
+  """
+  documentType: String
+  """Date of birth. Null when unset."""
+  birthDate: String
+  """
+  Free-form gender value; the store configures the options it offers. Null when unset.
+  """
+  gender: String
+}
+
+"""A typed, expected failure of a profile write."""
+type CustomerProfileError {
+  """Machine-readable code for the write failure."""
+  code: CustomerProfileErrorCode!
+  """A safe message. Never echoes a submitted profile value."""
+  message: String!
+}
+
+"""The set of expected, typed profile-write failure codes."""
+enum CustomerProfileErrorCode {
+  """
+  The account's profile schema refused one or more submitted values. It does not
+  attribute the refusal to a cause — a required field left empty and a malformed
+  value are not distinguishable until the upstream rejection body is
+  characterised, at which point a narrower code joins this one.
+  """
+  INVALID_VALUE
+}
+
+"""
+Every field is optional: provide only what the shopper edited. An empty string
+is an explicit erase; an omitted field is left untouched. A `null` is neither —
+it counts as not provided, so nulling an untouched field cannot wipe it.
+"""
+input CustomerProfileUpdateInput {
+  """Given name to write. Omit to leave unchanged; empty string to erase."""
+  firstName: String
+  """Family name to write. Omit to leave unchanged; empty string to erase."""
+  lastName: String
+  """
+  Primary contact phone to write. Omit to leave unchanged; empty string to erase.
+  """
+  homePhone: String
+  """
+  Mobile contact phone to write. Omit to leave unchanged; empty string to erase.
+  """
+  mobilePhone: String
+  """
+  National tax ID to write. Omit to leave unchanged; empty string to erase.
+  """
+  document: String
+  """Tax ID type to write. Omit to leave unchanged; empty string to erase."""
+  documentType: String
+  """
+  Date of birth to write. Omit to leave unchanged; empty string to erase.
+  """
+  birthDate: String
+  """Gender value to write. Omit to leave unchanged; empty string to erase."""
+  gender: String
+}
+
+"""
+The result of a profile write, carrying the merged profile and any typed
+failures.
+"""
+type CustomerProfileUpdatePayload {
+  """
+  The profile after the write, so a reactive fragment re-delivers without a refetch.
+  """
+  customerProfile: CustomerProfile!
+  """Typed, expected write failures. Empty on success."""
+  userErrors: [CustomerProfileError!]!
+}