@vtex/faststore 0.0.7 → 0.0.10

package/dist/schema.graphql

@@ -403,6 +403,27 @@ extend type Query {
   ): Order
 }
 
+extend type Query {
+  """
+  The fields a postal code resolves to. Needs no cart and no shopper. Null when
+  the platform does not know the code. A lookup that could not run is an error,
+  never null. A malformed argument is a BAD_USER_INPUT error and reaches no
+  upstream.
+  """
+  addressByPostalCode(
+    """
+    ISO 3166-1 alpha-3 code, such as `BRA`. Case and surrounding spaces are
+    ignored.
+    """
+    country: String!
+    """
+    The postal code, masked or not: letters, digits, spaces, and hyphens, up to
+    20 characters.
+    """
+    postalCode: String!
+  ): PostalCodeAddress
+}
+
 extend type Query {
   """Which authentication methods this account enables."""
   sessionAuthProviders: SessionAuthProviders!
@@ -427,6 +448,89 @@ extend type Query {
   nothing yet.
   """
   customerProfile: CustomerProfile
+  """
+  The signed-in shopper's saved addresses, in the order the profile returns
+  them. Takes no id: the identity comes from the session. Empty when the shopper
+  has none. Throws UNAUTHORIZED or UPSTREAM_ERROR (ADR-00007).
+  """
+  customerAddresses: [CustomerAddress!]!
+  """
+  The signed-in shopper's address book. Takes no id: the identity comes from the
+  session. Throws UNAUTHORIZED, or UPSTREAM_ERROR when `addresses` is selected
+  (ADR-00007).
+  """
+  customerAddressBook: CustomerAddressBook!
+  """
+  One of the signed-in shopper's saved addresses. Null when the id is malformed,
+  names another entity type, or is not one of this shopper's addresses; these
+  cases are indistinguishable.
+  """
+  customerAddress(
+    """The CustomerAddress global id, as returned by `customerAddresses`."""
+    id: ID!
+  ): CustomerAddress
+}
+
+extend type Query {
+  """
+  The countries the store ships to. Takes no arguments and needs no cart or
+  shopper. Null when the platform could not be read, with the reason in
+  `errors`; a consumer then knows no shipping country rather than none.
+  """
+  shippingCountries: ShippingCountries
+}
+
+extend type Query {
+  """
+  Read one order owned by the signed-in shopper. A missing or foreign order returns null.
+  """
+  customerOrder(
+    """Shopper-facing order number, or the global Node id of a CustomerOrder."""
+    id: ID!
+  ): CustomerOrder @cacheControl(maxAge: 0, scope: PRIVATE)
+  """One page of the signed-in shopper's orders."""
+  customerOrders(
+    """Page size. Must be 25."""
+    first: Int!
+    """Opaque resume cursor issued by this field."""
+    after: Cursor
+    """Not supported. The list is read forward from the route."""
+    last: Int
+    """Not supported. The list is read forward from the route."""
+    before: Cursor
+    """View, text, and placed-date range."""
+    filter: CustomerOrdersFilterInput
+  ): 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!]
 }
 
 """
@@ -452,14 +556,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."""
@@ -503,6 +607,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 {
@@ -627,6 +740,58 @@ extend type Mutation {
     """The fields to write. Provide only what the shopper edited."""
     input: CustomerProfileUpdateInput!
   ): CustomerProfileUpdatePayload!
+  """
+  Save a new address for the signed-in shopper. The store must ship to the country, and the
+  country's rules must accept the fields. Refusals come back as `userErrors`.
+  """
+  customerAddressCreate(
+    """The address to save."""
+    input: CustomerAddressCreateInput!
+  ): CustomerAddressCreatePayload!
+  """
+  Change one of the signed-in shopper's saved addresses. The merged address is validated
+  against its stored country. Refusals come back as `userErrors`.
+  """
+  customerAddressUpdate(
+    """The CustomerAddress global id, as returned by `customerAddresses`."""
+    id: ID!
+    """The fields to change. Provide only what the shopper edited."""
+    input: CustomerAddressUpdateInput!
+  ): CustomerAddressUpdatePayload!
+  """
+  Remove one of the signed-in shopper's saved addresses. An address that is already gone
+  counts as removed.
+  """
+  customerAddressDelete(
+    """The CustomerAddress global id, as returned by `customerAddresses`."""
+    id: ID!
+  ): CustomerAddressDeletePayload!
+}
+
+extend type Mutation {
+  """
+  Request the cancellation of one order owned by the signed-in shopper. Checkout
+  records the request and OMS applies it afterwards, so the returned order can
+  still show the previous status.
+  """
+  customerOrderCancel(
+    """Shopper-facing order number."""
+    id: ID!
+    """The optional reason."""
+    input: CustomerOrderCancelInput!
+  ): 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!
 }
 
 """
@@ -1690,10 +1855,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
 }
@@ -1893,8 +2058,9 @@ 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.
+  Identifier for this child line, scoped to the cart's order form or to the
+  order's group (same opaque encoding as CartItem.id). Cache key only; not
+  independently mutable.
   """
   id: ID!
   """Display name as recorded on the order line."""
@@ -2097,30 +2263,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
 }
@@ -2155,26 +2323,24 @@ enum CartItemAddErrorCode {
 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."""
+  """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)."""
   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
 }
@@ -2185,12 +2351,12 @@ enum CartItemQuantityIncreaseErrorCode {
   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."""
@@ -2199,12 +2365,12 @@ enum CartItemQuantityDecreaseErrorCode {
   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."""
@@ -2297,6 +2463,11 @@ 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."""
@@ -2373,6 +2544,44 @@ type CartValidatePayload {
   userErrors: [CartValidateError!]!
 }
 
+"""Error codes for moving a cart onto the active sales channel."""
+enum CartSalesChannelSyncErrorCode {
+  """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 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."""
@@ -2492,6 +2701,10 @@ enum ShippingSimulateErrorCode {
   No active cart in context: the cartShippingSimulation query requires an x-order-form-id and never mints a cart.
   """
   MISSING_CART_CONTEXT
+  """
+  The country is not an ISO 3166-1 alpha-3 code (three capital letters). Refused before any upstream call.
+  """
+  INVALID_COUNTRY_CODE
 }
 
 """A domain error returned from the shippingSimulation query."""
@@ -2764,8 +2977,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")."""
@@ -2798,6 +3013,10 @@ enum ShippingAddressUpdateErrorCode {
   INVALID_POSTAL_CODE
   """The address is invalid."""
   INVALID_ADDRESS
+  """
+  The country is not an ISO 3166-1 alpha-3 code (three capital letters). Refused before any upstream call.
+  """
+  INVALID_COUNTRY_CODE
 }
 
 """A domain error returned from a shipping address update mutation."""
@@ -2905,6 +3124,46 @@ type Payment implements Node @cacheControl(maxAge: 0, scope: PRIVATE) {
   Not sensitive — a BIN identifies an issuer range, never a card.
   """
   selectedBin: String
+  """
+  The store's country as an ISO 3166-1 alpha-3 code (e.g. "BRA"), read from the order form's
+  store preferences. Null when the order form carries none or the value is not three capital
+  letters. It is not limited to the countries in `countries`: a store in another country gets its
+  own code and no table entry, and the API never substitutes another country's entry.
+  """
+  storeCountryCode: String
+  """
+  The countries the payment data supports and, per country, the cardholder document types it
+  accepts. A fixed table, identical in every response and independent of the cart. Order: USA,
+  BRA, CAN, MEX. Select the entry whose countryCode equals storeCountryCode.
+  """
+  countries: [PaymentCountry!]!
+}
+
+"""
+A country the payment data supports, with the cardholder document types it accepts. A
+non-normalized value object read directly off Payment.countries.
+"""
+type PaymentCountry {
+  """ISO 3166-1 alpha-3 country code (e.g. "BRA")."""
+  countryCode: String!
+  """
+  The document types a cardholder of this country can give. Masks and validation rules are not
+  carried: the client keys them on the document type.
+  """
+  documents: [PaymentCountryDocument!]!
+}
+
+"""
+One cardholder document type of a PaymentCountry, with whether it is shown and whether it is
+required. Values follow @vtex/country-forms 1.2.0 for an individual person.
+"""
+type PaymentCountryDocument {
+  """Document type id, lowercase (e.g. "cpf", "ssn", "sin", "rfc")."""
+  type: String!
+  """Whether the document field should be shown for this country."""
+  displayable: Boolean!
+  """Whether the document is required for this country."""
+  required: Boolean!
 }
 
 """
@@ -2969,11 +3228,11 @@ type PaymentMethodValidator {
   """
   Whether a cardholder document field is displayable for this method. Distinct from documentRequired.
   """
-  documentDisplayable: Boolean!
+  documentDisplayable: Boolean! @deprecated(reason: "The document type, mask and country come from Payment.countries. Storefront clients still read this flag as the merchant's per-method gate until a per-method replacement exists.")
   """
   Whether the displayed cardholder document is required. Distinct from documentDisplayable — a document can be shown without being mandatory.
   """
-  documentRequired: Boolean!
+  documentRequired: Boolean! @deprecated(reason: "The document type, mask and country come from Payment.countries. Storefront clients still read this flag as the merchant's per-method gate until a per-method replacement exists.")
 }
 
 """
@@ -3215,6 +3474,10 @@ enum PaymentBillingAddressUpdateErrorCode {
   CART_NOT_FOUND
   """sameAsDelivery is false but postalCode or country was omitted."""
   MISSING_BILLING_ADDRESS_FIELDS
+  """
+  The country is not an ISO 3166-1 alpha-3 code (three capital letters). Refused before any upstream call.
+  """
+  INVALID_COUNTRY_CODE
 }
 
 """A domain error returned from the paymentBillingAddressUpdate mutation."""
@@ -3291,13 +3554,11 @@ type PaymentStartTransactionPayload {
   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.
+  "https://mystore.vtexvault.com" — the base the browser's direct-to-gateway
+  send-payments POST appends its own path to. Always `https://{account}.vtexvault.com`,
+  derived from the request's account alone: no upstream field and no caller-supplied
+  value is an input, since this field decides where card data is sent. Null when the
+  account is not a single DNS label, and if errors occurred.
   """
   gatewayUrl: String
   """
@@ -3336,6 +3597,11 @@ succeeded.
 input PaymentGatewayCallbackInput {
   """The order group returned by paymentStartTransaction."""
   orderGroup: String!
+  """
+  The resume flag. False (the default) on the first pass; true when the shopper
+  returns from the bank's challenge page, so the callback accepts the challenge.
+  """
+  acceptChallenges: Boolean = false
 }
 
 """
@@ -3350,7 +3616,7 @@ enum PaymentGatewayCallbackErrorCode {
   """
   MISSING_TRANSACTION_COOKIES
   """
-  VTEX requires a redirect or out-of-band flow to complete this payment. Phase 2; not supported in v1.
+  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
 }
@@ -3369,6 +3635,10 @@ type PaymentGatewayCallbackPayload {
   The finalized order group, echoed back on success. Null if errors occurred.
   """
   orderId: String
+  """
+  The bank's challenge page; set only when VTEX answered 428 with a usable http(s) URL.
+  """
+  redirectUrl: String
   """Domain errors that occurred during the operation."""
   userErrors: [PaymentGatewayCallbackError!]!
 }
@@ -3385,8 +3655,9 @@ 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 charged across all installments, including any interest, in the
+  order's currency, or the request's when no seller order carries one, as the
+  order's other amounts are. Null when the settled record carries no amount.
   """
   total: Money
 }
@@ -3403,115 +3674,364 @@ type Order implements Node @cacheControl(maxAge: 0, scope: PRIVATE) {
   """
   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.
+  The purchase's payment outcome, shared by its seller orders. The banner shows this one. UNKNOWN when
+  the seller orders disagree.
+  """
+  status: OrderStatus!
+  """
+  The distinct payments of the purchase, each counted once across its seller orders. They follow the
+  seller orders sorted by order id, and within a transaction the order the order system lists them
+  in, which this API does not change. Empty when the order carries no payment.
+  """
+  payments: [OrderPayment!]!
+  """
+  Card network / payment-system display name of the first payment (e.g. "Visa", or a non-card
+  method's own name such as "Boleto Bancário"). Kept for the payment recap; prefer payments. 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.
+  Last four digits of the card used by the first payment, 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.
+  where last four is a saved-card-only field. Kept for the payment recap; prefer payments. Null for
+  a non-card method or when no payment record exists to project one from.
   """
   lastFourDigits: String
+  """Always null: the order system sends no card label."""
+  label: String @deprecated(reason: "The order system sends no card label; always null.")
   """
-  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).
+  The installment plan of the first payment. Kept for the payment recap; prefer payments. Null when
+  the settled record reports none.
   """
-  label: String
+  installment: OrderInstallment
   """
-  The installment plan this order was charged in. Null when the settled record
-  reports none.
+  Who bought, as the order recorded them at placement, not the live profile. Masked (e.g.
+  "A*** S***") when personalDataVisible is false. Null when the order carries no profile.
   """
-  installment: OrderInstallment
+  customer: OrderCustomer
+  """
+  Whether the order system returned the order's personal data unmasked: the customer, and the
+  addresses, invoice and payment details it masks under the same verdict. False means masked, and is
+  also the answer when the order system does not say.
+  """
+  personalDataVisible: Boolean!
+  """
+  The order group: the reference the shopper reads and support resolves. One per purchase, however
+  many sellers.
+  """
+  reference: String!
+  """
+  When the purchase was placed: the earliest creation date across its seller orders. Null when none
+  carries one.
+  """
+  placedAt: DateTime
+  """
+  What the purchase costs: the sum of its seller orders' totals. Null when a seller order has none.
+  """
+  total: Money
+  """
+  The purchase's money lines: each line summed across seller orders, keyed on (id, name).
+  """
+  totals: [CartTotalizer!]!
+  """
+  The purchase split by seller, one entry per seller order, sorted by orderId.
+  """
+  sellerOrders: [SellerOrder!]!
+  """
+  Every item of the purchase grouped by shipping method, channel and relative estimate, across
+  sellers; SmartCheckout uses the same key within each seller order.
+  """
+  deliveries: [OrderDelivery!]!
 }
 
 """
-The authentication methods an account enables, read before rendering a sign-in form.
+Items that arrive together: the same shipping method, channel and relative estimate.
 """
-type SessionAuthProviders {
-  """Whether classic email and password sign-in is enabled."""
-  passwordAuthentication: Boolean!
-  """Whether email access-code (passwordless) sign-in is enabled."""
-  accessKeyAuthentication: Boolean!
+type OrderDelivery @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """Encoded from the grouping key and its scope, the order group."""
+  id: ID!
+  """
+  The shipping method, as the shopper chose it: its name, channel and relative estimate. Its price
+  is one line's; use price. Null when the order system omits the method or its estimate is
+  unreadable.
+  """
+  shippingOption: OrderShippingOption
+  """
+  The group's dated promise: its latest line's, so it covers every item. Null when no line carries a
+  date.
+  """
+  estimatedDate: DateTime
+  """
+  What the group's shipping cost: the sum of its lines' shipping prices. A line without a readable
+  method adds zero, so with shippingOption null this zero is unknown, never free shipping.
+  """
+  price: Money!
+  """
+  What the group's shipping would have cost without discounts: the sum of its lines' list prices,
+  read as price is.
+  """
+  listPrice: Money!
+  """
+  Where the group ships: its first line's address. The address is not part of the grouping key: the
+  cart delivers to one address, so a group's lines share it. Each line's own is on
+  items.deliveryAddress. Masked under personalDataVisible.
+  """
+  address: Address
+  """
+  The pickup point's name: its first line's. Null unless the group is picked up.
+  """
+  pickupPointName: String
+  """The number of items in the group."""
+  itemCount: Int!
+  """The group's items, in the order of the seller orders."""
+  items: [OrderItem!]!
 }
 
 """
-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.
+The shipping method the shopper chose, as the order recorded it. Read from the order, never from the
+cart.
 """
-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
+type OrderShippingOption @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """Encoded from the order group, the line's uniqueId and the SLA id."""
+  id: ID!
   """
-  BFF-side guard: the request lacked the auth context it needed (e.g. a missing
-  authenticationToken). Not a VTEX outcome.
+  The method's name, e.g. Motoboy. The SLA id when the order system sends no name.
   """
-  MISSING_AUTH_CONTEXT
+  name: String!
+  """Delivery channel: home delivery or pickup."""
+  channel: DeliveryChannel!
+  """The method's relative estimate, e.g. 7 business days."""
+  shippingEstimate: ShippingEstimate!
+  """What this line's shipping cost. Zero when free shipping applies."""
+  price: Money!
+  """What this line's shipping would have cost without discounts."""
+  listPrice: Money!
 }
 
 """
-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.
+The payment outcome of a settled order (PRD UQ-2), mapped from the order's Checkout workflow state.
 """
-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!
+enum OrderStatus {
+  """The payment was approved, or the order has moved past approval."""
+  APPROVED
+  """The payment is not decided yet, under anti-fraud review included."""
+  PENDING
+  """The payment was denied, or the order was cancelled."""
+  DENIED
+  """A state the page does not classify. It asserts no outcome."""
+  UNKNOWN
+}
+
+"""One payment of a settled purchase. No id: it lives inside its Order."""
+type OrderPayment @cacheControl(maxAge: 0, scope: PRIVATE) {
   """
-  The client profile projected from the refreshed order form; the entity always
-  resolves, its fields are null when unset.
+  Card network / payment-system display name, e.g. "Visa". Null when the order system sends none.
   """
-  clientProfile: ClientProfile!
+  network: String
   """
-  The client preferences projected from the refreshed order form; the entity
-  always resolves, its fields are null when unset.
+  Last four digits of the card, when the payment method was a card. Never the card number.
   """
-  clientPreferences: ClientPreferences!
-  """Typed login-attempt failures. Empty on success."""
-  userErrors: [SessionError!]!
-}
-
-"""The result of requesting an email access code."""
-type SessionRequestAccessCodePayload {
+  lastFourDigits: String
   """
-  Opaque token to hand back to sessionValidateAccessCode. Null when the request
-  failed.
+  The installment plan of this payment. Null when the settled record reports none.
   """
-  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!
+  installment: OrderInstallment
   """
-  The shopper's password. Proxied to VTEX ID over TLS, never logged or persisted.
+  What this payment charged, in full: never one instalment. Null only if the order system omits it,
+  which it does not today.
   """
-  password: String!
+  value: Money
+}
+
+"""One seller's part of a purchase: its own seller, totals and items."""
+type SellerOrder @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """Encoded from orderId."""
+  id: ID!
+  """The seller order's number, e.g. 1667094470146-01."""
+  orderId: String!
+  """
+  The seller fulfilling this order. Null only when neither sellers nor any readable item names one.
+  """
+  seller: CartSellerRef
+  """
+  What this seller order costs. Null when the order system does not send it.
+  """
+  total: Money
+  """This seller order's money lines. The cart's own totalizer type."""
+  totals: [CartTotalizer!]!
+  """
+  Every line of this seller order. Children of a composition nest under their parent.
+  """
+  items: [OrderItem!]!
+}
+
+"""
+One purchased line of a settled order. The fields mean what they mean on CartItem.
+"""
+type OrderItem @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """Encoded from the order group and the line's uniqueId."""
+  id: ID!
+  """
+  The SKU as the cart shows it: name, image, seller, availability and variation.
+  """
+  variant: CartVariant!
+  """
+  The product the SKU belongs to: title, detail URL, categories and brand.
+  """
+  product: CartProduct!
+  """How many units were bought."""
+  quantity: Int!
+  """The unit price at placement, before discounts."""
+  price: Money!
+  """Zero when the line had no list price."""
+  listPrice: Money!
+  """The unit price the shopper paid."""
+  sellingPrice: Money!
+  """The line's own total, as the cart computes it."""
+  ownTotal: Money!
+  """The line's own total plus its compositions'."""
+  total: Money!
+  """Whether the line is a gift."""
+  gift: Boolean!
+  """The featured promotions that discounted this line."""
+  discounts: [CartItemDiscount!]!
+  """The values the shopper entered for the line's input assemblies."""
+  customizations: [CartItemCustomization!]!
+  """The add-on services and bundle children nested under this line."""
+  compositions: [CartItemComposition!]!
+  """
+  The shipping method the shopper chose for this line. Null when the order system omits it or its
+  estimate is unreadable.
+  """
+  selectedShippingOption: OrderShippingOption
+  """
+  Where this line ships: the delivery address, or the pickup point's. Masked under
+  personalDataVisible.
+  """
+  deliveryAddress: Address
+  """
+  The pickup point's name, e.g. "RJ - Botafogo Praia Shopping". Null unless the line is picked up.
+  """
+  pickupPointName: String
+  """The dated promise. Null when the order system has not set one."""
+  estimatedDeliveryDate: DateTime
+}
+
+"""
+The customer of a settled order, as the order recorded them at placement. The same fields as
+ClientProfile, which is the live order form's profile.
+"""
+type OrderCustomer @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """Email address."""
+  email: String
+  """First name."""
+  firstName: String
+  """Last name."""
+  lastName: String
+  """Phone number."""
+  phone: String
+  """Identity document number."""
+  document: String
+}
+
+"""
+The address fields a postal code resolves to. Each is null when the platform
+left it blank.
+"""
+type PostalCodeAddress @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """The city, as the platform names it."""
+  city: String
+  """The state or region, as the platform codes it (`SP`, `NY`)."""
+  state: String
+  """The street. Null where the platform resolves codes to an area only."""
+  street: String
+  """The neighborhood. Null where the platform resolves none."""
+  neighborhood: String
+}
+
+"""
+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."""
@@ -3597,7 +4117,7 @@ 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).
+  by a global id (no id argument, no CustomerProfile entry in Query.node).
   """
   id: ID!
   """Given name. Null when unset."""
@@ -3689,3 +4209,733 @@ type CustomerProfileUpdatePayload {
   """Typed, expected write failures. Empty on success."""
   userErrors: [CustomerProfileError!]!
 }
+
+"""
+An address the shopper saved to their account. Read from the shopper's own
+profile, never through a cart. Every field it shares with checkout's Address is
+spelled the same way.
+"""
+type CustomerAddress implements Node @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """
+  Global id. Resolves through Query.node only inside the signed-in shopper's own
+  addresses; any other id resolves to null.
+  """
+  id: ID!
+  """
+  ISO 3166-1 alpha-3 country code, as stored. Null when the stored address has
+  none, as an address another system wrote can; it is listed so the shopper can
+  still see and remove it.
+  """
+  country: String
+  """Who receives deliveries at this address. Null when unset."""
+  recipientName: String
+  """Street name. Null when unset."""
+  street: String
+  """Street number. Null when unset."""
+  number: String
+  """Additional address detail (apartment, suite, etc.). Null when unset."""
+  complement: String
+  """Neighborhood or district. Null when unset."""
+  neighborhood: String
+  """City. Null when unset."""
+  city: String
+  """State or province code. Null when unset."""
+  state: String
+  """Postal code, as stored. Null when unset."""
+  postalCode: String
+  """A landmark that helps find the address. Null when unset."""
+  reference: String
+}
+
+"""
+The signed-in shopper's saved addresses, held in one object so a client can cache
+and subscribe to the list. It takes no argument and reads only the shopper's own
+list. Not resolvable through Query.node.
+"""
+type CustomerAddressBook @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """
+  Stable identity for cache normalization, the same for every request of the
+  shopper. Not a Relay Node ID.
+  """
+  id: ID!
+  """
+  Every saved address, the same list `customerAddresses` returns. Empty when the
+  shopper has none.
+  """
+  addresses: [CustomerAddress!]!
+}
+
+"""
+A new saved address. `country` is required; every other field is optional to the
+schema, and the country's rules say which ones it needs. A field that is omitted,
+`null`, or an empty string is not written.
+"""
+input CustomerAddressCreateInput {
+  """
+  ISO 3166-1 alpha-3 country code. The store must ship to it. Trimmed and upper-cased.
+  """
+  country: String!
+  """Who receives deliveries at this address."""
+  recipientName: String
+  """Street name."""
+  street: String
+  """Street number."""
+  number: String
+  """Additional address detail (apartment, suite, etc.)."""
+  complement: String
+  """Neighborhood or district."""
+  neighborhood: String
+  """City."""
+  city: String
+  """State or province code."""
+  state: String
+  """Postal code. Stored in the country's masked form once it is valid."""
+  postalCode: String
+  """A landmark that helps find the address."""
+  reference: String
+}
+
+"""
+Changes to a saved address. Omit a field, or send `null`, to keep it; send an empty
+string to erase it. The country cannot change.
+"""
+input CustomerAddressUpdateInput {
+  """
+  Who receives deliveries at this address. Omit to leave unchanged; empty string to erase.
+  """
+  recipientName: String
+  """Street name. Omit to leave unchanged; empty string to erase."""
+  street: String
+  """Street number. Omit to leave unchanged; empty string to erase."""
+  number: String
+  """
+  Additional address detail (apartment, suite, etc.). Omit to leave unchanged; empty string to erase.
+  """
+  complement: String
+  """
+  Neighborhood or district. Omit to leave unchanged; empty string to erase.
+  """
+  neighborhood: String
+  """City. Omit to leave unchanged; empty string to erase."""
+  city: String
+  """
+  State or province code. Omit to leave unchanged; empty string to erase.
+  """
+  state: String
+  """
+  Postal code. Omit to leave unchanged; empty string to erase. Stored in the country's masked form once it is valid.
+  """
+  postalCode: String
+  """
+  A landmark that helps find the address. Omit to leave unchanged; empty string to erase.
+  """
+  reference: String
+}
+
+"""
+A typed, expected failure of an address write, or of the lookup that precedes it.
+"""
+type CustomerAddressError {
+  """Machine-readable code for the failure."""
+  code: CustomerAddressErrorCode!
+  """
+  A safe, fixed message. Never echoes a submitted value, an id, or a key.
+  """
+  message: String!
+  """
+  The field the failure is about. Null when it is about the address as a whole.
+  """
+  field: CustomerAddressField
+}
+
+"""The set of expected, typed address-write failure codes."""
+enum CustomerAddressErrorCode {
+  """
+  The id is malformed, names another entity type, or is not one of the shopper's saved
+  addresses. These cases are indistinguishable.
+  """
+  NOT_FOUND
+  """The country's rules require this field and it is empty."""
+  MISSING_REQUIRED_FIELD
+  """
+  The value is not accepted: a bad format, a value outside the country's options, a value
+  that is too long, or a country that is not three letters. With no field, the profile
+  service refused the address and does not say why.
+  """
+  INVALID_VALUE
+  """The store does not ship to the country."""
+  UNSUPPORTED_COUNTRY
+}
+
+"""The address field a failure is about."""
+enum CustomerAddressField {
+  """The `country` field."""
+  COUNTRY
+  """The `recipientName` field."""
+  RECIPIENT_NAME
+  """The `street` field."""
+  STREET
+  """The `number` field."""
+  NUMBER
+  """The `complement` field."""
+  COMPLEMENT
+  """The `neighborhood` field."""
+  NEIGHBORHOOD
+  """The `city` field."""
+  CITY
+  """The `state` field."""
+  STATE
+  """The `postalCode` field."""
+  POSTAL_CODE
+  """The `reference` field."""
+  REFERENCE
+}
+
+"""The result of creating a saved address."""
+type CustomerAddressCreatePayload {
+  """The address as written. Null when `userErrors` is not empty."""
+  customerAddress: CustomerAddress
+  """Typed, expected failures, one per refused field. Empty on success."""
+  userErrors: [CustomerAddressError!]!
+}
+
+"""The result of updating a saved address."""
+type CustomerAddressUpdatePayload {
+  """
+  The address as written, or as stored when the input provided no field. Null when
+  `userErrors` is not empty.
+  """
+  customerAddress: CustomerAddress
+  """Typed, expected failures, one per refused field. Empty on success."""
+  userErrors: [CustomerAddressError!]!
+}
+
+"""The result of deleting a saved address."""
+type CustomerAddressDeletePayload {
+  """
+  The id of the deleted address, to evict it from a client cache. Null when `userErrors`
+  is not empty.
+  """
+  deletedCustomerAddressId: ID
+  """Typed, expected failures. Empty on success."""
+  userErrors: [CustomerAddressError!]!
+}
+
+"""
+The countries the store ships to, read from the platform's freight
+configuration. Store-level and identical for every shopper.
+"""
+type ShippingCountries @cacheControl(maxAge: 3600, scope: PUBLIC) {
+  """
+  ISO 3166-1 alpha-3 codes, upper-case, without duplicates, in the order the
+  platform lists them. Never empty: when the freight configuration declares no
+  country, this holds the sales channel's country and `source` says so.
+  """
+  countries: [String!]!
+  """
+  Where `countries` came from. A consumer that judges an address against the
+  list must not do so when this is `SALES_CHANNEL_FALLBACK`.
+  """
+  source: ShippingCountriesSource!
+}
+
+"""The origin of a shipping-country list."""
+enum ShippingCountriesSource {
+  """The store's freight configuration declares these countries."""
+  PLATFORM
+  """
+  The freight configuration declares none, so the list is the sales channel's
+  country alone. It is a guess, not a declared delivery area.
+  """
+  SALES_CHANNEL_FALLBACK
+}
+
+"""A placed order owned by the signed-in shopper."""
+type CustomerOrder implements Node @cacheControl(maxAge: 0, scope: PRIVATE) {
+  """Global Node id. Refetch it with `node` or `customerOrder`."""
+  id: ID!
+  """
+  Shopper-facing order number. The same value the list carries as its `id`.
+  """
+  orderNumber: String!
+  """Raw OMS status code."""
+  status: String!
+  """Whether OMS currently permits whole-order cancellation."""
+  allowCancellation: Boolean!
+  """Timestamp when the order was placed."""
+  placedAt: DateTime
+  """Grand total recorded on the order."""
+  total: Money!
+  """Itemized totals recorded on the order."""
+  totals: [CustomerOrderTotal!]!
+  """Product lines recorded on the order."""
+  items: [CustomerOrderItem!]!
+  """Product lines grouped by their selected delivery option."""
+  deliveryOptions: [CustomerOrderDeliveryOption!]!
+  """Payments recorded on active and historical transactions."""
+  payments: [CustomerOrderPayment!]!
+  """Whether every package has a recorded delivery confirmation."""
+  isAllDelivered: Boolean
+  """Earliest estimated delivery timestamp."""
+  shippingEstimatedDateMin: DateTime
+  """Latest estimated delivery timestamp."""
+  shippingEstimatedDateMax: DateTime
+  """Timestamp when the order was invoiced."""
+  invoiceDate: DateTime
+  """
+  Order delivery channel. The order-level value when OMS supplies it, otherwise
+  the channel every logistics entry agrees on. Null when those entries differ.
+  """
+  selectedDeliveryChannel: String
+  """
+  Completion resolved once for this order, with the inputs the single-order payload carries. The list also passes courierStatusFinished, which this payload does not.
+  """
+  completion: CustomerOrderCompletion!
+  """The progress stage this order is in."""
+  progress: CustomerOrderProgress!
+}
+
+"""
+One of the four progress stages a shopper sees. Approval is not a stage.
+"""
+enum CustomerOrderProgressStage {
+  """The order was placed and payment has not started."""
+  PLACED
+  """Payment is pending, awaiting authorization, or denied."""
+  PAYMENT
+  """Payment was approved and the order is being prepared."""
+  PROCESSING
+  """The order was invoiced and is on its way or ready for pickup."""
+  SHIPPING
+}
+
+"""Progress stage resolved once for one order."""
+type CustomerOrderProgress {
+  """The stage the order is in. A cancelled order stays on PAYMENT."""
+  stage: CustomerOrderProgressStage!
+  """True when payment was denied or the order was cancelled."""
+  paymentFailed: Boolean!
+  """True when the order is cancelled or a cancellation was requested."""
+  cancelled: Boolean!
+}
+
+"""One total line recorded on a placed order."""
+type CustomerOrderTotal {
+  """Stable total category code."""
+  id: String!
+  """Upstream total name."""
+  name: String!
+  """Monetary value of this total line."""
+  value: Money!
+}
+
+"""One product line recorded on a placed order."""
+type CustomerOrderItem {
+  """Stable line identifier within the order."""
+  id: ID!
+  """Product name recorded at purchase time."""
+  name: String!
+  """Purchased quantity."""
+  quantity: Int!
+  """Product image recorded at purchase time."""
+  image: Image
+  """Base unit price recorded on the line."""
+  price: Money
+  """Unit list price recorded on the line."""
+  listPrice: Money
+  """Effective unit selling price recorded on the line."""
+  sellingPrice: Money
+  """
+  Line total from the recorded selling price and quantity. Null when that price is absent.
+  """
+  total: Money
+  """
+  Tax recorded on the line. Null when OMS omitted it. A recorded zero is kept.
+  """
+  tax: Money
+  """Custom values recorded on the line."""
+  customFields: [CustomerOrderItemCustomField!]!
+}
+
+"""A custom value recorded on an order line."""
+type CustomerOrderItemCustomField {
+  """Custom field name."""
+  name: String!
+  """Custom field value as recorded on the order."""
+  value: String!
+}
+
+"""Products that share one selected delivery option."""
+type CustomerOrderDeliveryOption {
+  """Selected service-level agreement name."""
+  selectedSla: String
+  """Address identifier recorded by OMS."""
+  addressId: String
+  """Delivery or pickup channel."""
+  deliveryChannel: String
+  """Estimated delivery timestamp for this option."""
+  shippingEstimateDate: DateTime
+  """Historical address recorded on the order."""
+  address: CustomerOrderAddress
+  """Product lines assigned to this option."""
+  items: [CustomerOrderItem!]!
+}
+
+"""Historical delivery address recorded on an order."""
+type CustomerOrderAddress {
+  """Recipient name."""
+  receiverName: String
+  """Postal code."""
+  postalCode: String
+  """City."""
+  city: String
+  """State or region."""
+  state: String
+  """ISO country code."""
+  country: String
+  """Street."""
+  street: String
+  """Street number."""
+  number: String
+  """Neighborhood."""
+  neighborhood: String
+  """Address complement."""
+  complement: String
+  """Address reference."""
+  reference: String
+}
+
+"""One payment recorded on a placed order."""
+type CustomerOrderPayment {
+  """Shopper-facing payment method name."""
+  methodName: String
+  """
+  Last four digits recorded on the payment. Null when OMS omitted them or sent a blank.
+  """
+  lastDigits: String
+  """Amount charged through this payment."""
+  amount: Money!
+  """Number of installments."""
+  installments: Int
+  """Gift-card redemption code when this payment used one."""
+  redemptionCode: String
+  """Bank-invoice number already recorded on the payment."""
+  bankInvoiceNumber: String
+  """Existing bank-invoice print URL."""
+  bankInvoicePrintUrl: URI
+}
+
+"""Which slice of the shopper's orders to read."""
+enum CustomerOrdersView {
+  """Every order in the narrowed route result."""
+  ALL
+  """Orders the completion rule places in ongoing."""
+  ONGOING
+  """Orders the completion rule places in completed."""
+  COMPLETED
+  """Orders the completion rule places in cancelled."""
+  CANCELLED
+}
+
+"""The view resolved for one list order."""
+enum CustomerOrderCompletionView {
+  """The order is still open."""
+  ONGOING
+  """The order has reached the shopper, or the shipment window has passed."""
+  COMPLETED
+  """The cancellation has finished."""
+  CANCELLED
+}
+
+"""Label id for the catalogue. The catalogue owns the sentence."""
+enum CustomerOrderCompletionLabel {
+  """A finished cancellation."""
+  CANCELLED
+  """A cancellation that was requested and has not finished."""
+  CANCELLATION_REQUESTED
+  """An order that is not yet shipped."""
+  IN_PROGRESS
+  """Delivery was confirmed."""
+  DELIVERED
+  """Shipped, or completed from the estimate or the invoice period."""
+  SHIPPED
+  """Ready for the shopper to collect."""
+  READY_FOR_PICKUP
+  """Pickup collection was confirmed."""
+  COLLECTED
+}
+
+"""View and label resolved once for one list order."""
+type CustomerOrderCompletion {
+  """The view this order belongs to."""
+  view: CustomerOrderCompletionView!
+  """The catalogue label id."""
+  label: CustomerOrderCompletionLabel!
+}
+
+"""One order on the shopper's list. The detail document is CustomerOrder."""
+type CustomerOrderListItem {
+  """Shopper-facing order number. Pass this value to customerOrder."""
+  id: ID!
+  """Raw OMS status code. Empty when the list entry omits it."""
+  status: String!
+  """When the order was placed."""
+  placedAt: DateTime
+  """
+  Grand total. Null when the list entry omits the value or the currency code.
+  """
+  total: Money
+  """Sum of line quantities. Null when the list entry omits it."""
+  itemCount: Int
+  """Completion resolved once for this order."""
+  completion: CustomerOrderCompletion!
+  """Whether every package has a recorded delivery confirmation."""
+  isAllDelivered: Boolean
+  """Earliest estimated delivery timestamp."""
+  shippingEstimatedDateMin: DateTime
+  """Latest estimated delivery timestamp."""
+  shippingEstimatedDateMax: DateTime
+  """Timestamp when the order was invoiced."""
+  invoiceDate: DateTime
+  """Delivery channel when the list entry carries it."""
+  selectedDeliveryChannel: String
+}
+
+"""An edge in the shopper's order list."""
+type CustomerOrderListItemEdge {
+  """Resume cursor for the order after this one."""
+  cursor: Cursor!
+  """The list order."""
+  node: CustomerOrderListItem!
+}
+
+"""One page of the signed-in shopper's orders."""
+type CustomerOrdersConnection {
+  """Orders on this page."""
+  edges: [CustomerOrderListItemEdge!]!
+  """Cursors for the page."""
+  pageInfo: PageInfo!
+  """Route total for ALL. Classified count so far for a filtered view."""
+  totalCount: Int!
+  """True only when a filtered walk stopped at 20 upstream pages."""
+  totalIncomplete: Boolean!
+}
+
+"""Criteria applied before the page is returned."""
+input CustomerOrdersFilterInput {
+  """View to return. Defaults to every order."""
+  view: CustomerOrdersView = ALL
+  """Free-text term sent to the order route."""
+  text: String
+  """Inclusive start of the placed-date range, as an instant."""
+  placedFrom: DateTime
+  """Inclusive end of the placed-date range, as an instant."""
+  placedTo: DateTime
+}
+
+"""What the shopper submits with a whole-order cancellation."""
+input CustomerOrderCancelInput {
+  """Optional reason the merchant keeps. Trimmed; at most 500 characters."""
+  reason: String
+}
+
+"""The set of expected, typed cancellation failure codes."""
+enum CustomerOrderCancelErrorCode {
+  """
+  Checkout refused the cancellation. The order is past the point where the shopper
+  can cancel it, or a cancellation was already requested.
+  """
+  ORDER_NOT_CANCELLABLE
+  """
+  No order the signed-in shopper can see has this id. A missing id and someone
+  else's id are not distinguished.
+  """
+  NOT_FOUND
+}
+
+"""A typed, expected failure of a cancellation."""
+type CustomerOrderCancelError {
+  """Machine-readable code for the failure."""
+  code: CustomerOrderCancelErrorCode!
+  """A fixed message. Never echoes the upstream response."""
+  message: String!
+}
+
+"""The result of a cancellation request."""
+type CustomerOrderCancelPayload {
+  """
+  The order re-read after checkout accepted the request. Null on a user error, and
+  null when the re-read failed after an accepted request.
+  """
+  customerOrder: CustomerOrder
+  """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
+}