@vtex/faststore 0.0.5 → 0.0.7

package/dist/schema.graphql

@@ -241,6 +241,14 @@ extend type Query {
     """Maximum number of recommendations."""
     first: Int = 10
   ): [Product!]!
+  """
+  Resolves a catalog route by ID or by path and returns its confirmed localized equivalents.
+  Null when the route does not exist or the catalog could not be reached.
+  """
+  catalogRoute(
+    """The route to resolve, by ID or by path."""
+    input: CatalogRouteInput!
+  ): CatalogRoute
   """Look up a single category by global ID."""
   category(
     """Global category ID."""
@@ -373,6 +381,28 @@ extend type Query {
   session: Session!
 }
 
+extend type Query {
+  """
+  The cart's payment state: methods, selection, installment options, and saved cards. Projected from the same order form as Query.cart. Always resolves; lists are empty and selection fields are null when payment is unset.
+  """
+  payment: Payment!
+}
+
+extend type Query {
+  """
+  A settled order's payment recap, keyed on the order group
+  paymentStartTransaction / paymentGatewayCallback return. Null when the
+  order group does not resolve to a settled order — never a fabricated empty
+  projection (contrast Query.payment, which always resolves).
+  """
+  order(
+    """
+    The order group returned by paymentStartTransaction / paymentGatewayCallback.
+    """
+    orderGroup: String!
+  ): Order
+}
+
 extend type Query {
   """Which authentication methods this account enables."""
   sessionAuthProviders: SessionAuthProviders!
@@ -389,11 +419,14 @@ extend type Query {
 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.
+  comes from the session. Nullable because it is permission-gated (ADR-00005).
+  Null with no error when the session names no shopper. Null with an
+  UNAUTHORIZED, UPSTREAM_ERROR, UPSTREAM_TIMEOUT or CIRCUIT_OPEN error on this
+  field's path when the read fails (ADR-00007), so the rest of the operation
+  still resolves. A profile whose fields are null when the shopper has saved
+  nothing yet.
   """
-  customerProfile: CustomerProfile!
+  customerProfile: CustomerProfile
 }
 
 """
@@ -507,6 +540,41 @@ extend type Mutation {
   ): ShippingOptionSelectPayload!
 }
 
+extend type Mutation {
+  """
+  Select a payment method, optionally identifying a new card's BIN or a saved card's account.
+  """
+  paymentMethodSelect(
+    """Method (and optional BIN/saved-card) to select."""
+    input: PaymentMethodSelectInput!
+  ): PaymentMethodSelectPayload!
+  """
+  Select an installment count for the currently-selected method. Recomputes the cart total.
+  """
+  paymentInstallmentSelect(
+    """Installment count to select."""
+    input: PaymentInstallmentSelectInput!
+  ): PaymentInstallmentSelectPayload!
+  """Set the billing address, or fall back to the delivery address."""
+  paymentBillingAddressUpdate(
+    """
+    Billing address details, or sameAsDelivery: true to use the delivery address.
+    """
+    input: PaymentBillingAddressUpdateInput!
+  ): PaymentBillingAddressUpdatePayload!
+  """
+  Open a VTEX transaction from the currently-selected payment. No input: every field is server-derived.
+  """
+  paymentStartTransaction: PaymentStartTransactionPayload!
+  """
+  Finalize a transaction after the direct-to-gateway payment call succeeded.
+  """
+  paymentGatewayCallback(
+    """The order group to finalize."""
+    input: PaymentGatewayCallbackInput!
+  ): PaymentGatewayCallbackPayload!
+}
+
 extend type Mutation {
   """
   Sign in with email and password. Returns the refreshed session, or typed
@@ -766,6 +834,10 @@ type Variant implements Node {
   name: String!
   """Stock Keeping Unit code. Unique merchant-side identifier."""
   sku: String!
+  """
+  PDP path segment in the active locale for this SKU, "{linkId}-{skuId}".
+  """
+  routeSlug: String!
   """International Article Number (barcode). Maps to VTEX SKU EAN."""
   ean: String
   """Merchant reference code."""
@@ -839,6 +911,11 @@ type Product implements Node @cacheControl(maxAge: 60, scope: PUBLIC) {
   title: String!
   """URL-friendly handle / slug. Maps to VTEX `LinkId`."""
   slug: String!
+  """
+  PDP path segment in the active locale, "{linkId}-{skuId}" with the representative SKU (in stock first, then lowest
+  spot price, then the first SKU). Build product URLs from this, not from `slug`.
+  """
+  routeSlug: String!
   """Full marketing description."""
   description: String
   """Description rendered as HTML."""
@@ -1503,6 +1580,62 @@ type TrendingSearch {
   count: Int!
 }
 
+"""Identifies a catalog route. Set exactly one member."""
+input CatalogRouteInput {
+  """
+  Relay node ID of the entity behind the route. Only Product IDs are accepted.
+  """
+  id: ID
+  """
+  Logical store route, without the binding's origin or base path
+  (e.g. "/apparel/t-shirts", "/shirt-51/p").
+  """
+  path: String
+}
+
+"""Kind of entity a catalog route resolves to."""
+enum CatalogRouteKind {
+  """A product detail page."""
+  PRODUCT
+  """A category or subcategory page."""
+  CATEGORY
+  """A brand page."""
+  BRAND
+  """A collection page."""
+  COLLECTION
+}
+
+"""
+A catalog route and its confirmed equivalents in every locale the catalog registers.
+"""
+type CatalogRoute @cacheControl(maxAge: 300, scope: PUBLIC) {
+  """
+  Relay node ID of the entity. Stable across locales; the route's identity.
+  """
+  id: ID!
+  """Kind of entity behind the route."""
+  kind: CatalogRouteKind!
+  """
+  One entry per locale the catalog confirms for every segment of the route. Editorial fallback never adds an
+  entry. May include locales the store does not publish; intersect with the store's bindings.
+  """
+  variants: [CatalogRouteVariant!]!
+}
+
+"""A route's equivalent in one locale."""
+type CatalogRouteVariant {
+  """BCP 47 tag, canonicalized."""
+  locale: String!
+  """
+  Route segment(s) in that locale, lowercased, accents kept. Not percent-encoded.
+  """
+  slug: String!
+  """
+  Relative logical path ("/{slug}" or "/{slug}/p"). No origin, no base path, not percent-encoded.
+  """
+  path: String!
+}
+
 """
 A shopping cart representing items a customer intends to purchase.
 Maps to the VTEX orderForm entity.
@@ -1719,10 +1852,11 @@ type CartItem {
   """
   compositions: [CartItemComposition!]!
   """
-  This item's own available delivery options (not intersected across the cart).
-  Excludes pickup options; delivery channel only.
+  The cart-wide delivery options this item is eligible for: the same ShippingOption
+  entities Shipping.options lists, carrying the shared-pool price, not a per-item
+  quote. Excludes pickup options; delivery channel only.
   """
-  shippingOptions: [ItemShippingOption!]!
+  shippingOptions: [ShippingOption!]!
   """
   This item's own currently selected delivery option, or null when no selection
   is persisted or the persisted selection is a pickup option.
@@ -1745,7 +1879,7 @@ type CartItemCustomization {
 }
 
 """A single submitted customization field."""
-type CartItemCustomizationEntry {
+type CartItemCustomizationEntry @cacheControl(maxAge: 0, scope: PRIVATE) {
   """Field name as defined by the assembly (e.g. "Text")."""
   name: String!
   """Submitted value, stringified. File uploads carry the file URL."""
@@ -2272,8 +2406,9 @@ type ShippingEstimate {
 }
 
 """
-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.
+One cart item's current selection. Its price and estimate are Checkout's real values for
+this item; option carries the shared name and channel. All values are a live snapshot:
+another item joining or leaving the same SLA can change them.
 """
 type ItemShippingOption {
   """
@@ -2281,15 +2416,9 @@ type ItemShippingOption {
   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."""
+  """The cart-wide shipping option this selection belongs to."""
+  option: ShippingOption!
+  """Estimated shipping time for this item."""
   shippingEstimate: ShippingEstimate!
   """Shipping cost for this item. Zero when free shipping applies."""
   price: Money!
@@ -2297,6 +2426,28 @@ type ItemShippingOption {
   listPrice: Money!
 }
 
+"""
+A shipping option with at least one cart item currently selected on it. Its price and
+shippingEstimateList cover only those items, recomputed on every request.
+"""
+type SelectedShippingOption {
+  """The cart-wide shipping option these items selected."""
+  option: ShippingOption!
+  """
+  Cart items currently selected on this option (not every eligible item).
+  """
+  items: [CartItem!]!
+  """Sum of items[].selectedShippingOption.price."""
+  price: Money!
+  """Sum of items[].selectedShippingOption.listPrice."""
+  listPrice: Money!
+  """
+  items[].selectedShippingOption.shippingEstimate, one entry per item, unreduced and
+  uncompared.
+  """
+  shippingEstimateList: [ShippingEstimate!]!
+}
+
 """A shipping option available for a given item and destination."""
 type ShippingOption {
   """Opaque delivery option identifier."""
@@ -2309,11 +2460,21 @@ type ShippingOption {
   name: String!
   """Delivery channel: home delivery or pickup."""
   channel: DeliveryChannel!
-  """Estimated shipping time."""
-  shippingEstimate: ShippingEstimate!
-  """Shipping cost. Zero when free shipping applies."""
+  """
+  Estimated shipping time, sampled from one eligible item. Delivery estimates can genuinely vary
+  per item under the same option; use shippingEstimateList for every item's own value.
+  """
+  shippingEstimate: ShippingEstimate! @deprecated(reason: "Sampled from one item and can misrepresent the others. Use shippingEstimateList.")
+  """
+  Every eligible item's own shippingEstimate, one entry per item, unreduced and uncompared.
+  """
+  shippingEstimateList: [ShippingEstimate!]!
+  """
+  Shipping cost for every item this option covers. Zero when free shipping applies. A live
+  estimate of the shared per-SLA pool, not a guaranteed quote.
+  """
   price: Money!
-  """Shipping list price before any promotions."""
+  """Shipping list price before any promotions, summed like price."""
   listPrice: Money!
   """Cart items for which this option is currently available."""
   items: [CartItem!]!
@@ -2530,17 +2691,21 @@ type Shipping implements Node @cacheControl(maxAge: 0, scope: PRIVATE) {
   """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.
+  Delivery-channel shipping options any cart item is eligible for at the current address, prices summed across the eligible items.
   """
   options: [ShippingOption!]!
   """
+  Delivery-channel options with at least one item currently selected on them, one entry per option. Pickup selections are excluded.
+  """
+  selectedOptions: [SelectedShippingOption!]!
+  """
   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
+  selectedOptionId: ID @deprecated(reason: "Cannot express split shipping. Use Shipping.selectedOptions.")
 }
 
 """A delivery address or saved-address reference."""
-type Address {
+type Address @cacheControl(maxAge: 0, scope: PRIVATE) {
   """Saved-address reference. Null for addresses entered in this session."""
   id: ID
   """Recipient name for this address."""
@@ -2656,7 +2821,8 @@ type ShippingAddressUpdatePayload {
 """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.
+  The shipping option ID to select. Must be offered as a delivery option by at least one item in
+  the cart; items that don't offer it fall back to the Checkout API's own choice.
   """
   optionId: ID!
 }
@@ -2667,7 +2833,10 @@ enum ShippingOptionSelectErrorCode {
   MISSING_CART_CONTEXT
   """The cart was not found."""
   CART_NOT_FOUND
-  """The option is not available for all items in the cart."""
+  """
+  The option id is not offered as a delivery option by any item in the cart (unknown id or
+  pickup). Returned without calling Checkout. An option only some items offer is not an error.
+  """
   OPTION_UNAVAILABLE
   """No delivery address is persisted on the cart."""
   MISSING_SHIPPING_ADDRESS
@@ -2691,6 +2860,575 @@ type ShippingOptionSelectPayload {
   userErrors: [ShippingOptionSelectError!]!
 }
 
+"""
+The cart's payment state: available methods with server-driven validator config,
+the current selection, installment options, and the shopper's saved cards. A
+read-only sibling of Cart, Shipping, and Session, projected from the same order
+form fetch. Method-agnostic: projects whatever payment systems VTEX returns, not
+only credit card. Never carries a full card number or CVV.
+"""
+type Payment implements Node @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """
+  Globally unique identifier (Relay Node ID), encoded from the order form ID.
+  """
+  id: ID!
+  """
+  Payment methods available on this cart. Empty when none are configured.
+  """
+  methods: [PaymentMethod!]!
+  """
+  The currently selected method's id (PaymentMethod.id), or null when unselected.
+  """
+  selectedMethodId: String
+  """
+  Saved-card account reference for the current selection, when a saved card is selected. Null otherwise.
+  """
+  selectedAccountId: String
+  """
+  The currently selected installment tier, resolved from the selection against installmentOptions. Null when unselected or unresolved.
+  """
+  selectedInstallment: PaymentInstallment
+  """
+  Installment plans available, grouped by method (and BIN, for card methods). Serves both a new card (matched by BIN) and a saved card (matched by its stored method).
+  """
+  installmentOptions: [PaymentInstallmentOption!]!
+  """
+  The shopper's saved cards. Empty for anonymous shoppers or when none are saved.
+  """
+  savedCards: [SavedCard!]!
+  """
+  The BIN persisted on the current selection, or null when the selection carries
+  none (a non-card method, or a saved card selected without one). Echoes back what
+  paymentMethodSelect wrote, which is what a client needs in order to know whether
+  its own locally-detected BIN has actually reached the order form: installment
+  options are matched against THIS value server-side, never against a client draft.
+  Not sensitive — a BIN identifies an issuer range, never a card.
+  """
+  selectedBin: String
+}
+
+"""
+A payment method available on the cart, with the server-driven validator config
+that determines which card-form fields render, their masks, and whether they
+are required. A non-normalized value object (ADR-0012); read directly off
+Payment.methods.
+"""
+type PaymentMethod {
+  """Payment-system identifier (VTEX paymentSystem stringId)."""
+  id: String!
+  """
+  Display name (e.g. "Visa", "Mastercard", "Cash"). Doubles as the network name for card methods.
+  """
+  name: String!
+  """
+  Payment-system group (e.g. "creditCardPaymentGroup", "debitCardPaymentGroup"). Store-configured; kept as a string, not an enum.
+  """
+  groupName: String!
+  """
+  Whether VTEX flags this payment system as requiring cardholder authentication
+  (for example 3-D Secure). Projected verbatim from the order form's payment-system
+  configuration: it describes how the store configured the system, not a guarantee
+  about any particular transaction. Null when the order form carries no value for
+  this system — which is not the same as false. Detection only: this API implements
+  no authentication challenge.
+  """
+  requiresAuthentication: Boolean
+  """
+  Validator configuration driving field presence, masks, and requiredness.
+  """
+  validator: PaymentMethodValidator!
+}
+
+"""
+Per-method validator configuration. Server-driven so no component hardcodes
+field presence, masks, or requiredness.
+"""
+type PaymentMethodValidator {
+  """
+  Mask pattern for the card number input. Null when the method carries no mask.
+  """
+  numberMask: String
+  """
+  Regex for real-time network detection against the typed BIN. Null when unset.
+  """
+  numberRegex: String
+  """
+  Mask pattern for the security-code (CVV) input. Null when unused or unmasked.
+  """
+  cvvMask: String
+  """Regex validating the security-code (CVV) input. Null when unused."""
+  cvvRegex: String
+  """Whether this method requires the security code (CVV)."""
+  cvvRequired: Boolean!
+  """Whether this method requires an expiration date."""
+  expirationRequired: Boolean!
+  """Whether this method requires the cardholder name."""
+  holderNameRequired: Boolean!
+  """Whether this method requires a billing address."""
+  billingAddressRequired: Boolean!
+  """
+  Whether a cardholder document field is displayable for this method. Distinct from documentRequired.
+  """
+  documentDisplayable: Boolean!
+  """
+  Whether the displayed cardholder document is required. Distinct from documentDisplayable — a document can be shown without being mandatory.
+  """
+  documentRequired: Boolean!
+}
+
+"""
+One installment tier: a specific installment count at a given per-installment
+value and total. Keyed by count within its parent PaymentInstallmentOption — a
+non-normalized value object (ADR-0012).
+"""
+type PaymentInstallment {
+  """Number of installments (1 = single payment, no interest)."""
+  count: Int!
+  """Amount per installment."""
+  value: Money!
+  """Total amount across all installments, including any interest."""
+  total: Money!
+  """
+  Interest rate in hundredths of a percent, exactly as the VTEX order form carries it (100 = 1%; 0 = interest-free).
+  """
+  interestRate: Float!
+}
+
+"""
+Installment tiers available for one payment method (and, for card methods, one
+BIN range). A non-normalized value object (ADR-0012): read straight off
+Payment.installmentOptions.
+"""
+type PaymentInstallmentOption @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """The payment method this option applies to (PaymentMethod.id)."""
+  methodId: String!
+  """
+  The BIN range this option applies to, when method-and-BIN-specific. Null when the option applies by method alone.
+  """
+  bin: String
+  """Base order value this option was quoted against."""
+  baseValue: Money!
+  """
+  Installment tiers, with a guaranteed `count: 1` entry prepended when VTEX
+  omits one. A tier that upstream already supplies is passed through untouched
+  (including its position and interest rate).
+  """
+  installments: [PaymentInstallment!]!
+}
+
+"""
+One of the shopper's saved cards. Never carries a full card number or CVV. A
+normalized, id-bearing value object (ADR-0012): id is a stable opaque cache
+key, not a Relay Node.
+"""
+type SavedCard @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """
+  Opaque, stable cache key. Not a Relay Node ID; SavedCard is not registered in the cross-module Node registry.
+  """
+  id: ID!
+  """
+  The saved-card account reference. Pass this back on selection; never a full card number.
+  """
+  accountId: String!
+  """
+  The saved card's payment-system id (PaymentMethod.id), for cross-referencing validator config and installment options.
+  """
+  methodId: String!
+  """Card network / issuer display name (e.g. "Visa")."""
+  network: String!
+  """Last four digits of the card number."""
+  lastFourDigits: String!
+  """BIN of the saved card, for installment-option lookup by network."""
+  bin: String!
+  """Shopper-assigned custom label, when set."""
+  label: String
+  """
+  Whether the card is expired. Expired cards are still returned; non-selectable is a UI concern downstream.
+  """
+  expired: Boolean!
+  """
+  Whether completing payment with this card requires the shopper to enter the CVV.
+  """
+  cvvRequired: Boolean!
+}
+
+"""
+Input for selecting a payment method, optionally identifying a new card (by
+BIN) or a saved card (by account reference). A non-card method (e.g. Cash)
+omits both `bin` and `accountId`. When `accountId` is given, `bin` may also
+be given to match the saved card against a BIN-specific installment option;
+a `bin` that does not match the saved card's own BIN is rejected with
+MISMATCHED_BIN_FOR_SAVED_CARD.
+"""
+input PaymentMethodSelectInput {
+  """The method to select (PaymentMethod.id)."""
+  methodId: String!
+  """
+  A newly-entered card's BIN, once detected. Omit for a saved card or a non-card method.
+  """
+  bin: String
+  """
+  A saved card's account reference (SavedCard.accountId). Omit for a new card or a non-card method.
+  """
+  accountId: String
+}
+
+"""Error codes for the paymentMethodSelect mutation."""
+enum PaymentMethodSelectErrorCode {
+  """No cart context was provided (x-order-form-id header/cookie)."""
+  MISSING_CART_CONTEXT
+  """The cart was not found."""
+  CART_NOT_FOUND
+  """The provided methodId does not match any entry in Payment.methods."""
+  INVALID_METHOD_ID
+  """The provided accountId does not match any entry in Payment.savedCards."""
+  INVALID_SAVED_CARD_ACCOUNT_ID
+  """The bin does not match the BIN of the saved card named by accountId."""
+  MISMATCHED_BIN_FOR_SAVED_CARD
+  """
+  The bin is not 1 to 8 numeric digits — a BIN identifies an issuer range, never a card number.
+  """
+  INVALID_BIN_FORMAT
+  """
+  Never returned. The input once allowed at most one of bin / accountId; both are
+  now accepted so a saved card can be matched to an installment option by its own
+  BIN. Retained per ADR-00010 (additive-only with a deprecation window).
+  """
+  CONFLICTING_BIN_AND_ACCOUNT_ID @deprecated(reason: "Never returned; bin and accountId may now be sent together.")
+}
+
+"""A domain error returned from the paymentMethodSelect mutation."""
+type PaymentMethodSelectError {
+  """Machine-readable error code."""
+  code: PaymentMethodSelectErrorCode!
+  """Human-readable error message."""
+  message: String!
+}
+
+"""Payload returned by the paymentMethodSelect mutation."""
+type PaymentMethodSelectPayload {
+  """The updated payment state, or null if errors occurred."""
+  payment: Payment
+  """
+  The current billing address, echoed for convenience. Null when same-as-delivery is in effect.
+  """
+  billingAddress: Address
+  """Domain errors that occurred during the operation."""
+  userErrors: [PaymentMethodSelectError!]!
+}
+
+"""
+Input for selecting an installment count for the currently-selected method.
+"""
+input PaymentInstallmentSelectInput {
+  """Number of installments to select (1 = single payment, no interest)."""
+  count: Int!
+}
+
+"""Error codes for the paymentInstallmentSelect mutation."""
+enum PaymentInstallmentSelectErrorCode {
+  """No cart context was provided (x-order-form-id header/cookie)."""
+  MISSING_CART_CONTEXT
+  """The cart was not found."""
+  CART_NOT_FOUND
+  """
+  No payment method has been selected yet (paymentMethodSelect was never called).
+  """
+  MISSING_PAYMENT_METHOD_SELECTION
+  """
+  The count does not match any tier in the resolvable installment option.
+  """
+  INVALID_INSTALLMENT_COUNT
+}
+
+"""A domain error returned from the paymentInstallmentSelect mutation."""
+type PaymentInstallmentSelectError {
+  """Machine-readable error code."""
+  code: PaymentInstallmentSelectErrorCode!
+  """Human-readable error message."""
+  message: String!
+}
+
+"""
+Payload returned by the paymentInstallmentSelect mutation. Includes the
+recomputed cart so the order total (with any interest) updates in the same
+round trip.
+"""
+type PaymentInstallmentSelectPayload {
+  """The updated payment state, or null if errors occurred."""
+  payment: Payment
+  """
+  The recomputed cart, or null if errors occurred. Carries the order total with any installment interest applied.
+  """
+  cart: Cart
+  """
+  The current billing address, echoed for convenience. Null when same-as-delivery is in effect.
+  """
+  billingAddress: Address
+  """Domain errors that occurred during the operation."""
+  userErrors: [PaymentInstallmentSelectError!]!
+}
+
+"""
+Input for setting the billing address. When sameAsDelivery is true, every
+other field is ignored and no upstream write happens (VTEX's own default:
+an absent invoiceData falls back to the delivery address).
+"""
+input PaymentBillingAddressUpdateInput {
+  """
+  When true, billing uses the delivery address; every field below is ignored.
+  """
+  sameAsDelivery: Boolean!
+  """Address classification for the billing address."""
+  addressType: String
+  """
+  Postal code for the billing address. Required when sameAsDelivery is false.
+  """
+  postalCode: String
+  """
+  ISO 3166-1 alpha-3 country code (e.g. "BRA"). Required when sameAsDelivery is false.
+  """
+  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
+  """
+  A landmark reference. Sent upstream but not echoed back on billingAddress (Decision 11).
+  """
+  reference: String
+}
+
+"""Error codes for the paymentBillingAddressUpdate mutation."""
+enum PaymentBillingAddressUpdateErrorCode {
+  """No cart context was provided (x-order-form-id header/cookie)."""
+  MISSING_CART_CONTEXT
+  """The cart was not found."""
+  CART_NOT_FOUND
+  """sameAsDelivery is false but postalCode or country was omitted."""
+  MISSING_BILLING_ADDRESS_FIELDS
+}
+
+"""A domain error returned from the paymentBillingAddressUpdate mutation."""
+type PaymentBillingAddressUpdateError {
+  """Machine-readable error code."""
+  code: PaymentBillingAddressUpdateErrorCode!
+  """Human-readable error message."""
+  message: String!
+}
+
+"""Payload returned by the paymentBillingAddressUpdate mutation."""
+type PaymentBillingAddressUpdatePayload {
+  """
+  The billing address just written, or null when same-as-delivery is in effect.
+  """
+  billingAddress: Address
+  """
+  The updated payment state, or null if errors occurred, or when same-as-delivery is in effect, where no upstream write happens.
+  """
+  payment: Payment
+  """Domain errors that occurred during the operation."""
+  userErrors: [PaymentBillingAddressUpdateError!]!
+}
+
+"""
+Error codes for the paymentStartTransaction mutation. Login-required VTEX
+business codes (CHK0087, CHK003, ORD062) and generic infrastructure failures
+are never in this enum — per ADR-00007 they surface as top-level GraphQL
+errors (UNAUTHORIZED / UPSTREAM_ERROR), not userErrors.
+"""
+enum PaymentStartTransactionErrorCode {
+  """No cart context was provided (x-order-form-id header/cookie)."""
+  MISSING_CART_CONTEXT
+  """The cart was not found."""
+  CART_NOT_FOUND
+  """
+  No payment method has been selected yet (paymentMethodSelect was never called).
+  """
+  MISSING_PAYMENT_METHOD_SELECTION
+  """
+  VTEX opened the transaction but named no merchant transaction on it, so
+  neither the transaction id the send-payments POST addresses nor the merchant
+  name its body carries exists. The transaction is open upstream but cannot be
+  paid; the legacy checkout refuses the same state.
+  """
+  INVALID_TRANSACTION_DATA
+}
+
+"""A domain error returned from the paymentStartTransaction mutation."""
+type PaymentStartTransactionError {
+  """Machine-readable error code."""
+  code: PaymentStartTransactionErrorCode!
+  """Human-readable error message."""
+  message: String!
+}
+
+"""
+Payload returned by paymentStartTransaction: everything the browser needs to
+run the direct-to-gateway send-payments call (out of scope here) and the
+later gatewayCallback. The transaction cookies VTEX issues are set on the
+HTTP response (Set-Cookie), not exposed as a field.
+"""
+type PaymentStartTransactionPayload {
+  """The opened transaction's id. Null if errors occurred."""
+  transactionId: String
+  """
+  Name of the merchant responsible for the sale, as the gateway call's payment
+  `id` and `transaction.merchantName`. Projected from the same
+  merchantTransactions entry transactionId comes from — VTEX returns one entry
+  per seller, so a multi-seller order carries more than one and only the first
+  is exposed here (see specs/payment-transaction-payload-gaps.md, Decision 1).
+  Null if errors occurred.
+  """
+  merchantName: String
+  """
+  Origin of the payment gateway this transaction must be paid at, e.g.
+  "https://mystore.vtexpayments.com.br" — the base the browser's
+  direct-to-gateway send-payments POST appends its own path to. Origin only:
+  VTEX's own receiver path is the split-payment endpoint, not the
+  per-transaction one. Always an https origin inside vtexpayments.com.br: an
+  upstream receiver URI that is neither is rejected in favour of the
+  account-derived origin, since this field decides where card data is sent.
+  Null if errors occurred.
+  """
+  gatewayUrl: String
+  """
+  The order group, needed for the gateway call's orderId parameter and for gatewayCallback's input.
+  """
+  orderGroup: String
+  """The shopper's user profile id, needed for the gateway call."""
+  userProfileId: String
+  """
+  The payment amount for this transaction, as a decimal (e.g. "100.00") for
+  display. The gateway body wants minor units — read valueInCents for that,
+  never a client-side multiplication of this amount.
+  """
+  value: Money
+  """
+  The same payment amount in the currency's minor units (e.g. 10000 for
+  "100.00"), exactly as VTEX returned it and as this mutation sent it upstream.
+  The unit the gateway body's `value`/`installmentValue` fields expect. Null if
+  errors occurred.
+  """
+  valueInCents: Int
+  """
+  Pre-interest base amount this transaction was opened against, in the
+  currency's minor units — the gateway body's `referenceValue`. Equals
+  valueInCents when no interest applies. Null if errors occurred.
+  """
+  referenceValueInCents: Int
+  """Domain errors that occurred during the operation."""
+  userErrors: [PaymentStartTransactionError!]!
+}
+
+"""
+Input for finalizing a transaction after the direct-to-gateway call
+succeeded.
+"""
+input PaymentGatewayCallbackInput {
+  """The order group returned by paymentStartTransaction."""
+  orderGroup: String!
+}
+
+"""
+Error codes for the paymentGatewayCallback mutation. Login-required VTEX
+business codes (CHK0087, CHK003, ORD062) and generic infrastructure failures
+are never in this enum — per ADR-00007 they surface as top-level GraphQL
+errors (UNAUTHORIZED / UPSTREAM_ERROR), not userErrors.
+"""
+enum PaymentGatewayCallbackErrorCode {
+  """
+  The transaction cookies (Vtex_CHKO_Auth, CheckoutDataAccess) were not present on this request — paymentStartTransaction was not called first, or the five-minute window lapsed.
+  """
+  MISSING_TRANSACTION_COOKIES
+  """
+  VTEX requires a redirect or out-of-band flow to complete this payment. Phase 2; not supported in v1.
+  """
+  REDIRECT_REQUIRED
+}
+
+"""A domain error returned from the paymentGatewayCallback mutation."""
+type PaymentGatewayCallbackError {
+  """Machine-readable error code."""
+  code: PaymentGatewayCallbackErrorCode!
+  """Human-readable error message."""
+  message: String!
+}
+
+"""Payload returned by the paymentGatewayCallback mutation."""
+type PaymentGatewayCallbackPayload {
+  """
+  The finalized order group, echoed back on success. Null if errors occurred.
+  """
+  orderId: String
+  """Domain errors that occurred during the operation."""
+  userErrors: [PaymentGatewayCallbackError!]!
+}
+
+"""
+The installment plan a settled order was charged in. Projected from the
+placed-order payment record, which carries the count and the settled total
+only — never a per-installment amount and never an interest rate, unlike the
+live order form behind `Payment.selectedInstallment`. That asymmetry is
+upstream and permanent (see specs/settle-and-project-the-placed-order.md,
+Decision 2).
+"""
+type OrderInstallment @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """Number of installments the order was charged in. 1 = single payment."""
+  count: Int!
+  """
+  Total charged across all installments, including any interest. Null when the
+  settled record carries no amount, or no currency to denominate it in.
+  """
+  total: Money
+}
+
+"""
+A settled order's payment recap. Read-only; projected from VTEX's
+settled-order source rather than the live order form, so it keeps resolving
+after the order form itself stops existing. Carries no sensitive field: no
+full card number or CVV is ever read for this projection (RFC D13).
+"""
+type Order implements Node @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """
+  Globally unique identifier (Relay Node ID), encoded from the order group.
+  """
+  id: ID!
+  """
+  Card network / payment-system display name (e.g. "Visa", or a non-card
+  method's own name such as "Boleto Bancário"). Null when the settled order
+  carries no payment record to project one from.
+  """
+  network: String
+  """
+  Last four digits of the card used, when the payment method was a card.
+  Present for both a saved and a freshly-entered card — unlike Payment (T1),
+  where last four is a saved-card-only field. Null for a non-card method or
+  when no payment record exists to project one from.
+  """
+  lastFourDigits: String
+  """
+  Shopper-assigned custom label for the saved card used, when one was set.
+  Null for a freshly-entered (unsaved) card, a non-card method, or when no
+  payment record exists to project one from (see specs/order-read-model.md,
+  Decision 5).
+  """
+  label: String
+  """
+  The installment plan this order was charged in. Null when the settled record
+  reports none.
+  """
+  installment: OrderInstallment
+}
+
 """
 The authentication methods an account enables, read before rendering a sign-in form.
 """