Add Item to Cart

GraphQL counterpart of POST /api/admin/carts/{id}/items. Mutation field is addItemAdminCart. Input type is addItemAdminCartInput.

Select cart fields, not id

This mutation returns the updated cart — select itemsCount, grandTotal, formattedGrandTotal, couponCode, success, message, etc. Do not select id (or _id): this is an action result with no addressable record, so the auto-generated IRI field is null and selecting it errors out the whole payload. The same applies to every cart-write mutation.

Prerequisites

The example uses an illustrative cart id. Admin cart endpoints only operate on draft carts (is_active=0) — storefront carts are rejected by the admin cart guard. Create a draft cart first with the createAdminDraftCart mutation and use the returned cartId.

Operation

Operation	Type
addItemAdminCart(input: addItemAdminCartInput!)	Mutation

Product type fields

Each product type needs its own selection fields (besides productId and quantity). These are typed input fields, so they work over GraphQL exactly as they do over REST:

Product type	Field
Simple / Virtual	—
Configurable	selectedConfigurableOption — the chosen variant's product id
Downloadable	links — list of downloadable-link ids
Grouped	groupedQuantities — list of { productId, quantity }
Bundle	bundleOptions — list of { optionId, productIds, quantity }
Booking	not supported in admin Create-Order (returns an error)

See the examples dropdown for a per-type sample.

Errors

Cause	Response
productId missing	errors[] — productId is required.
Product not found	errors[] — Product not found.
Booking product — admin draft orders do not support booking products	errors[] — Booking products cannot be added to an admin draft order. Booking purchases must be made through the customer storefront. Sample: {"errors":[{"message":"Booking products cannot be added to an admin draft order. Booking purchases must be made through the customer storefront.","extensions":{"category":"user"}}],"data":{"addItemAdminCart":null}}
Cart is an active storefront cart	errors[] — This cart cannot be modified through the admin API.