Skip to Content
ReferenceStorefrontv0.8.0 API ReferenceMutationscartLinesRemove

cartLinesRemove

Removes merchandise lines from an existing cart.

Mutation Structure

mutation cartLinesRemove($cartId: String!, $lineIds: [ID]!) {
  cartLinesRemove(cartId: $cartId, lineIds: $lineIds) {
    cart {
      id
      lines {
        id
        merchandise {
          ... on ProductVariant {
            id
            title
            price
          }
        }
        quantity
      }
      totalQuantity
      cost {
        subtotalAmount {
          amount
          currencyCode
        }
        totalAmount {
          amount
          currencyCode
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Input Arguments

ArgumentTypeDescriptionRequiredValidation
cartIdString!The ID of the cart to remove lines fromYesMust be a valid cart identifier
lineIds[ID]!A list of line item IDs to remove from the cartYesMust contain at least one valid line ID

Return Type

CartLinesRemovePayload

  • cart (Cart!): The updated cart after removing the specified lines. Includes details such as line items, quantities, and cost.
  • userErrors ([UserError]!): A list of errors that occurred during the removal process. Each error contains a field and a message.

Examples

Basic Mutation

mutation {
  cartLinesRemove(
    cartId: "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0",
    lineIds: ["98765"]
  ) {
    cart {
      id
      lines {
        id
        quantity
      }
      totalQuantity
    }
    userErrors {
      field
      message
    }
  }
}

Advanced Mutation

mutation cartLinesRemove($cartId: String!, $lineIds: [ID]!) {
  cartLinesRemove(cartId: $cartId, lineIds: $lineIds) {
    cart {
      id
      lines {
        id
        merchandise {
          ... on ProductVariant {
            id
            title
            price
          }
        }
        quantity
      }
      totalQuantity
      cost {
        subtotalAmount {
          amount
          currencyCode
        }
        totalAmount {
          amount
          currencyCode
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Input Validation

mutation {
  cartLinesRemove(
    cartId: "",
    lineIds: []
  ) {
    cart {
      id
    }
    userErrors {
      field
      message
    }
  }
}

cURL Example

curl -X POST https://www.mystoreurl.com/graphql/0.8.0/ \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation cartLinesRemove($cartId: String!, $lineIds: [ID]!) { cartLinesRemove(cartId: $cartId, lineIds: $lineIds) { cart { id lines { id quantity } totalQuantity } userErrors { field message } } }","variables":{"cartId":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0","lineIds":["98765","12345"]}}'

JavaScript Example

async function removeCartLines(cartId, lineIds) {
  const query = `
    mutation cartLinesRemove($cartId: String!, $lineIds: [ID]!) {
      cartLinesRemove(cartId: $cartId, lineIds: $lineIds) {
        cart {
          id
          lines {
            id
            quantity
          }
          totalQuantity
        }
        userErrors {
          field
          message
        }
      }
    }
  `;
 
  const variables = { cartId, lineIds };
 
  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.cartLinesRemove.userErrors.length > 0) {
      console.error('User errors:', result.data.cartLinesRemove.userErrors);
      return null;
    }
 
    return result.data.cartLinesRemove.cart;
  } catch (error) {
    console.error('Network or server error:', error);
    return null;
  }
}

Response Format

The mutation returns a CartLinesRemovePayload object containing:

  • cart: The updated cart object with current lines, quantities, and cost details.
  • userErrors: An array of user errors encountered during the mutation. Each error includes:
    • field: The input field related to the error (e.g., cartId, lineIds).
    • message: A descriptive error message.

Example successful response:

{
  "data": {
    "cartLinesRemove": {
      "cart": {
        "id": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0",
        "lines": [
          {
            "id": "12345",
            "quantity": 2
          }
        ],
        "totalQuantity": 2
      },
      "userErrors": []
    }
  }
}

Example response with user errors:

{
  "data": {
    "cartLinesRemove": {
      "cart": null,
      "userErrors": [
        {
          "field": "lineIds",
          "message": "One or more line IDs do not exist in the cart."
        }
      ]
    }
  }
}

Error Handling

Common error scenarios include:

  • Invalid or missing cartId
    Error message: "cartId is required and must be a valid cart identifier."
    Occurs when: cartId is empty, malformed, or does not correspond to an existing cart.

  • Empty or invalid lineIds list
    Error message: "lineIds must contain at least one valid line ID."
    Occurs when: lineIds is empty or contains invalid IDs.

  • Line IDs not found in cart
    Error message: "One or more line IDs do not exist in the cart."
    Occurs when: Provided lineIds do not match any line items in the specified cart.

  • General user errors
    Returned in the userErrors array with relevant field and message.

Example error response:

{
  "data": {
    "cartLinesRemove": {
      "cart": null,
      "userErrors": [
        {
          "field": "cartId",
          "message": "cartId is required and must be a valid cart identifier."
        }
      ]
    }
  }
}

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

  • Removing lines from a cart updates the cart’s total quantity and cost.
  • This mutation modifies the cart state and should be used carefully to avoid unintended removal of items.
  • Ensure that the cartId corresponds to an active cart to prevent errors.
  • The operation is idempotent for the same line IDs; removing lines that are already removed will result in user errors.

Authentication

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

  • Cart: Represents the shopping cart, including line items, quantities, and cost.
  • UserError: Contains error information related to user input or mutation execution.
  • CartLinesRemovePayload: The payload returned by this mutation, containing the updated cart and any user errors.

Notes

  • Use the JWT-format cartId token exactly as provided by the cart creation or retrieval APIs.
  • Always check the userErrors array after mutation execution to handle validation or business logic errors gracefully.
  • The mutation supports removing multiple line items in a single call by providing multiple lineIds.
  • Rate limiting may apply; if you encounter rate limit errors, implement exponential backoff and retry logic.
  • This mutation is designed for e-commerce scenarios where customers modify their shopping carts before checkout.
Last updated on
cartLinesAddcartLinesUpdate