CartUpsertItemByProductIdInput
A single line to upsert into the shopping cart, addressed by product rather than by item id.
The 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 (10 then 12 leaves 12), which is what separates this from cartAddItem — that one accumulates. With no match the line is created.
input CartUpsertItemByProductIdInput {
productId: Int!
quantity: Int!
price: Float
notes: String
requestDate: String
attributes: [AttributeBulkCreateInput!]
}
Fields
CartUpsertItemByProductIdInput.productId ● Int! non-null scalar
Product identifier this line refers to.
Must be a product this caller's catalogue sells. An id that does not exist, is hidden, or is outside the company's assortment refuses the whole call — PRODUCT_NOT_FOUND_ERROR or PRODUCT_INVALID_ERROR — and nothing is written. It is the key the upsert matches on, so it may appear only once per call.
CartUpsertItemByProductIdInput.quantity ● Int! non-null scalar
Number of units this product should have in the cart after the call.
Absolute, not a delta: the value REPLACES the quantity on a matched line instead of being added to it. Send 0 to remove the matched line; a 0 for a product that is not in the cart does nothing. Required — there is no default, because a defaulted quantity on a replace operation would silently reset lines the caller never meant to touch. A removal is never checked against the catalogue, so a line whose product has since been hidden or withdrawn can always be taken out.
CartUpsertItemByProductIdInput.price ● Float scalar
Override price per unit for this cart item.
When specified, replaces the calculated price with this custom value and marks the line as externally priced. Primarily used for external pricing systems. Maximum 5 decimal places allowed. Send null to drop a custom price and return the line to platform pricing. Omit it to leave a matched line's existing price untouched.
Requires one of the roles: supervisor, admin, system, internal, order.OWNER. Sending a price at all — null included — without one rejects the whole call with CART_ITEM_PRICE_NOT_ALLOWED_ERROR, and nothing is written.
CartUpsertItemByProductIdInput.notes ● String scalar
Additional notes or special instructions for this item.
Maximum length of 255 characters. HTML tags will be automatically removed for security. Omit it to leave a matched line's existing notes untouched.
CartUpsertItemByProductIdInput.requestDate ● String scalar
Preferred delivery date for this specific item.
Must be provided in ISO 8601 date format (YYYY-MM-DD). Omit it to leave a matched line's existing date untouched.
CartUpsertItemByProductIdInput.attributes ● [AttributeBulkCreateInput!] list input
Custom attributes for this cart item, captured on the item and forwarded to the order item on processing.
Additive, exactly as on cartUpdateItem: attributes you do not mention are always kept. An entry whose description is already stored overwrites its value; a new description is appended. To remove a single attribute, send it with a null value. An omitted array changes nothing; an EMPTY array removes every attribute on this item in one call.