cartLinesUpdate
Updates merchandise lines in an existing cart.
Mutation Structure
mutation cartLinesUpdate($cartId: String!, $lines: [CartLinesUpdateInput]!) {
cartLinesUpdate(cartId: $cartId, lines: $lines) {
cart {
id
lines {
id
quantity
customizations {
id
name
value
}
}
totalQuantity
updatedAt
}
userErrors {
field
message
code
}
}
}
Input Arguments
Argument | Type | Description | Required | Validation |
---|---|---|---|---|
cartId | String! | The ID of the cart to update lines in | Yes | Must be a valid cart identifier |
lines | [CartLinesUpdateInput]! | List of merchandise lines to update in the cart | Yes | Each line must include id and quantity |
CartLinesUpdateInput Fields
Field | Type | Description | Required | Validation |
---|---|---|---|---|
id | Int! | The ID of the cart line item to update | Yes | Must correspond to an existing line item in the cart |
quantity | Int! | The quantity of the merchandise item to update | Yes | Must be a positive integer |
customizations | [CustomizationGroupOptionInput] | List of customizations for the merchandise item | No | Optional; each customization must be valid |
Return Type
The mutation returns a CartLinesUpdatePayload
object containing:
cart
(Cart!
): The updated cart object after applying the line updates.userErrors
([UserError]!
): A list of errors encountered during the update operation. Each error includes the affected field, an error message, and an error code.
Examples
Basic Mutation
mutation {
cartLinesUpdate(
cartId: "eyJhbGciOiJIUzI1NiJ9...",
lines: [
{ id: 12345, quantity: 2 }
]
) {
cart {
id
lines {
id
quantity
}
totalQuantity
}
userErrors {
field
message
code
}
}
}
Advanced Mutation
mutation {
cartLinesUpdate(
cartId: "eyJhbGciOiJIUzI1NiJ9...",
lines: [
{
id: 12345,
quantity: 3,
customizations: [
{ id: 1, name: "Color", value: "Red" },
{ id: 2, name: "Size", value: "M" }
]
},
{
id: 67890,
quantity: 1
}
]
) {
cart {
id
lines {
id
quantity
customizations {
id
name
value
}
}
totalQuantity
updatedAt
}
userErrors {
field
message
code
}
}
}
Input Validation
mutation {
cartLinesUpdate(
cartId: "eyJhbGciOiJIUzI1NiJ9...",
lines: [
{ id: 12345, quantity: 0 }
]
) {
cart {
id
}
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 cartLinesUpdate($cartId: String!, $lines: [CartLinesUpdateInput]!) { cartLinesUpdate(cartId: $cartId, lines: $lines) { cart { id lines { id quantity } totalQuantity } userErrors { field message code } } }",
"variables": {
"cartId": "eyJhbGciOiJIUzI1NiJ9...",
"lines": [
{ "id": 12345, "quantity": 2 }
]
}
}'
JavaScript Example
async function updateCartLines() {
const query = `
mutation cartLinesUpdate($cartId: String!, $lines: [CartLinesUpdateInput]!) {
cartLinesUpdate(cartId: $cartId, lines: $lines) {
cart {
id
lines {
id
quantity
customizations {
id
name
value
}
}
totalQuantity
updatedAt
}
userErrors {
field
message
code
}
}
}
`;
const variables = {
cartId: "eyJhbGciOiJIUzI1NiJ9...",
lines: [
{
id: 12345,
quantity: 3,
customizations: [
{ id: 1, name: "Color", value: "Red" },
{ id: 2, name: "Size", value: "M" }
]
}
]
};
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.cartLinesUpdate.userErrors.length > 0) {
console.error("User errors:", result.data.cartLinesUpdate.userErrors);
} else {
console.log("Updated cart:", result.data.cartLinesUpdate.cart);
}
} catch (error) {
console.error("Network or server error:", error);
}
}
updateCartLines();
Response Format
The response contains a cartLinesUpdate
object with two fields:
cart
: The updated cart object, including updated line items and cart totals.userErrors
: An array of errors encountered during the update operation. Each error object includes:field
: The input field related to the error.message
: A descriptive error message.code
: An error code identifying the type of error.
Example successful response:
{
"data": {
"cartLinesUpdate": {
"cart": {
"id": "eyJhbGciOiJIUzI1NiJ9...",
"lines": [
{
"id": 12345,
"quantity": 3,
"customizations": [
{ "id": 1, "name": "Color", "value": "Red" }
]
}
],
"totalQuantity": 3,
"updatedAt": "2024-06-01T12:00:00Z"
},
"userErrors": []
}
}
}
Example response with validation errors:
{
"data": {
"cartLinesUpdate": {
"cart": null,
"userErrors": [
{
"field": ["lines", "0", "quantity"],
"message": "Quantity must be at least 1.",
"code": "INVALID_QUANTITY"
}
]
}
}
}
Error Handling
Common errors returned in userErrors
include:
Code | Message | Description |
---|---|---|
INVALID_QUANTITY | Quantity must be at least 1. | The provided quantity is zero or negative. |
LINE_NOT_FOUND | Cart line item with the specified ID does not exist. | The id does not match any line item in the cart. |
INVALID_CART_ID | Cart ID is invalid or expired. | The provided cartId is not recognized or expired. |
Example error response for invalid quantity:
{
"data": {
"cartLinesUpdate": {
"cart": null,
"userErrors": [
{
"field": ["lines", "0", "quantity"],
"message": "Quantity must be at least 1.",
"code": "INVALID_QUANTITY"
}
]
}
}
}
Example error response for non-existent line ID:
{
"data": {
"cartLinesUpdate": {
"cart": null,
"userErrors": [
{
"field": ["lines", "0", "id"],
"message": "Cart line item with the specified ID does not exist.",
"code": "LINE_NOT_FOUND"
}
]
}
}
}
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 cart lines modifies the quantities and customizations of existing merchandise items in the cart.
- The cart’s total quantity and other computed fields are updated accordingly.
- If invalid input is provided, the mutation will not update the cart and will return user errors.
- This mutation does not create new cart lines; it only updates existing ones.
- Cart expiration or invalid cart IDs will result in errors.
Authentication
No authentication is currently required to perform this mutation. Future API versions may introduce authentication requirements.
Related Types
CartLinesUpdateInput
: Input object defining the cart line updates.CartLinesUpdatePayload
: Payload returned by the mutation, containing the updated cart and user errors.Cart
: Represents the shopping cart with line items and metadata.UserError
: Represents errors related to user input during mutation execution.CustomizationGroupOptionInput
: Input type for specifying customizations on merchandise items.
Notes
- Always validate that the
cartId
corresponds to an active cart. - Quantities must be positive integers; zero or negative values are rejected.
- Customizations are optional but must conform to valid customization options.
- Use GraphQL variables to improve query reusability and security.
- Rate limiting may apply; if you encounter rate limit errors, implement retry logic with exponential backoff.
- Monitor
userErrors
in the response to handle validation and business logic errors gracefully.
Last updated on