Skip to Content
ReferenceStorefrontv0.8.0 API ReferenceInputsCartInput

CartInput

Input for creating a new cart.

Input Definition

input CartInput {
  lines: [CartLineInput]
  buyerIdentity: BuyerIdentityInput
}

Fields

FieldTypeRequiredDefaultDescription
lines[CartLineInput]NonullA list of merchandise lines to add to the cart.
buyerIdentityBuyerIdentityInputNonullThe buyer identity associated with the cart.

Usage Examples

Basic Usage

mutation {
  createCart(input: {
    lines: [
      {
        merchandiseId: 12345,
        quantity: 2
      }
    ]
  }) {
    cart {
      id
      lines {
        id
        quantity
      }
    }
  }
}

Complex Input

mutation {
  createCart(input: {
    lines: [
      {
        merchandiseId: 12345,
        quantity: 3,
        attributes: [
          { key: "Color", value: "Red" },
          { key: "Size", value: "M" }
        ]
      },
      {
        merchandiseId: 67890,
        quantity: 1
      }
    ],
    buyerIdentity: {
      email: "customer@example.com",
      phone: "+1234567890",
      countryCode: "US"
    }
  }) {
    cart {
      id
      lines {
        id
        merchandise {
          id
          title
        }
        quantity
      }
      buyerIdentity {
        email
        phone
        countryCode
      }
    }
  }
}

With Variables

mutation CreateCart($input: CartInput!) {
  createCart(input: $input) {
    cart {
      id
      lines {
        id
        quantity
      }
      buyerIdentity {
        email
      }
    }
  }
}
{
  "input": {
    "lines": [
      {
        "merchandiseId": 12345,
        "quantity": 2
      }
    ],
    "buyerIdentity": {
      "email": "user@example.com"
    }
  }
}

Nested Objects

mutation {
  createCart(input: {
    lines: [
      {
        merchandiseId: 54321,
        quantity: 1,
        attributes: [
          { key: "Material", value: "Cotton" }
        ]
      }
    ],
    buyerIdentity: {
      email: "buyer@example.com",
      phone: "+19876543210",
      countryCode: "CA"
    }
  }) {
    cart {
      id
      lines {
        id
        quantity
        attributes {
          key
          value
        }
      }
      buyerIdentity {
        email
        phone
        countryCode
      }
    }
  }
}

Validation Rules

  • lines (optional): If provided, must be an array of valid CartLineInput objects.
    • Each CartLineInput must include a valid merchandiseId (integer) and a positive quantity (integer > 0).
    • Attributes inside lines (if supported) must be key-value pairs of strings.
  • buyerIdentity (optional): If provided, must conform to the BuyerIdentityInput structure.
    • Email must be a valid email format.
    • Phone numbers should include country code and be in a valid format.
    • countryCode should be a valid ISO 3166-1 alpha-2 country code.

Error Examples

  • Missing required fields in nested inputs:
{
  "errors": [
    {
      "message": "Field 'merchandiseId' of required type 'Int!' was not provided.",
      "locations": [{ "line": 3, "column": 7 }]
    }
  ]
}
  • Invalid quantity value:
{
  "errors": [
    {
      "message": "Quantity must be greater than zero.",
      "locations": [{ "line": 4, "column": 9 }]
    }
  ]
}
  • Invalid email format in buyerIdentity:
{
  "errors": [
    {
      "message": "Invalid email format for buyerIdentity.email.",
      "locations": [{ "line": 5, "column": 11 }]
    }
  ]
}

Best Practices

  • Always validate merchandiseId and quantity before sending the input to avoid server-side errors.
  • Use GraphQL variables for better reusability and cleaner queries.
  • Include buyer identity information when available to personalize the cart experience.
  • When adding multiple lines, ensure each line has unique merchandise and correct quantities.
  • Use attributes in lines to specify product options like size or color.
  • Handle errors gracefully by checking the response for validation messages.
  • Keep lines and buyerIdentity optional if you want to create an empty cart or anonymous cart.
  • CartLineInput: Defines individual merchandise lines with fields such as merchandiseId, quantity, and optional attributes.
  • BuyerIdentityInput: Defines buyer details such as email, phone, and countryCode.

Notes

  • The API currently requires no authentication; however, this may change in future versions.
  • Always use integer IDs for merchandise and other entities.
  • Cart creation supports flexible input, allowing partial or full specification of cart contents and buyer details.
  • Properly structuring nested inputs like lines and buyerIdentity improves mutation clarity and reduces errors.
Last updated on
BuyerIdentityInputCartLineInput