cartBuyerIdentityUpdate

Updates the buyer identity for an existing cart.

Mutation Structure


mutation cartBuyerIdentityUpdate($cartId: String!, $buyerIdentity: BuyerIdentityInput) {
  cartBuyerIdentityUpdate(cartId: $cartId, buyerIdentity: $buyerIdentity) {
    cart {
      id
      buyerIdentity {
        email
        phone
        countryCode
      }
      # Additional cart fields can be queried here as needed
    }
    userErrors {
      field
      message
      code
    }
  }
}

Input Arguments

Argument	Type	Description	Required	Validation / Notes
`cartId`	`String!`	The ID of the cart to update the buyer identity for	Yes	Must be a valid cart identifier (JWT token)
`buyerIdentity`	`BuyerIdentityInput`	The new buyer identity for the cart	No	Fields inside are optional; see below

BuyerIdentityInput Fields

Field	Type	Description	Required	Validation / Notes
`email`	`String`	The email address of the buyer	No	Should be a valid email format if provided
`phone`	`String`	The phone number of the buyer	No	Should be a valid phone number format if provided
`countryCode`	`String`	The country code for the buyer (ISO 3166-1 alpha-2)	No	Must be a valid ISO 3166-1 alpha-2 country code

Return Type

CartBuyerIdentityUpdatePayload

cart (Cart!): The updated cart object reflecting the new buyer identity.
userErrors ([UserError]!): A list of errors that occurred during the update operation. Each error contains:
- field (optional): The input field related to the error.
- message: A descriptive error message.
- code (optional): A machine-readable error code.

Examples

Basic Mutation


mutation {
  cartBuyerIdentityUpdate(
    cartId: "eyJhbGciOiJIUzI1NiJ9..."
    buyerIdentity: {
      email: "jane.doe@example.com"
    }
  ) {
    cart {
      id
      buyerIdentity {
        email
        phone
        countryCode
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}

Advanced Mutation


mutation UpdateCartBuyerIdentity($cartId: String!, $buyerIdentity: BuyerIdentityInput) {
  cartBuyerIdentityUpdate(cartId: $cartId, buyerIdentity: $buyerIdentity) {
    cart {
      id
      buyerIdentity {
        email
        phone
        countryCode
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}

Variables:


{
  "cartId": "eyJhbGciOiJIUzI1NiJ9...",
  "buyerIdentity": {
    "email": "john.smith@example.com",
    "phone": "+14155552671",
    "countryCode": "US"
  }
}

Input Validation


mutation {
  cartBuyerIdentityUpdate(
    cartId: "eyJhbGciOiJIUzI1NiJ9..."
    buyerIdentity: {
      email: "invalid-email-format",
      countryCode: "USA"
    }
  ) {
    cart {
      id
      buyerIdentity {
        email
        phone
        countryCode
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}

cURL Example


curl -X POST https://www.mystoreurl.com/graphql/0.8.0/ \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation cartBuyerIdentityUpdate($cartId: String!, $buyerIdentity: BuyerIdentityInput) { cartBuyerIdentityUpdate(cartId: $cartId, buyerIdentity: $buyerIdentity) { cart { id buyerIdentity { email phone countryCode } } userErrors { field message code } } }",
    "variables": {
      "cartId": "eyJhbGciOiJIUzI1NiJ9...",
      "buyerIdentity": {
        "email": "alice@example.com",
        "phone": "+442071838750",
        "countryCode": "GB"
      }
    }
  }'

JavaScript Example


async function updateCartBuyerIdentity(cartId, buyerIdentity) {
  const query = `
    mutation cartBuyerIdentityUpdate($cartId: String!, $buyerIdentity: BuyerIdentityInput) {
      cartBuyerIdentityUpdate(cartId: $cartId, buyerIdentity: $buyerIdentity) {
        cart {
          id
          buyerIdentity {
            email
            phone
            countryCode
          }
        }
        userErrors {
          field
          message
          code
        }
      }
    }
  `;
 
  const variables = { cartId, buyerIdentity };
 
  try {
    const response = await fetch('https://www.mystoreurl.com/graphql/0.8.0/', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ query, variables }),
    });
 
    const result = await response.json();
 
    if (result.data.cartBuyerIdentityUpdate.userErrors.length) {
      console.error('User errors:', result.data.cartBuyerIdentityUpdate.userErrors);
      return null;
    }
 
    return result.data.cartBuyerIdentityUpdate.cart;
  } catch (error) {
    console.error('Network or server error:', error);
    return null;
  }
}
 
// Example usage:
updateCartBuyerIdentity("eyJhbGciOiJIUzI1NiJ9...", {
  email: "bob@example.com",
  phone: "+15555555555",
  countryCode: "CA"
}).then(cart => {
  if (cart) {
    console.log('Updated cart buyer identity:', cart.buyerIdentity);
  }
});

Response Format

The mutation returns a CartBuyerIdentityUpdatePayload object containing:

cart: The updated cart object with the new buyer identity information.
userErrors: An array of UserError objects describing any issues encountered during the update.

Example successful response:


{
  "data": {
    "cartBuyerIdentityUpdate": {
      "cart": {
        "id": "eyJhbGciOiJIUzI1NiJ9...",
        "buyerIdentity": {
          "email": "jane.doe@example.com",
          "phone": null,
          "countryCode": null
        }
      },
      "userErrors": []
    }
  }
}

Example response with validation errors:


{
  "data": {
    "cartBuyerIdentityUpdate": {
      "cart": null,
      "userErrors": [
        {
          "field": ["buyerIdentity", "email"],
          "message": "Invalid email format",
          "code": "INVALID_EMAIL"
        },
        {
          "field": ["buyerIdentity", "countryCode"],
          "message": "Country code must be a valid ISO 3166-1 alpha-2 code",
          "code": "INVALID_COUNTRY_CODE"
        }
      ]
    }
  }
}

Error Handling

Common error scenarios include:

Invalid cartId: If the provided cart ID is malformed or does not correspond to an existing cart, the mutation will return a user error indicating the cart was not found.
Invalid input values: Errors such as invalid email format or invalid country code will be returned in the userErrors array with descriptive messages and error codes.
Missing required cartId argument: The mutation will fail if cartId is not provided.

Example error response for invalid cart ID:


{
  "data": {
    "cartBuyerIdentityUpdate": {
      "cart": null,
      "userErrors": [
        {
          "field": ["cartId"],
          "message": "Cart not found",
          "code": "NOT_FOUND"
        }
      ]
    }
  }
}

Example validation error response:


{
  "data": {
    "cartBuyerIdentityUpdate": {
      "cart": null,
      "userErrors": [
        {
          "field": ["buyerIdentity", "email"],
          "message": "Invalid email format",
          "code": "INVALID_EMAIL"
        }
      ]
    }
  }
}

Authentication

This API currently does not require authentication. However, authentication requirements may be introduced in future versions. Monitor API updates for any changes to authentication requirements.

Side Effects

Updating the buyer identity on a cart may affect downstream processes such as tax calculation, shipping options, and marketing communications.
Ensure that the cartId corresponds to an active cart; otherwise, the mutation will return an error.
Partial updates are supported; you can provide any subset of email, phone, and countryCode in the buyerIdentity input.
This mutation modifies the state of the cart and should be used with care to avoid unintended buyer identity changes.

Authentication Requirements

No authentication is currently required to perform this mutation. This may change in future API versions.

BuyerIdentityInput
Input object containing buyer identity fields: email, phone, countryCode.
CartBuyerIdentityUpdatePayload
Payload returned by the mutation containing the updated cart and any userErrors.
UserError
Object representing an error related to user input, including field, message, and code.
Cart
Represents the shopping cart object, including buyer identity information.

Notes

The cartId must be provided as a JWT token string representing the cart.
The countryCode must conform to ISO 3166-1 alpha-2 codes (e.g., “US”, “GB”, “CA”).
Email and phone fields are optional but should be valid if provided.
Rate limiting may apply to mutation requests; handle 429 Too Many Requests HTTP responses gracefully.
Use GraphQL variables to improve query reusability and security.
Always check the userErrors array in the response to handle validation and business logic errors properly.