Skip to Content
ReferenceStorefrontv0.8.0 API ReferenceMutationscartLinesAdd

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

ArgumentTypeDescriptionRequiredValidation
cartIdString!The ID of the cart to add lines toYesMust be a valid cart identifier
lines[CartLineInput]!List of merchandise lines to add to the cartYesEach line must include valid merchandiseId and quantity

CartLineInput fields

FieldTypeDescriptionRequiredValidation
merchandiseIdInt!The ID of the merchandise item to addYesMust be a positive integer
quantityInt!The quantity of the merchandise item to addYesMust be a positive integer
customizations[CustomizationGroupOptionInput]List of customizations for the merchandise itemNoOptional; 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:

FieldDescription
fieldThe input field related to the error
messageA descriptive error message
codeAn 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.

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