Add to Cart

About

The createAddProductInCart mutation adds a product to a customer's shopping cart. Use this mutation to:

• Add products from product detail pages to cart
• Implement "Add to Cart" buttons and flows
• Add products programmatically from search results
• Handle quantity selection and product-specific options
• Support all product types: simple, configurable, downloadable, grouped, bundle, and booking

This mutation validates product availability, applies applicable pricing rules, and updates the cart totals. It returns the complete updated cart state including all items, pricing, and tax information.

Authentication

This mutation supports both authenticated customers and guest users:

• Authenticated customers: Provide a valid customer authentication token in the Authorization header. Obtain this token via the Customer Login API.
• Guest users: Provide the Guest Cart Token cartToken obtained from the Create Cart mutation.

Authorization: Bearer <accessToken>

Input Arguments

Argument	Type	Required	Description
productId	Int!	Yes	The product ID to add to the cart.
quantity	Int	No	Number of units to add. Defaults to 1 if omitted.
selectedConfigurableOption	Int	Configurable only	The child variant product ID for configurable products.
superAttribute	Iterable	Configurable only	Array of attribute-option mappings, e.g., [{"23": 2}, {"24": 8}] where keys are attribute IDs and values are option IDs.
links	Iterable	Downloadable only	Array of downloadable link IDs the customer wants to purchase, e.g., [1, 2].
groupedQty	String	Grouped only	JSON string mapping each associated product ID to its quantity, e.g., "{\"1\":1,\"3\":2}". All associated products must be included.
bundleOptions	String	Bundle only	JSON string mapping bundle option IDs to arrays of selected product IDs, e.g., "{\"1\":[1],\"2\":[2]}".
bundleOptionQty	String	Bundle only	JSON string mapping bundle option IDs to their quantities, e.g., "{\"2\":3,\"3\":4}". Only applies to radio/select options; checkbox/multiselect quantities are fixed by admin.
booking	String	Booking only	JSON string containing booking details. Structure varies by booking type (see Booking Input Reference below).
bookingNote	String	Table booking only	Special note or request for table bookings. Required for table booking type.
isBuyNow	Int	No	Set to 1 for buy-now flow (creates a new cart for immediate checkout). Default: 0.

Input Requirements by Product Type

Product Type	Required Fields	Optional Fields
Simple	productId	quantity
Configurable	productId, selectedConfigurableOption, superAttribute	quantity
Downloadable	productId, links	quantity
Grouped	productId, groupedQty	quantity
Bundle	productId, bundleOptions	quantity, bundleOptionQty
Booking	productId, booking	quantity, bookingNote

Booking Input Reference

The booking field accepts a JSON string whose structure varies by booking type. The API automatically converts human-readable time range strings (e.g., "12:00 PM - 08:00 PM") to Unix timestamps internally.

Booking Type	JSON Structure	Example
Default	{"type":"default","date":"YYYY-MM-DD","slot":"HH:MM AM - HH:MM PM"}	{"type":"default","date":"2026-03-25","slot":"12:00 PM - 08:00 PM"}
Appointment	{"type":"appointment","date":"YYYY-MM-DD","slot":"HH:MM AM - HH:MM PM"}	{"type":"appointment","date":"2026-03-28","slot":"12:00 PM - 12:45 PM"}
Rental (Daily)	{"type":"rental","renting_type":"daily","date_from":"YYYY-MM-DD","date_to":"YYYY-MM-DD"}	{"type":"rental","renting_type":"daily","date_from":"2026-03-24","date_to":"2026-03-26"}
Rental (Hourly)	{"type":"rental","renting_type":"hourly","date":"YYYY-MM-DD","slot":"HH:MM AM - HH:MM PM"}	{"type":"rental","renting_type":"hourly","date":"2026-03-19","slot":"11:00 AM - 12:00 PM"}
Event	{"type":"event","qty":{"ticketId":qty,...}}	{"type":"event","qty":{"1":1,"2":1}}
Table	{"type":"table","date":"YYYY-MM-DD","slot":"HH:MM AM - HH:MM PM"} + bookingNote param	{"type":"table","date":"2026-03-25","slot":"12:00 PM - 12:45 PM"}

Booking Type Notes

• Event bookings: At least one ticket type must have a quantity greater than 0.
• Table bookings: The bookingNote input parameter is required. It is passed separately from the booking JSON.
• Rental bookings: Daily rentals use date_from/date_to; hourly rentals use date/slot.
• Slot format: Time ranges like "12:00 PM - 08:00 PM" are automatically parsed and converted to Unix timestamps by the API.

Cart Item options Field

The options field on each cart item contains product-specific selection details. This data is essential for displaying what the customer selected on the cart page. The structure varies by product type:

Product Type	Options Content	Example
Simple	Not present — no additional options needed	—
Configurable	Selected attribute values (color, size, etc.)	[{"id":"23","label":"Color","value":"Blue","option_id":"2"}]
Downloadable	Selected downloadable links	[{"link_id":"1","title":"PDF Version","price":15}]
Grouped	Individual product quantities	[{"product_id":"101","name":"Product A","qty":2}]
Bundle	Selected bundle options and quantities	[{"option_id":"1","label":"Mouse","can_change_qty":true,"value":[...]}]
Booking	Booking date, slot, and note details	[{"label":"Date","value":"2026-03-25"},{"label":"Slot","value":"12:00 PM - 12:45 PM"}]

Possible Returns

Field	Type	Description
id	ID!	Cart identifier in IRI format.
_id	Int!	Numeric cart ID.
cartToken	String!	Cart session token for guest users.
customerId	Int	Customer ID (null for guest users).
channelId	Int!	Channel the cart belongs to.
subtotal	String!	Cart subtotal before tax and shipping.
grandTotal	String!	Final cart total including tax and discounts.
discountAmount	String	Total discount applied.
taxAmount	String	Total tax amount.
shippingAmount	String	Shipping cost.
couponCode	String	Applied coupon code, if any.
items	CartItemConnection!	Paginated collection of cart items.
items.totalCount	Int!	Total number of items in cart.
items.edges.node	CartItem!	Individual cart item with product details, pricing, and options.
success	Boolean!	Whether the product was added successfully.
message	String!	Success or error message.
sessionToken	String	Session token for cart persistence.
isGuest	Boolean!	Whether the cart belongs to a guest user.
itemsQty	Int!	Total quantity of all items in cart.
itemsCount	Int!	Number of distinct items in cart.
haveStockableItems	Boolean!	Whether cart contains physical/shippable items.

Best Practices

1. Use Product-Specific Fields — Only pass the input fields relevant to the product type being added (e.g., don't pass booking for simple products)
2. Handle Options in Cart Display — Use the options field on cart items to display what the customer selected (variant attributes, bundle choices, booking dates, etc.)
3. Check success Field — Always check the success boolean and message in the response to handle errors gracefully
4. Persist Session Token — Store the sessionToken/cartToken returned for guest users to maintain cart state across requests
5. Validate Booking Slots — For booking products, retrieve available slots from the product query before adding to cart
6. Bundle Qty Restrictions — For bundle products, note that checkbox/multiselect option quantities are admin-controlled and cannot be changed by customers

Related Resources

• Create Cart - Create a new cart (required for guest users)
• Update Cart Item - Update quantity of items in cart
• Remove Cart Item - Remove items from cart
• Get Cart - Retrieve current cart state
• Single Product - Get product details and available options