cartLinesAdd
Adds merchandise lines to an existing cart.
Mutation Structure
mutation cartLinesAdd($cartId: String!, $lines: [CartLineInput]!) {
cartLinesAdd(cartId: $cartId, lines: $lines) {
cart {
id
lines {
merchandiseId
quantity
customizations {
groupId
optionId
}
}
}
userErrors {
field
message
code
}
}
}
Input Arguments
Argument | Type | Description | Required | Validation |
---|---|---|---|---|
cartId | String! | The ID of the cart to add lines to | Yes | Must be a valid cart identifier |
lines | [CartLineInput]! | List of merchandise lines to add to the cart | Yes | Each line must include valid merchandiseId and quantity |
CartLineInput fields
Field | Type | Description | Required | Validation |
---|---|---|---|---|
merchandiseId | Int! | The ID of the merchandise item to add | Yes | Must be a positive integer |
quantity | Int! | The quantity of the merchandise item to add | Yes | Must be a positive integer |
customizations | [CustomizationGroupOptionInput] | List of customizations for the merchandise item | No | Optional; if provided, must be valid customization options |
Return Type
The mutation returns a CartLinesAddPayload
object containing:
cart
(Cart!
): The updated cart after adding the specified lines.userErrors
([UserError]!
): A list of errors that occurred during the addition of cart lines. If empty, the operation was successful.
Examples
Basic Mutation
mutation {
cartLinesAdd(
cartId: "eyJhbGciOiJIUzI1NiJ9...",
lines: [
{
merchandiseId: 12345,
quantity: 2
}
]
) {
cart {
id
lines {
merchandiseId
quantity
}
}
userErrors {
field
message
code
}
}
}
Advanced Mutation
mutation {
cartLinesAdd(
cartId: "eyJhbGciOiJIUzI1NiJ9...",
lines: [
{
merchandiseId: 12345,
quantity: 3,
customizations: [
{
groupId: 10,
optionId: 100
},
{
groupId: 11,
optionId: 110
}
]
},
{
merchandiseId: 67890,
quantity: 1
}
]
) {
cart {
id
lines {
merchandiseId
quantity
customizations {
groupId
optionId
}
}
}
userErrors {
field
message
code
}
}
}
Input Validation
mutation {
cartLinesAdd(
cartId: "eyJhbGciOiJIUzI1NiJ9...",
lines: [
{
merchandiseId: -1,
quantity: 0
}
]
) {
cart {
id
lines {
merchandiseId
quantity
}
}
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 cartLinesAdd($cartId: String!, $lines: [CartLineInput]!) { cartLinesAdd(cartId: $cartId, lines: $lines) { cart { id lines { merchandiseId quantity customizations { groupId optionId } } } userErrors { field message code } } }",
"variables": {
"cartId": "eyJhbGciOiJIUzI1NiJ9...",
"lines": [
{
"merchandiseId": 12345,
"quantity": 2
}
]
}
}'
JavaScript Example
async function addLinesToCart() {
const query = `
mutation cartLinesAdd($cartId: String!, $lines: [CartLineInput]!) {
cartLinesAdd(cartId: $cartId, lines: $lines) {
cart {
id
lines {
merchandiseId
quantity
customizations {
groupId
optionId
}
}
}
userErrors {
field
message
code
}
}
}
`;
const variables = {
cartId: "eyJhbGciOiJIUzI1NiJ9...",
lines: [
{
merchandiseId: 12345,
quantity: 2
}
]
};
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.cartLinesAdd.userErrors.length > 0) {
console.error("User errors:", result.data.cartLinesAdd.userErrors);
} else {
console.log("Updated cart:", result.data.cartLinesAdd.cart);
}
} catch (error) {
console.error("Network or server error:", error);
}
}
addLinesToCart();
Response Format
The response contains a cartLinesAdd
field with the following structure:
{
"data": {
"cartLinesAdd": {
"cart": {
"id": "eyJhbGciOiJIUzI1NiJ9...",
"lines": [
{
"merchandiseId": 12345,
"quantity": 2,
"customizations": [
{
"groupId": 10,
"optionId": 100
}
]
}
]
},
"userErrors": []
}
}
}
cart
: The updated cart object with its lines.userErrors
: An array of errors encountered during the mutation. Empty if successful.
Error Handling
Errors are returned in the userErrors
array with the following fields:
Field | Description |
---|---|
field | The input field related to the error |
message | A descriptive error message |
code | An error code indicating the type of error |
Common error scenarios
-
Invalid cartId
{ "field": "cartId", "message": "Cart not found or invalid cart ID.", "code": "NOT_FOUND" }
-
Invalid merchandiseId
{ "field": "lines[0].merchandiseId", "message": "Merchandise item does not exist.", "code": "INVALID_INPUT" }
-
Quantity less than 1
{ "field": "lines[0].quantity", "message": "Quantity must be at least 1.", "code": "INVALID_INPUT" }
-
Invalid customizations
{ "field": "lines[0].customizations", "message": "Invalid customization options provided.", "code": "INVALID_INPUT" }
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
- Adds specified merchandise lines to the existing cart identified by
cartId
. - Updates the cart’s line items and quantities accordingly.
- May trigger recalculation of cart totals and discounts.
- Does not remove or modify existing lines unless explicitly added again with updated quantities.
Authentication
No authentication is required to perform this mutation at this time. This may change in future API versions.
Related Types
- CartLinesAddPayload: The payload returned by this mutation containing the updated cart and any user errors.
- CartLineInput: Input object defining merchandise lines to add.
- Cart: Represents the shopping cart.
- UserError: Object describing errors related to user input.
- CustomizationGroupOptionInput: Input type for specifying customizations on merchandise lines.
Notes
- Ensure
cartId
is a valid JWT token representing an existing cart. - Quantities must be positive integers; zero or negative values are invalid.
- Customizations are optional but must conform to valid customization options if provided.
- The mutation is idempotent for the same merchandise and quantity combination.
- Rate limiting may apply; excessive mutation requests could be throttled.
- Always check
userErrors
in the response to handle validation or business logic errors gracefully.
Last updated on