Changing the cart

Every action on NativeSlide.Cart returns a promise of { ok, cart, error }. The promise never rejects. When the change works, it resolves once the drawer has read the changed cart, and cart is that cart. (If that takes more than 5 seconds, it resolves anyway with the cart the drawer has.) When it fails, it resolves as soon as Shopify answers, with ok: false and an error. cart is then the cart as it is.

const result = await NativeSlide.Cart.addItem(40001, 1, {
  properties: { Engraving: 'D.C.' },
});

if (!result.ok) {
  console.warn(result.error.code, result.error.message);
}

If you call an action before the API is ready, it waits and then runs.

Adding

Action
addItem(variantId, quantity, options)	Adds one line. quantity defaults to 1.
addItems(lines, options)	Adds several lines in one request. An empty list does nothing and resolves with ok: true.

Each line in addItems is { id, quantity, properties, sellingPlan, parentKey }. Only id, the variant ID, is required, and quantity defaults to 1. addItem’s options take the same fields apart from id and quantity, plus open:

• properties are line item properties, such as an engraving.
• sellingPlan is a selling plan ID, to add the line as a subscription.
• parentKey is another line’s key, to add this one as part of a bundle.

After a successful add, the drawer opens if the merchant has turned on Open on add to cart. Pass { open: true } or { open: false } to decide yourself: it’s the last argument of addItem and the second of addItems. A free gift added in the background, for example, shouldn’t pop the drawer open:

await NativeSlide.Cart.addItems([{ id: 40099, properties: { _gift: 'yes' } }], { open: false });

await NativeSlide.Cart.addItem(40001, 2, { sellingPlan: 690010, open: true });

Adds made through the API fire the item-added event with source: 'api'.

Changing and removing lines

key is a line’s key from Cart.items. A variant ID works too, for the first line with that variant. If there’s no such line, the action fails with not_found.

Action
updateItem(key, { quantity, properties, sellingPlan })	Changes any of these on a line. Fields you leave out stay as they are.
setQuantity(key, quantity)	Sets the quantity; 0 removes the line. If the line already has that quantity, nothing is sent.
increaseQuantity(key) / decreaseQuantity(key)	One more or one fewer. Decreasing a line of 1 removes it.
removeItem(key)	Removes the line
clear()	Empties the cart
refresh()	Reads the cart again from Shopify

While one of these runs, the drawer shows the line as busy, and if it fails, Shopify’s message appears under the line and the error event fires. Pass the line’s key rather than a variant ID for this to show on the right line.

Calling the same action on the same line again while the first call is still running fails with cancelled, and so does clear() while another clear() runs. updateItem and setQuantity count as the same action.

The drawer notices changes made by the theme and other apps on its own. You only need refresh() if your script changes the cart in a way the page can’t see, such as from a server. See For theme developers.

Discount codes

Action
addDiscountCode(code)	Applies a code next to the ones already applied
removeDiscountCode(code)	Takes one code off
setDiscountCodes(codes)	Replaces all codes. [] removes them all.

Codes are matched without regard to case, and addDiscountCode trims spaces around the code.

• If Shopify can’t apply a code to this cart, addDiscountCode takes it off again and fails with invalid_discount, so the cart is left as it was. An empty code fails the same way.
• Adding a code that’s already applied, or removing one that isn’t, does nothing and resolves with ok: true.
• setDiscountCodes doesn’t check the codes. A code that can’t apply doesn’t show in Cart.discountCodes.

Note and attributes

Action
setNote(note)	Sets the order note
setAttributes({ name: value })	Adds or changes cart attributes; an empty value removes one. Attributes you leave out stay as they are.

await NativeSlide.Cart.setAttributes({ 'Delivery date': '2026-12-24', 'Gift wrap': '' });

Errors

When ok is false, error.code says why and error.message describes it:

Code	Meaning
disabled	The store has no published NativeSlide cart
not_found	There’s no line with that key or variant ID
invalid_discount	Shopify can’t apply that code to this cart, or the code is empty
shopify	Shopify refused the change. error.message is Shopify’s own message, such as “You can only add 2 of Canvas tote to the cart.”, and error.status is its HTTP status. A failed discount code request also gives shopify, with the cart’s own error text and no status.
network	The request didn’t complete. A failed clear() always gives network.
cancelled	The same change was already running, or a before-checkout listener stopped checkout