Add cart.updateLineItemQuantity to the POS Cart API (2026-10)

[js-goupil]

Background

https://github.com/shop/issues-retail/issues/34342
Community feature request: https://community.shopify.dev/t/feature-request-updatelineitemquantity-in-the-pos-ui-extensions-cart-ap/36489

POS UI extensions have no line-scoped way to change the quantity of an existing cart line. Today an extension must either re-add the variant (which creates a separate line, or merges unpredictably across POS versions) or rewrite the whole cart with bulkCartUpdate (which risks rejecting on computed fields and has repriced existing lines to $0.00). Custom sale lines have no variant ID, so bulkCartUpdate is their only option.

Solution

Adds updateLineItemQuantity(uuid: string, quantity: number): Promise<void> to the POS Cart API (MutableCartApiContent), available in API version 2026-10 and later.

• Sets the absolute quantity of one existing line item, identified by UUID. POS resolves the full line item internally, so the line's properties, discounts, and selling plans are preserved — the same behavior as a merchant tapping +/- on the native cart line.
• quantity must be an integer of 1 or greater; use removeLineItem to remove a line.
• The promise resolves after the cart state reflects the change.
• Throws if the line item is not found, the quantity is invalid, the cart is not editable (during a return or exchange), or the POS app version does not support the method.
• If a UUID matches multiple split-line allocations, the call throws (ambiguous target) rather than guessing a line.

Also included: a docs example, tester mock support (@shopify/ui-extensions-tester), and a changeset (minor for @shopify/ui-extensions, patch for the tester).

🎩

• Host-side implementation: https://github.com/Shopify/extensibility/pull/1713 (cart plugin); POS runtime: shop/world Meteorite PR 2027388 (internal). Tophat end-to-end there. Type surface here validated with yarn build, yarn type-check, yarn lint, and the POS tester test suites.

Checklist

• I have 🎩'd these changes
• I have updated relevant documentation