Modifying Cart Contents

we provide a function ( window\ spark updatecart ) that enables you to modify the cart contents adding products, changing quantities, removing items, clearing the cart, and updating cart level fields window\ spark updatecart( input partial\<updatecart>, cartsuccesshandledlocally? boolean, carterrorshandledlocally? boolean, ) promise\<cartresults\[] | null> adding a product to the cart add a variant by sku with adjustquantity , which increments whatever quantity is already in the cart await window\ spark updatecart({ products \[{ sku 'red shirt m', adjustquantity 1 }], }); add several products/variants in one call await window\ spark updatecart({ products \[ { sku 'red shirt m', adjustquantity 2 }, { sku 'blue hat l', adjustquantity 1 }, ], }); use quantity instead of adjustquantity when you want to set the line to an absolute value rather than increment it (e g a quantity input on the cart page) await window\ spark updatecart({ products \[{ sku 'red shirt m', quantity 5 }], }); adding custom attributes to a line item any product line can carry customattributes free form key/value pairs that travel with that line through the cart and into the resulting order (e g customer supplied customizations like engraving text or fabric choice) text to store a text value in the custom attributes, you can do the following await window\ spark updatecart({ products \[ { sku 'shirt custom', adjustquantity 1, customattributes \[ { key 'shirt length', value '32in' }, { key 'shirt fabric', value 'cotton' }, ], }, ], }); key / value are shown to the customer and staff under the line item, and persist through to past orders files attaching a file instead of text uses the same array, but value must be a json string of an array of gid(s) rather than plain text the gid comes from spark uploadfile() const gid = await window\ spark uploadfile('design png', fileblob); await window\ spark updatecart({ products \[ { sku 'shirt custom', adjustquantity 1, customattributes \[ { key 'design', value json stringify(\[gid]) }, ], }, ], }); the file name you pass to uploadfile() ( design png above) must match the actual type of the data in filedata e g don't name it design png if the blob is actually a jpeg a mismatch fails a post upload check on the server, the file is deleted, and the gid you got back stops resolving to anything (any later lookup of it, including reading the cart, will error) if you're building your own custom "add to cart" ui, this is all you need customattributes is just another field on the product you're already sending if instead you want to attach custom attributes to an add to cart action performed by one of sparklayer's built in components (the pdp widget, product card, etc ), see customizing add to cart docid\ dqn6ykft1nh2i 0qzaywx you don't call updatecart yourself in that case, so this won't apply directly removing an item / clearing the cart set quantity to 0 to remove a line if you already have the cart line's itemkey (e g from getcart() ), target it directly instead of by sku await window\ spark updatecart({ products \[{ itemkey 'abc123', quantity 0 }], }); clear the whole cart await window\ spark updatecart({ clearcart true }); updating cart level fields customerreference , ponumber , shippingrequesteddate , etc can all be updated the same way, independently of products await window\ spark updatecart({ customerreference 'this is a note on the order', ponumber 'po 4567', }); return value resolves to cartresults\[] one entry per product line you sent in or null if the request failed outright it does not return the updated cart directly; use spark getcart() or spark getcartcache() to read the new cart state each entry has requestedquantity / resultantquantity what you asked for vs what was actually applied these differ whenever a messages entry below fired (e g rounded to a pack size, clamped to a stock or order limit) itemkey , sku , name , barcode identify which line the result is for messages a list of { type } objects flagging anything that happened to this line type is one of type meaning success line added/updated with no issues pack size quantity rounded down to the nearest pack size qty excessive quantity brought down to the allowed maximum qty insufficient quantity brought up to the allowed minimum qty unavailable quantity lowered to what's currently in stock qty unavailable no clamp added, but the requested quantity isn't fully available check the cart excessive lines cart line limit reached; item wasn't added not found sku doesn't exist unavailable product isn't currently sellable product settings overridden default product settings were overridden these are just status codes, not display text updatecart uses them to show its own toast automatically (see below) if you handle messages yourself, switch on type to show your own copy handling feedback by default, updatecart shows toast messages for you pass true for the relevant flag to suppress sparklayer's built in toasts when you're showing your own feedback ui // suppress the built in success toast, but keep automatic error toasts await window\ spark updatecart( { products \[{ sku 'red shirt m', adjustquantity 1 }] }, true, // cartsuccesshandledlocally );