Cart API Documentation¶

Overview¶

The Cart API allows you to manage shopping cart operations including viewing cart contents, adding items, updating quantities, and removing items.

Queries¶

Get Cart Contents¶

Retrieves the current cart contents including items and total.

query MyQuery {
  cart {
    items {
      productVariant {
        id
        name
        price
        priceRaw
        priceWithoutSymbol
      }
      quantity
      subtotal
    }
    total
  }
}

Response Fields¶

  • items: List of items in the cart

    • quantity: Number of items

    • subtotal: Price subtotal for this line item (formatted string with currency)

    • productVariant: Associated product variant information

  • total: Total price of all items in cart (formatted string with currency)

Mutations¶

Add to Cart¶

Adds a product variant to the cart.

mutation MyMutation {
  addToCart(input: {productVariantId: "", quantity: 10}) {
    cart {
      items {
        productVariant {
          id
          name
          price
          priceRaw
        }
        quantity
        subtotal
      }
    }
  }
}

Input Fields¶

  • input:

    • productVariantId: ID of the product variant (required)

    • quantity: Number of items to add (required)

Response Fields¶

  • success: Boolean indicating if operation was successful

  • message: Status message

  • cart: Updated cart contents (same structure as Get Cart query)

Update Cart Item¶

Updates the quantity of an existing cart item.

mutation MyMutation {
  updateCartItem(input: {productVariantId: "", quantity: 10}) {
    message
  }
}

Input Fields¶

  • input:

    • productVariantId: ID of the product variant (required)

    • quantity: New quantity (required, must be ≥ 1)

Response Fields¶

  • message: Status message

Remove from Cart¶

Removes an item from the cart.

mutation MyMutation {
  removeFromCart(productVariantId: "") {
    cart {
      items {
        productVariant {
          id
          name
          price
          priceRaw
          priceWithoutSymbol
        }
        quantity
        subtotal
      }
    }
  }
}

Input Fields¶

  • productVariantId: ID of the product variant to remove (required)

Response Fields¶

  • success: Boolean indicating if operation was successful

  • message: Status message

  • cart: Updated cart contents (same structure as Get Cart query)

Important Notes¶

Guest vs Authenticated Users¶

  • The API handles both guest and authenticated users automatically.

  • Guest cart data is stored in the session.

  • Upon user login, guest cart items are automatically merged with the user’s existing cart.

Quantity Validation¶

  • Quantity must be at least 1.

  • Invalid quantities will return an error.

Error Handling¶

Common error cases:

  • Product variant not found

  • Item not found in cart (for updates/removals)

  • Invalid quantity values

Currency Handling¶

  • All price fields (subtotal, total) are returned as formatted strings.

  • Multi-currency support is available if enabled.

  • Exchange rates are applied automatically based on the user’s selected currency.

Caching Considerations¶

  • It’s recommended to refetch cart data after mutations to ensure consistency.

  • The cart query reflects the most current state including price updates.