cartUpsertItemsByProductId
Upsert cart lines addressed by product instead of by item id.
Each line is matched by productId against the PLAIN lines already in the cart — those with no cluster, no bundle and no parent. On a match the quantity REPLACES the stored one; with no match the line is created. The whole set is applied in one pass and the cart is recalculated once, so this is the call to use for a standing order or a basket sync rather than firing one cartAddItem per product.
How it differs from the neighbouring mutations:
- cartAddItem ACCUMULATES on a repeat product (10 then 12 gives 22); this one REPLACES (10 then 12 gives 12). Keep using cartAddItem when a repeat add should add up.
- cartItemBulk decides create-vs-update on the presence of an itemId, so a caller that does not hold the id always gets a second line. Here productId is the key, so no read-before-write is needed.
Rules:
- Send quantity 0 to remove the matched line. A 0 for a product that is not in the cart does nothing. A removal is never checked against the catalogue, so a line whose product has since been hidden or withdrawn can always be taken out.
- Lines already in the cart that are not mentioned are left alone. This is not a whole-cart replace.
- price, notes and requestDate are written only when sent, and left untouched when omitted. Attributes are merged by description, as on cartUpdateItem.
- Each productId may appear only once in a call — it is the match key, so a second line for it would contradict the first.
- Sending a price (null included) requires one of the roles: supervisor, admin, system, internal, order.OWNER. order.EDITOR alone is not enough: it may edit the cart, but not price it. Note that this check is specific to this mutation: cartAddItem, cartUpdateItem and cartItemBulk currently accept a price without it, so it is a consistency rule for this call rather than a guarantee that a line's price was set by an order owner.
SCOPE — cluster variants and bundles are not addressable here, and are never touched:
- A line belonging to a cluster, a bundle, or any line with a parent is ignored by the match. A cluster variant is identified by the options selected on it and a bundle by its composition, and neither can be expressed by a product id.
- So a product that sits in the cart ONLY as a cluster option gets a NEW plain line from this mutation rather than having its cluster line changed. That is the same thing cartAddItem does with a bare productId, and it is worth knowing before using this to sync a basket: the quantity you set appears on a new line, and the cluster line keeps its own.
- Use cartUpdateItem by itemId to change a cluster or bundle line, cartAddItem to create a cluster line with its options, and cartAddBundle for a bundle.
Ambiguity is refused rather than guessed, with the itemIds named, so nothing is written:
- More than one plain line for the same product. cartAddItem merges plain lines so it cannot create this, but cartItemBulk can.
- A plain line that carries child items, which only cartItemBulk can produce.
Possible errors:
- CART_NOT_FOUND_ERROR: Cart with the specified ID does not exist, or is not visible to the caller
- CART_INVALID_STATUS_ERROR: Cart is not in an editable status
- CART_INVALID_OWNER_ERROR: Cart is not owned by, or shared with, the requesting user
- CART_CONCURRENT_WRITE_ERROR: Another write to this cart is already in progress
- CART_ITEM_PRICE_NOT_ALLOWED_ERROR: A price was sent by a caller without one of the roles above; nothing was written
- PRODUCT_NOT_FOUND_ERROR: One or more of the products being written do not exist, or are outside this company's assortment — the lookup is company-scoped, so an orderlist exclusion is reported the same way as a product that was never there; nothing was written
- PRODUCT_INVALID_ERROR: One or more of the products being written are hidden, or the catalogue could not be reached; nothing was written
- ATTRIBUTE_VALIDATION_ERROR: One or more attributes are not valid for this tenant
- ORDER_HELPER_VALIDATION_ERROR: order-helper rejected the order (e.g. invalid quantity, no price found)
- ORDER_HELPER_UNAVAILABLE_ERROR: order-helper could not be reached
- ORDER_HELPER_PAYLOAD_TOO_LARGE_ERROR: The recalculation request exceeded a size limit
- ORDER_HELPER_ERROR: Cart totals could not be recalculated for an unclassified reason
- CART_ITEM_UPSERT_ERROR: A productId appeared more than once, a line could not be addressed unambiguously, or the upsert failed unexpectedly
Every product this call WRITES is checked before anything is stored, so one unknown, hidden or out-of-assortment id refuses the whole call — the sellable lines sent beside it included — and leaves the cart exactly as it was. Chunk a large sync if you need the rest to go through regardless.
unOrderableItems on the resulting Cart therefore describes lines this call did not mention: a product the catalogue will no longer sell to this contact/company/channel is returned there instead of under items, never dropped without a trace. A line that reaches neither list is a failure, and is reported as CART_ITEM_UPSERT_ERROR rather than as a Cart with the product missing.
cartUpsertItemsByProductId(
id: String!
input: CartUpsertItemsByProductIdInput!
): Cart!
Arguments
cartUpsertItemsByProductId.id ● String! non-null scalar
Unique identifier of the cart to upsert the items into.
Must be a valid UUID format representing an existing cart.
cartUpsertItemsByProductId.input ● CartUpsertItemsByProductIdInput! non-null input
The product lines the cart should hold after the call.
Each line names a productId and the quantity it should have. Lines not mentioned here are left alone.
Type
Cart object
Shopping cart entity for managing customer purchases.
Represents a shopping session containing products, customer information, addresses, payment preferences, and all data needed for order processing. Carts can be associated with different customer types and support various business models.