CartBuyerIdentityUpdatePayload

Payload returned by the cartBuyerIdentityUpdate mutation. This object contains the updated cart information along with any user errors that occurred during the update process.

Type Definition

type CartBuyerIdentityUpdatePayload {
  cart: Cart!
  userErrors: [UserError]!
}

Fields

Relationships

• cart: Links to the Cart object representing the current state of the cart after the buyer identity has been updated.
• userErrors: An array of UserError objects providing detailed error information if the update operation encountered issues.

Usage Examples

Basic Query

mutation {
  cartBuyerIdentityUpdate(cartId: "eyJhbGciOiJIUzI1NiJ9...", buyerIdentity: { email: "jane.doe@example.com" }) {
    cart {
      id
      buyerIdentity {
        email
      }
      lines(first: 5) {
        edges {
          node {
            id
            quantity
            merchandise {
              ... on ProductVariant {
                id
                title
              }
            }
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Field Selection

mutation {
  cartBuyerIdentityUpdate(cartId: "eyJhbGciOiJIUzI1NiJ9...", buyerIdentity: { phone: "+1234567890" }) {
    cart {
      id
      buyerIdentity {
        phone
      }
      attributes {
        key
        value
      }
    }
    userErrors {
      message
    }
  }
}

Nested Queries

mutation {
  cartBuyerIdentityUpdate(cartId: "eyJhbGciOiJIUzI1NiJ9...", buyerIdentity: { customerAccessToken: "abcd1234token" }) {
    cart {
      id
      buyerIdentity {
        customerAccessToken
        email
      }
      lines(first: 3) {
        edges {
          node {
            id
            quantity
            merchandise {
              ... on ProductVariant {
                id
                price {
                  amount
                  currencyCode
                }
              }
            }
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Filtering and Sorting

The CartBuyerIdentityUpdatePayload type itself does not support filtering or sorting directly. However, you can apply filtering and sorting on nested fields such as lines within the cart object.

Example: Sorting cart lines by quantity descending

mutation {
  cartBuyerIdentityUpdate(cartId: "eyJhbGciOiJIUzI1NiJ9...", buyerIdentity: { email: "john.smith@example.com" }) {
    cart {
      id
      lines(first: 10, sortKey: QUANTITY, reverse: true) {
        edges {
          node {
            id
            quantity
            merchandise {
              ... on ProductVariant {
                id
                title
              }
            }
          }
        }
      }
    }
    userErrors {
      message
    }
  }
}

Implements

This type does not implement any interfaces.

Connections

• The cart field connects to the Cart object type, which represents the shopping cart and includes detailed information such as line items, buyer identity, and attributes.
• The userErrors field connects to a list of UserError objects, which provide granular error details related to the mutation operation.

Related Types

• Cart: Represents the shopping cart, including buyer identity, line items, and other cart details.
• UserError: Provides information about errors encountered during mutation operations, including the error message and the field related to the error.

Best Practices

• Always check the userErrors field after performing the cartBuyerIdentityUpdate mutation to handle any errors gracefully.
• Use specific field selections on the cart object to minimize response size and improve query performance.
• When updating buyer identity, provide only the necessary fields (e.g., email, phone, customerAccessToken) to avoid unintended data overwrites.
• Use pagination and sorting on nested fields like lines to efficiently manage large carts.
• Handle nullability carefully; both cart and userErrors are non-nullable, but userErrors may be an empty array if no errors occurred.

Notes

• The cartBuyerIdentityUpdate mutation and its payload currently require no authentication, but this may change in future API versions.
• The cart field reflects the cart state immediately after the buyer identity update, ensuring clients have the latest data.
• The userErrors array provides actionable feedback for client-side validation and error handling.
• To optimize performance, request only the fields you need from the cart object.
• Nested queries allow you to traverse relationships such as cart lines and merchandise details in a single request, reducing the number of round trips to the server.