@vtex/faststore 0.0.8 → 0.0.11

package/dist/schema.graphql

@@ -326,9 +326,10 @@ extend type Query {
 
 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.
+  Resolve the active cart from the request context: the order form id in the
+  `checkout.vtex.com=__ofid=<id>` cookie. When no cart context is present, a
+  new cart is created and the `checkout.vtex.com` cookie that names it is set
+  on the response.
   """
   cart: Cart!
 }
@@ -344,8 +345,8 @@ extend type Query {
     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
+  Simulate shipping options for the entire active cart. Reads the cart named by the
+  `checkout.vtex.com` cookie 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.
@@ -375,8 +376,8 @@ extend type Query {
   """
   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`.
+  Resolve the shopper's session state from the active order form (the one the
+  `checkout.vtex.com` cookie names). Projects from the same order form fetch as `cart`.
   """
   session: Session!
 }
@@ -390,16 +391,17 @@ extend type Query {
 
 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).
+  A settled order's payment recap, keyed on the order's Node ID. Null when the
+  id is malformed, of another type, or 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.
+    The Relay Node ID of the order: `Order.id`, or `orderNodeId` from paymentStartTransaction /
+    paymentGatewayCallback.
     """
-    orderGroup: String!
+    id: ID!
   ): Order
 }
 
@@ -503,6 +505,36 @@ extend type Query {
   ): CustomerOrdersConnection! @cacheControl(maxAge: 0, scope: PRIVATE)
 }
 
+extend type Query {
+  """
+  The signed-in shopper's own saved cards. Takes no id — the identity comes from
+  the session. Resolves to the shopper's entity, with an empty list when no card
+  is saved. Null only when the read fails, alongside an UNAUTHORIZED,
+  UPSTREAM_ERROR, or UPSTREAM_TIMEOUT error at this path (ADR-00007), so the
+  failure does not null the rest of the operation.
+  """
+  customerSavedCards: CustomerSavedCards
+}
+
+extend type Query {
+  """
+  The credit-card networks the store accepts on the request's sales channel,
+  with their validation rules, for adding a saved card. Requires a signed-in
+  shopper. Null when the read fails, alongside an UNAUTHORIZED, UPSTREAM_ERROR,
+  UPSTREAM_TIMEOUT, or NO_CARD_NETWORKS error at this path (ADR-00007).
+  NO_CARD_NETWORKS means the store accepts no credit-card network on this
+  sales channel; the list is never empty.
+  """
+  savedCardNetworks: [CardNetworkRule!]
+  """
+  The signed-in shopper's saved addresses a new card can be billed to, in the
+  platform's order. Takes no id. Empty when none is saved. Null only when the
+  read fails, alongside an UNAUTHORIZED, UPSTREAM_ERROR, or UPSTREAM_TIMEOUT
+  error at this path.
+  """
+  customerSavedCardBillingAddresses: [CardBillingAddress!]
+}
+
 """
 Root mutation type. Cart and checkout operations are declared via
 `extend type Mutation` in the checkout module.
@@ -526,14 +558,14 @@ extend type Mutation {
     """Item details to add."""
     input: CartItemAddInput!
   ): CartItemAddPayload!
-  """Remove an item from the cart entirely (sets quantity to 0)."""
+  """Remove a line 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.
+  quantity is set to 0). Tolerant: lines absent from the cart are skipped.
   """
   cartItemsRemove(
     """Items to remove."""
@@ -577,6 +609,15 @@ extend type Mutation {
   context and is never created.
   """
   cartValidate: CartValidatePayload!
+  """
+  Move the active cart onto the request's sales channel, then reconcile its locale. Takes no
+  arguments: the cart is resolved from the request context and is never created. An empty cart, or
+  a cart already on the active channel, does not send `sc`. Otherwise one POST to `items/update`
+  with `sc` re-sends every item's index and current quantity, so Checkout reprocesses that order
+  form and drops lines the destination cannot sell. An upstream failure is reported in `userErrors`
+  and does not throw.
+  """
+  cartSalesChannelSync: CartSalesChannelSyncPayload!
 }
 
 extend type Mutation {
@@ -623,7 +664,7 @@ extend type Mutation {
     input: PaymentMethodSelectInput!
   ): PaymentMethodSelectPayload!
   """
-  Select an installment count for the currently-selected method. Recomputes the cart total.
+  Select an installment count for the currently-selected method. The returned cart's `total` is the greater of the order form's value and the selected payment's value.
   """
   paymentInstallmentSelect(
     """Installment count to select."""
@@ -743,6 +784,18 @@ extend type Mutation {
   ): CustomerOrderCancelPayload!
 }
 
+extend type Mutation {
+  """
+  Removes one of the signed-in shopper's saved cards, by the id the
+  customerSavedCards read returned. Returns the refreshed list on success.
+  Throws UNAUTHORIZED / UPSTREAM_ERROR / UPSTREAM_TIMEOUT (ADR-00007).
+  """
+  customerSavedCardRemove(
+    """The card's id, as customerSavedCards returned it."""
+    id: ID!
+  ): CustomerSavedCardRemovePayload!
+}
+
 """
 A manufacturer or designer brand.
 Maps to VTEX Brand entity.
@@ -1195,7 +1248,7 @@ type Rating {
 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 {
+type Collection implements Node @cacheControl(maxAge: 300, scope: PUBLIC) {
   """Globally unique identifier."""
   id: ID!
   """Collection title."""
@@ -1761,7 +1814,13 @@ type Cart implements Node @cacheControl(maxAge: 0, scope: PRIVATE) {
   items: [CartItem!]!
   """Aggregated totals (items, shipping, discounts, etc.)."""
   totalizers: [CartTotalizer!]!
-  """Total cart value."""
+  """
+  Total cart value: the greater of the order form's value and the selected payment's value.
+  While an installment tier with interest is selected, the payment's value is the larger of
+  the two and the total includes the interest, so it matches what the transaction charges.
+  Without a selected payment it is the order form's value. Totalizer lines do not include an
+  interest line, so they may not add up to this total.
+  """
   total: Money!
   """
   Server messages from cart processing (e.g. promotions applied, stock warnings).
@@ -1804,10 +1863,10 @@ type Cart implements Node @cacheControl(maxAge: 0, scope: PRIVATE) {
   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.
+  cart is left exactly as it was: nothing here reprices it or removes an item. Converging it is the
+  `cartSalesChannelSync` write, and that write 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
 }
@@ -2212,30 +2271,32 @@ input CartItemAddInput {
   seller: ID = "U2VsbGVyOjE="
 }
 
-"""Input for removing an item from a cart."""
+"""Input for removing a line from a cart."""
 input CartItemRemoveInput {
-  """The variant's global Node ID to remove."""
-  variantId: ID!
+  """The line to remove: its `CartItem.lineId`."""
+  lineId: String!
 }
 
-"""Input for removing multiple items from a cart in one call."""
+"""Input for removing multiple lines from a cart in one call."""
 input CartItemsRemoveInput {
-  """The variants' global Node IDs to remove. Duplicates are collapsed."""
-  variantIds: [ID!]!
+  """
+  The lines to remove: their `CartItem.lineId` values. Duplicates are collapsed.
+  """
+  lineIds: [String!]!
 }
 
-"""Input for increasing the quantity of a cart item."""
+"""Input for increasing the quantity of a cart line."""
 input CartItemQuantityIncreaseInput {
-  """The variant's global Node ID whose quantity to increase."""
-  variantId: ID!
+  """The line whose quantity to increase: its `CartItem.lineId`."""
+  lineId: String!
   """Amount to add to the current quantity. Defaults to 1."""
   quantityToAdd: Int = 1
 }
 
-"""Input for decreasing the quantity of a cart item."""
+"""Input for decreasing the quantity of a cart line."""
 input CartItemQuantityDecreaseInput {
-  """The variant's global Node ID whose quantity to decrease."""
-  variantId: ID!
+  """The line whose quantity to decrease: its `CartItem.lineId`."""
+  lineId: String!
   """Amount to subtract from the current quantity. Defaults to 1."""
   quantityToRemove: Int = 1
 }
@@ -2254,7 +2315,7 @@ input CartCouponRemoveInput {
 
 """Error codes for cart item add operations."""
 enum CartItemAddErrorCode {
-  """No cart context was provided (x-order-form-id header/cookie)."""
+  """No cart context was provided (no valid `checkout.vtex.com` cookie)."""
   MISSING_CART_CONTEXT
   """The quantity must be a positive integer."""
   INVALID_QUANTITY
@@ -2268,58 +2329,56 @@ enum CartItemAddErrorCode {
 
 """Error codes for cart item remove operations."""
 enum CartItemRemoveErrorCode {
-  """No cart context was provided (x-order-form-id header/cookie)."""
+  """No cart context was provided (no valid `checkout.vtex.com` cookie)."""
   MISSING_CART_CONTEXT
-  """The specified variant was not found in the cart."""
+  """The specified line 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
+  """The upstream checkout API returned an unusable response."""
+  UPSTREAM_ERROR
 }
 
 """Error codes for cart items batch remove operations."""
 enum CartItemsRemoveErrorCode {
-  """No cart context was provided (x-order-form-id header/cookie)."""
+  """No cart context was provided (no valid `checkout.vtex.com` cookie)."""
   MISSING_CART_CONTEXT
-  """None of the specified variants were found in the cart."""
+  """None of the specified lines 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 input contained no line IDs."""
+  NO_LINE_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)."""
+  """No cart context was provided (no valid `checkout.vtex.com` cookie)."""
   MISSING_CART_CONTEXT
   """The quantity must be a positive integer."""
   INVALID_QUANTITY
-  """The specified variant was not found in the cart."""
+  """The specified line 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
+  """The upstream checkout API returned an unusable response."""
+  UPSTREAM_ERROR
 }
 
 """Error codes for cart item quantity decrease operations."""
 enum CartItemQuantityDecreaseErrorCode {
-  """No cart context was provided (x-order-form-id header/cookie)."""
+  """No cart context was provided (no valid `checkout.vtex.com` cookie)."""
   MISSING_CART_CONTEXT
   """The quantity must be a positive integer."""
   INVALID_QUANTITY
-  """The specified variant was not found in the cart."""
+  """The specified line 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
+  """The upstream checkout API returned an unusable response."""
+  UPSTREAM_ERROR
 }
 
 """A domain error returned from a cart item add mutation."""
@@ -2404,7 +2463,7 @@ type CartItemQuantityDecreasePayload {
 
 """Error codes for cart coupon apply operations."""
 enum CartCouponApplyErrorCode {
-  """No cart context was provided (x-order-form-id header/cookie)."""
+  """No cart context was provided (no valid `checkout.vtex.com` cookie)."""
   MISSING_CART_CONTEXT
   """The cart was not found."""
   CART_NOT_FOUND
@@ -2412,11 +2471,16 @@ enum CartCouponApplyErrorCode {
   COUPON_NOT_FOUND
   """The coupon code has expired."""
   COUPON_EXPIRED
+  """
+  The code was rejected while another coupon was applied, and the applied coupons were kept. The
+  platform does not say whether the code is unknown or cannot be combined with them.
+  """
+  COUPON_NOT_COMBINED
 }
 
 """Error codes for cart coupon remove operations."""
 enum CartCouponRemoveErrorCode {
-  """No cart context was provided (x-order-form-id header/cookie)."""
+  """No cart context was provided (no valid `checkout.vtex.com` cookie)."""
   MISSING_CART_CONTEXT
   """The cart was not found."""
   CART_NOT_FOUND
@@ -2462,7 +2526,7 @@ type CartCouponRemovePayload {
 
 """Error codes for cart validation operations."""
 enum CartValidateErrorCode {
-  """No cart context was provided (x-order-form-id header/cookie)."""
+  """No cart context was provided (no valid `checkout.vtex.com` cookie)."""
   MISSING_CART_CONTEXT
   """The cart was not found."""
   CART_NOT_FOUND
@@ -2488,6 +2552,44 @@ type CartValidatePayload {
   userErrors: [CartValidateError!]!
 }
 
+"""Error codes for moving a cart onto the active sales channel."""
+enum CartSalesChannelSyncErrorCode {
+  """No cart context was provided (no valid `checkout.vtex.com` 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 the cartSalesChannelSync mutation."""
+type CartSalesChannelSyncError {
+  """Machine-readable error code."""
+  code: CartSalesChannelSyncErrorCode!
+  """Human-readable error message."""
+  message: String!
+}
+
+"""
+Payload returned by the cartSalesChannelSync mutation.
+
+The cart comes from the request context and is never created. An empty cart, or a cart already on
+the active sales channel, does not send `sc`. Otherwise one POST to `items/update` with `sc`
+re-sends every item's index and current quantity, so Checkout reprocesses that order form and drops
+lines the destination cannot sell, and then the locale is reconciled. An upstream failure is
+reported in `userErrors` and does not throw.
+"""
+type CartSalesChannelSyncPayload {
+  """
+  The cart after the channel move and locale reconciliation, or null if errors occurred.
+  """
+  cart: Cart
+  """Domain errors that occurred during the operation."""
+  userErrors: [CartSalesChannelSyncError!]!
+}
+
 """The delivery channel for a shipping option."""
 enum DeliveryChannel {
   """Home delivery."""
@@ -2604,7 +2706,7 @@ enum ShippingSimulateErrorCode {
   """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.
+  No active cart in context: the cartShippingSimulation query requires the `checkout.vtex.com` cart cookie and never mints a cart.
   """
   MISSING_CART_CONTEXT
   """
@@ -2648,8 +2750,8 @@ input ShippingSimulateInput {
 
 """
 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.
+destination only; items are sourced from the cart named by the
+`checkout.vtex.com` cookie, so there is no variant, quantity, or seller.
 """
 input CartShippingSimulateInput {
   """Postal code of the delivery destination."""
@@ -2738,7 +2840,7 @@ input ClientPreferencesUpdateInput {
 
 """Error codes for client profile update operations."""
 enum ClientProfileUpdateErrorCode {
-  """No cart context was provided (x-order-form-id header/cookie)."""
+  """No cart context was provided (no valid `checkout.vtex.com` cookie)."""
   MISSING_CART_CONTEXT
   """The cart was not found."""
   CART_NOT_FOUND
@@ -2748,7 +2850,7 @@ enum ClientProfileUpdateErrorCode {
 
 """Error codes for client preferences update operations."""
 enum ClientPreferencesUpdateErrorCode {
-  """No cart context was provided (x-order-form-id header/cookie)."""
+  """No cart context was provided (no valid `checkout.vtex.com` cookie)."""
   MISSING_CART_CONTEXT
   """The cart was not found."""
   CART_NOT_FOUND
@@ -2883,8 +2985,10 @@ 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!
+  """
+  Recipient name for the delivery address. Omit it for a destination-only write: the cart keeps its current recipient name. A blank string is rejected with MISSING_RECIPIENT_NAME.
+  """
+  recipientName: String
   """Postal code for the delivery address."""
   postalCode: String!
   """ISO 3166-1 alpha-3 country code (e.g. "BRA")."""
@@ -2905,7 +3009,7 @@ input ShippingAddressUpdateInput {
 
 """Error codes for shipping address update operations."""
 enum ShippingAddressUpdateErrorCode {
-  """No cart context was provided (x-order-form-id header/cookie)."""
+  """No cart context was provided (no valid `checkout.vtex.com` cookie)."""
   MISSING_CART_CONTEXT
   """The cart was not found."""
   CART_NOT_FOUND
@@ -2952,7 +3056,7 @@ input ShippingOptionSelectInput {
 
 """Error codes for shipping option select operations."""
 enum ShippingOptionSelectErrorCode {
-  """No cart context was provided (x-order-form-id header/cookie)."""
+  """No cart context was provided (no valid `checkout.vtex.com` cookie)."""
   MISSING_CART_CONTEXT
   """The cart was not found."""
   CART_NOT_FOUND
@@ -3084,7 +3188,17 @@ type PaymentMethod {
   """
   name: String!
   """
-  Payment-system group (e.g. "creditCardPaymentGroup", "debitCardPaymentGroup"). Store-configured; kept as a string, not an enum.
+  The vendor-neutral kind of this method: the closed set `PaymentType` defines. Derived
+  from `groupName`; `OTHER` covers every group that is not mapped, including store-specific
+  groups and wallets other than PayPal. Never null. Read it to decide which payment UI a
+  method gets; read `groupName` to tell two `OTHER` methods apart.
+  """
+  type: PaymentType!
+  """
+  The payment-system group exactly as the order form carries it (e.g. "creditCardPaymentGroup",
+  "custom201PaymentGroupPaymentGroup"). Store-configured and open-ended, so kept as a string, not an
+  enum. It is the gateway transport value: the Send Payments request needs this literal, and the
+  gateway rejects anything else. Prefer `type` to classify a method.
   """
   groupName: String!
   """
@@ -3121,13 +3235,26 @@ type PaymentMethodValidator {
   cvvMask: String
   """Regex validating the security-code (CVV) input. Null when unused."""
   cvvRegex: String
-  """Whether this method requires the security code (CVV)."""
+  """
+  Whether this method requires the security code (CVV). False when the order form carries no
+  validator for the method: a method with no validator, such as Cash or Bank Invoice,
+  legitimately resolves false, and this field cannot tell that from an upstream that omitted the flag.
+  """
   cvvRequired: Boolean!
-  """Whether this method requires an expiration date."""
+  """
+  Whether this method requires an expiration date. False when the order form carries no
+  validator for the method: a method with no validator, such as Cash, legitimately resolves false.
+  """
   expirationRequired: Boolean!
-  """Whether this method requires the cardholder name."""
+  """
+  Whether this method requires the cardholder name. False when the order form carries no
+  validator for the method: a method with no validator, such as Cash, legitimately resolves false.
+  """
   holderNameRequired: Boolean!
-  """Whether this method requires a billing address."""
+  """
+  Whether this method requires a billing address. False when the order form carries no
+  validator for the method: a method with no validator, such as Cash, legitimately resolves false.
+  """
   billingAddressRequired: Boolean!
   """
   Whether a cardholder document field is displayable for this method. Distinct from documentRequired.
@@ -3142,19 +3269,29 @@ type PaymentMethodValidator {
 """
 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).
+non-normalized value object (ADR-0012). Field names match the catalog's
+`Installment`, so one selection reads either; nullability of `interestRate` and
+`interestFree` differs by design.
 """
 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!
+  """
+  The whole-plan amount: the total across all installments, including any interest.
+  """
+  totalAmount: Money!
   """
   Interest rate in hundredths of a percent, exactly as the VTEX order form carries it (100 = 1%; 0 = interest-free).
+  Null when the order form did not say what the rate is — which is not the same as 0 (interest-free).
   """
-  interestRate: Float!
+  interestRate: Float
+  """
+  Whether this tier is interest-free: true when the rate is 0, false for any other rate. Null exactly
+  when `interestRate` is null. The synthesized `count: 1` tier is 0 and true, a stated fact.
+  """
+  interestFree: Boolean
 }
 
 """
@@ -3197,20 +3334,31 @@ type SavedCard @cacheControl(maxAge: 0, scope: PRIVATE) {
   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")."""
+  """
+  Card network / issuer display name (e.g. "Visa"). An empty string when the order form carries no
+  network name for the card: nothing to show.
+  """
   network: String!
-  """Last four digits of the card number."""
+  """
+  Last four digits of the card number. An empty string when the order form carries no card number
+  for the account: nothing to show.
+  """
   lastFourDigits: String!
-  """BIN of the saved card, for installment-option lookup by network."""
+  """
+  BIN of the saved card, for installment-option lookup by network. An empty string when the order
+  form carries no BIN for the account: nothing to look up.
+  """
   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.
+  Whether the card is expired. Expired cards are still returned. Fails closed: true when the
+  order form does not report the expiry, so a card of unknown expiry is never offered as usable.
   """
   expired: Boolean!
   """
-  Whether completing payment with this card requires the shopper to enter the CVV.
+  Whether completing payment with this card requires the shopper to enter the CVV. True is the
+  default: it is what the field resolves to when the order form omits `useCvvForAuthorization`.
   """
   cvvRequired: Boolean!
 }
@@ -3227,7 +3375,9 @@ 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.
+  A newly-entered card's BIN, once the full 8 digits are known: omit it, send null or "" until then.
+  Anything else is rejected with INVALID_BIN_FORMAT. With an accountId, the saved card's own BIN (1 to 8
+  digits) may be restated. Omit for a non-card method.
   """
   bin: String
   """
@@ -3238,7 +3388,7 @@ input PaymentMethodSelectInput {
 
 """Error codes for the paymentMethodSelect mutation."""
 enum PaymentMethodSelectErrorCode {
-  """No cart context was provided (x-order-form-id header/cookie)."""
+  """No cart context was provided (no valid `checkout.vtex.com` cookie)."""
   MISSING_CART_CONTEXT
   """The cart was not found."""
   CART_NOT_FOUND
@@ -3249,7 +3399,8 @@ enum PaymentMethodSelectErrorCode {
   """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.
+  The bin is not in an accepted format — a BIN identifies an issuer range, never a card number. A new
+  card (no accountId) carries no bin or exactly 8 digits; with an accountId, a bin is 1 to 8 digits.
   """
   INVALID_BIN_FORMAT
   """
@@ -3290,7 +3441,7 @@ input PaymentInstallmentSelectInput {
 
 """Error codes for the paymentInstallmentSelect mutation."""
 enum PaymentInstallmentSelectErrorCode {
-  """No cart context was provided (x-order-form-id header/cookie)."""
+  """No cart context was provided (no valid `checkout.vtex.com` cookie)."""
   MISSING_CART_CONTEXT
   """The cart was not found."""
   CART_NOT_FOUND
@@ -3321,7 +3472,7 @@ 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.
+  The updated cart, or null if errors occurred. Its `total` is the greater of the order form's value and the selected payment's value, so it includes the selected tier's interest.
   """
   cart: Cart
   """
@@ -3372,7 +3523,7 @@ input PaymentBillingAddressUpdateInput {
 
 """Error codes for the paymentBillingAddressUpdate mutation."""
 enum PaymentBillingAddressUpdateErrorCode {
-  """No cart context was provided (x-order-form-id header/cookie)."""
+  """No cart context was provided (no valid `checkout.vtex.com` cookie)."""
   MISSING_CART_CONTEXT
   """The cart was not found."""
   CART_NOT_FOUND
@@ -3413,7 +3564,7 @@ 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)."""
+  """No cart context was provided (no valid `checkout.vtex.com` cookie)."""
   MISSING_CART_CONTEXT
   """The cart was not found."""
   CART_NOT_FOUND
@@ -3469,6 +3620,11 @@ type PaymentStartTransactionPayload {
   The order group, needed for the gateway call's orderId parameter and for gatewayCallback's input.
   """
   orderGroup: String
+  """
+  The Relay Node ID of the order for this order group, for Query.order(id:). Null if errors occurred
+  or the transaction carried no order group.
+  """
+  orderNodeId: ID
   """The shopper's user profile id, needed for the gateway call."""
   userProfileId: String
   """
@@ -3523,6 +3679,14 @@ enum PaymentGatewayCallbackErrorCode {
   VTEX answered 428: the payment needs a challenge step. When `redirectUrl` is set the shopper must be sent there; when it is null the challenge uses a mechanism this API does not hand over (for example a payment app).
   """
   REDIRECT_REQUIRED
+  """
+  The payment gateway answered the callback and refused the payment: a 400, 402, 422 or 500 response whose body carries a VTEX `error` object (not a login-required code). The message is a fixed sentence; nothing the gateway said is forwarded. A response that is not shaped like a gateway answer (502-504, an unreadable body, a timeout) is a top-level `UPSTREAM_ERROR` instead.
+  """
+  PAYMENT_DECLINED
+  """
+  The order group sent is not the one this session's `paymentStartTransaction` returned, or this session started none. The message is a fixed sentence that does not say which, and nothing was sent to VTEX.
+  """
+  ORDER_GROUP_MISMATCH
 }
 
 """A domain error returned from the paymentGatewayCallback mutation."""
@@ -3540,6 +3704,10 @@ type PaymentGatewayCallbackPayload {
   """
   orderId: String
   """
+  The Relay Node ID of the finalized order, for Query.order(id:). Null if errors occurred.
+  """
+  orderNodeId: ID
+  """
   The bank's challenge page; set only when VTEX answered 428 with a usable http(s) URL.
   """
   redirectUrl: String
@@ -3857,6 +4025,14 @@ type PostalCodeAddress @cacheControl(maxAge: 0, scope: PRIVATE) {
 The authentication methods an account enables, read before rendering a sign-in form.
 """
 type SessionAuthProviders {
+  """
+  Stable identifier for this account's sign-in configuration, as
+  base64("SessionAuthProviders:<account>"). It identifies the account's
+  configuration, never a shopper: it is what lets a client cache normalize the
+  type and read it outside a page's server-side fetch. Not a Relay Node: node(id)
+  on this value resolves to null, because the configuration is read as a whole.
+  """
+  id: ID!
   """Whether classic email and password sign-in is enabled."""
   passwordAuthentication: Boolean!
   """Whether email access-code (passwordless) sign-in is enabled."""
@@ -4387,6 +4563,10 @@ type CustomerOrder implements Node @cacheControl(maxAge: 0, scope: PRIVATE) {
   """Timestamp when the order was invoiced."""
   invoiceDate: DateTime
   """
+  Invoice files the merchant sent. Oldest issue date first. Empty when none qualify.
+  """
+  invoices: [CustomerOrderInvoice!]!
+  """
   Order delivery channel. The order-level value when OMS supplies it, otherwise
   the channel every logistics entry agrees on. Null when those entries differ.
   """
@@ -4462,13 +4642,33 @@ type CustomerOrderItem {
 }
 
 """A custom value recorded on an order line."""
-type CustomerOrderItemCustomField {
+type CustomerOrderItemCustomField @cacheControl(maxAge: 0, scope: PRIVATE) {
   """Custom field name."""
   name: String!
   """Custom field value as recorded on the order."""
   value: String!
 }
 
+"""Sale or return, from the OMS package type."""
+enum CustomerOrderInvoiceKind {
+  """An Output invoice, the sale document."""
+  SALE
+  """An Input invoice, the return document."""
+  RETURN
+}
+
+"""One invoice file the merchant sent on the order."""
+type CustomerOrderInvoice {
+  """Merchant file address. http or https."""
+  url: String!
+  """
+  Package issuance date. Null when OMS omitted it or sent a value that is not a date.
+  """
+  issuedAt: DateTime
+  """SALE for an Output invoice. RETURN for an Input invoice."""
+  kind: CustomerOrderInvoiceKind!
+}
+
 """Products that share one selected delivery option."""
 type CustomerOrderDeliveryOption {
   """Selected service-level agreement name."""
@@ -4483,10 +4683,14 @@ type CustomerOrderDeliveryOption {
   address: CustomerOrderAddress
   """Product lines assigned to this option."""
   items: [CustomerOrderItem!]!
+  """
+  Distinct http or https tracking addresses for invoices whose items fall in this option.
+  """
+  trackingLinks: [String!]!
 }
 
 """Historical delivery address recorded on an order."""
-type CustomerOrderAddress {
+type CustomerOrderAddress @cacheControl(maxAge: 0, scope: PRIVATE) {
   """Recipient name."""
   receiverName: String
   """Postal code."""
@@ -4510,7 +4714,7 @@ type CustomerOrderAddress {
 }
 
 """One payment recorded on a placed order."""
-type CustomerOrderPayment {
+type CustomerOrderPayment @cacheControl(maxAge: 0, scope: PRIVATE) {
   """Shopper-facing payment method name."""
   methodName: String
   """
@@ -4675,3 +4879,171 @@ type CustomerOrderCancelPayload {
   """Typed, expected failures. Empty on success."""
   userErrors: [CustomerOrderCancelError!]!
 }
+
+"""
+The signed-in shopper's saved cards, read from their persistent checkout
+profile. Never cart-scoped.
+"""
+type CustomerSavedCards @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """
+  Stable identity for cache normalization. Not a Relay Node ID: derived from the
+  session, with no id argument and no Query.node entry.
+  """
+  id: ID!
+  """
+  Every card the shopper saved, in the platform's order, including expired and
+  unusable ones. Empty when none is saved.
+  """
+  cards: [CustomerSavedCard!]!
+}
+
+"""
+One of the shopper's saved cards, as the account sees it. Distinct from the
+cart-scoped SavedCard. Never carries a card number beyond its last four digits,
+a BIN, or a security code.
+"""
+type CustomerSavedCard @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """Opaque, stable cache key. Not a Relay Node ID."""
+  id: ID!
+  """The card network the card belongs to."""
+  network: CardNetwork!
+  """
+  The card number's last four digits. Empty when the platform's record has none.
+  """
+  lastDigits: String!
+  """When the card expires. Null when the platform's record has no date."""
+  expiry: CardExpiry
+  """
+  Whether the card can still be used, derived once here so the UI never re-derives it.
+  """
+  status: CustomerSavedCardStatus!
+}
+
+"""A card network, such as Visa or Mastercard."""
+type CardNetwork {
+  """
+  The platform's payment-system id for the network. Empty when the record has none.
+  """
+  id: String!
+  """
+  Display name of the network (e.g. "Visa"). Falls back to the id when the record has no name.
+  """
+  name: String!
+}
+
+"""A card's expiry month and year."""
+type CardExpiry {
+  """Expiry month, from 1 to 12."""
+  month: Int!
+  """Four-digit expiry year."""
+  year: Int!
+}
+
+"""Whether a saved card can still be used."""
+enum CustomerSavedCardStatus {
+  """The card has not expired and the platform reports nothing against it."""
+  USABLE
+  """
+  The card's expiry date has passed. Wins over any other platform report.
+  """
+  EXPIRED
+  """The card has not expired, but the platform reports it cannot be used."""
+  UNUSABLE
+}
+
+"""
+A card network the store accepts on the request's sales channel, with the
+rules card entry validates a card by. Read from the store's payment systems,
+never from a cart.
+"""
+type CardNetworkRule @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """
+  The network. Its id is the platform's payment-system id, the same id a saved
+  card's network carries.
+  """
+  network: CardNetwork!
+  """
+  Pattern a full card number of this network matches. Null when the store sets none.
+  """
+  numberRegex: String
+  """
+  Display mask for the card number, with 9 standing for a digit. Null when the store sets none.
+  """
+  numberMask: String
+  """Pattern the security code matches. Null when the store sets none."""
+  securityCodeRegex: String
+  """Display mask for the security code. Null when the store sets none."""
+  securityCodeMask: String
+  """Whether the card asks for a security code."""
+  securityCodeRequired: Boolean!
+  """Whether the card asks for an expiry date."""
+  expirationRequired: Boolean!
+  """Whether the card asks for the holder's name."""
+  holderNameRequired: Boolean!
+  """Whether a cardholder document is required for this network."""
+  requiresDocument: Boolean!
+  """
+  Whether a cardholder document field is shown for this network. Distinct from requiresDocument.
+  """
+  displayDocument: Boolean!
+}
+
+"""
+One of the signed-in shopper's saved addresses a new card can be billed to.
+"""
+type CardBillingAddress @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """Opaque, stable cache key. Not a Relay Node ID."""
+  id: ID!
+  """
+  Name of the person the address belongs to. Null when the platform's record has none.
+  """
+  receiverName: String
+  """Street name. Null when the platform's record has none."""
+  street: String
+  """Street number. Null when the platform's record has none."""
+  number: String
+  """
+  Complement, such as an apartment. Null when the platform's record has none.
+  """
+  complement: String
+  """Neighborhood. Null when the platform's record has none."""
+  neighborhood: String
+  """City. Null when the platform's record has none."""
+  city: String
+  """State or province. Null when the platform's record has none."""
+  state: String
+  """Postal code. Null when the platform's record has none."""
+  postalCode: String
+  """
+  Country of the address, as the platform stores it (ISO 3166-1 alpha-3).
+  """
+  country: String!
+}
+
+"""Payload returned by customerSavedCardRemove."""
+type CustomerSavedCardRemovePayload {
+  """
+  The shopper's saved cards after the removal. Null when userErrors is non-empty.
+  """
+  customerSavedCards: CustomerSavedCards
+  """Domain errors that stopped the removal. Empty on success."""
+  userErrors: [CustomerSavedCardRemoveError!]!
+}
+
+"""A domain error returned by customerSavedCardRemove."""
+type CustomerSavedCardRemoveError {
+  """Machine-readable error code."""
+  code: CustomerSavedCardRemoveErrorCode!
+  """Human-readable error message."""
+  message: String!
+}
+
+"""Why a saved card was not removed."""
+enum CustomerSavedCardRemoveErrorCode {
+  """The id names no saved card of the signed-in shopper."""
+  CARD_NOT_FOUND
+  """
+  The platform refused the removal, or the card is still listed after it.
+  """
+  REMOVAL_REFUSED
+}