Skip to Content
ReferenceStorefrontv0.8.0 API ReferenceMutationscartLinesUpdate

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

ArgumentTypeDescriptionRequiredValidation
cartIdString!The ID of the cart to update lines inYesMust be a valid cart identifier
lines[CartLinesUpdateInput]!List of merchandise lines to update in the cartYesEach line must include id and quantity

CartLinesUpdateInput Fields

FieldTypeDescriptionRequiredValidation
idInt!The ID of the cart line item to updateYesMust correspond to an existing line item in the cart
quantityInt!The quantity of the merchandise item to updateYesMust be a positive integer
customizations[CustomizationGroupOptionInput]List of customizations for the merchandise itemNoOptional; 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:

CodeMessageDescription
INVALID_QUANTITYQuantity must be at least 1.The provided quantity is zero or negative.
LINE_NOT_FOUNDCart line item with the specified ID does not exist.The id does not match any line item in the cart.
INVALID_CART_IDCart 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.

  • 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
cartLinesRemovecartNoteUpdate