Skip to Content
ReferenceStorefrontv0.8.0 API ReferenceInputsCartLineInput

CartLineInput

Input for a cart line item.

Input Definition

input CartLineInput {
  merchandiseId: Int!
  quantity: Int!
  customizations: [CustomizationGroupOptionInput]
}

Fields

FieldTypeRequiredDescriptionDefault Value
merchandiseIdInt!YesThe ID of the merchandise item to add to the cartNone
quantityInt!YesThe quantity of the merchandise item to addNone
customizations[CustomizationGroupOptionInput]NoList of customizations for the merchandise itemNone

Usage Examples

Basic Usage

mutation {
  addCartLine(input: {
    merchandiseId: 12345
    quantity: 2
  }) {
    cart {
      id
      lines {
        merchandiseId
        quantity
      }
    }
  }
}

Complex Input

mutation {
  addCartLine(input: {
    merchandiseId: 98765
    quantity: 3
    customizations: [
      {
        customizationGroupId: 10
        optionId: 5
      },
      {
        customizationGroupId: 12
        optionId: 7
      }
    ]
  }) {
    cart {
      id
      lines {
        merchandiseId
        quantity
        customizations {
          customizationGroupId
          optionId
        }
      }
    }
  }
}

With Variables

mutation AddLineToCart($lineInput: CartLineInput!) {
  addCartLine(input: $lineInput) {
    cart {
      id
      lines {
        merchandiseId
        quantity
        customizations {
          customizationGroupId
          optionId
        }
      }
    }
  }
}

Variables:

{
  "lineInput": {
    "merchandiseId": 54321,
    "quantity": 1,
    "customizations": [
      {
        "customizationGroupId": 3,
        "optionId": 9
      }
    ]
  }
}

Nested Objects

mutation {
  addCartLine(input: {
    merchandiseId: 11223
    quantity: 4
    customizations: [
      {
        customizationGroupId: 15
        optionId: 2
      }
    ]
  }) {
    cart {
      id
      lines {
        merchandiseId
        quantity
        customizations {
          customizationGroupId
          optionId
        }
      }
    }
  }
}

Validation Rules

  • merchandiseId must be a positive integer representing a valid merchandise item ID.
  • quantity must be a positive integer greater than zero.
  • customizations, if provided, must be an array of valid CustomizationGroupOptionInput objects.
  • Each CustomizationGroupOptionInput must include valid customizationGroupId and optionId fields (both integers).
  • The combination of merchandiseId and customizations should correspond to available product options in the catalog.

Example validation:

  • Invalid: quantity of 0 or negative numbers.
  • Invalid: Missing required merchandiseId.
  • Invalid: customizations containing invalid or missing fields.

Error Examples

  • Missing Required Field
{
  "errors": [
    {
      "message": "Field 'merchandiseId' of required type 'Int!' was not provided.",
      "locations": [{ "line": 3, "column": 5 }]
    }
  ]
}
  • Invalid Quantity
{
  "errors": [
    {
      "message": "Quantity must be a positive integer greater than zero.",
      "locations": [{ "line": 4, "column": 7 }]
    }
  ]
}
  • Invalid Customization Object
{
  "errors": [
    {
      "message": "CustomizationGroupOptionInput must include 'customizationGroupId' and 'optionId' as integers.",
      "locations": [{ "line": 5, "column": 9 }]
    }
  ]
}

Best Practices

  • Always provide both merchandiseId and quantity as they are required fields.
  • Use the customizations field only when the merchandise supports customizable options.
  • Validate input data on the client side before sending mutations to reduce errors.
  • Use GraphQL variables to improve query readability and reusability.
  • When specifying customizations, ensure the IDs correspond to valid customization groups and options for the merchandise.
  • Keep quantities realistic and consistent with inventory availability.
  • Handle errors gracefully by checking the response for validation messages.
  • CustomizationGroupOptionInput — Input type representing customization options for merchandise items.

Notes

  • This API currently requires no authentication; however, this may change in future versions.
  • The CartLineInput type is designed to be used in mutations that add or update items in a shopping cart.
  • Properly structuring the input ensures smooth cart operations and accurate order processing.
Last updated on
CartInputCartLinesUpdateInput