Skip to main content

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.