POS cart: add optional options arg to addLineItem

.changeset/pos-cart-add-line-item-options.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': minor
+---
+
+Added an optional `options` argument to the POS `cart.addLineItem` method so a single call can create a line item and decorate it with line-item properties (`properties`) and cart-level properties (`cartProperties`) in one operation. This avoids the extra native calls and cart syncs of chaining `addLineItem` → `addLineItemProperties` → `addCartProperties`. Backwards compatible—the third argument is optional. Adds the `AddLineItemOptions` type.

.changeset/pre.json

@@ -17,6 +17,7 @@
     "floppy-camels-bet",
     "mean-ducks-join",
     "paragraph-text-align",
+    "pos-cart-add-line-item-options",
     "pos-data-target-readonly-cart",
     "sixty-points-doubt",
     "soft-otters-share",

packages/ui-extensions/src/surfaces/point-of-sale/api.ts

@@ -91,6 +91,7 @@ export type {ToastApiContent, ToastApi} from './api/toast-api/toast-api';
 
 // Type exports
 export type {
+  AddLineItemOptions,
   Cart,
   CartUpdateInput,
   Customer,

packages/ui-extensions/src/surfaces/point-of-sale/api/cart-api/cart-api.ts

@@ -1,5 +1,6 @@
 import type {ReadonlySignalLike} from '../../../../shared';
 import type {
+  AddLineItemOptions,
   Address,
   Cart,
   CartUpdateInput,
@@ -123,12 +124,19 @@ export interface MutableCartApiContent {
   /**
    * Add a product variant to the cart by its numeric `ID` with the specified quantity. Returns the `UUID` of the newly added line item, or an empty string if the user dismissed an oversell guard modal. Throws an error if POS fails to add the line item due to validation or system errors.
    *
+   * Pass `options` to attach line-item properties and/or cart-level properties in the same operation, instead of following up with separate `addLineItemProperties` and `addCartProperties` calls.
+   *
    * @param variantId the product variant's numeric ID to add to the cart
    * @param quantity the number of this variant to add to the cart
+   * @param options optional line-item and cart-level properties to apply to the new line item and cart in the same operation
    * @returns {string} the UUID of the line item added, or the empty string if the user dismissed an oversell guard modal
    * @throws {Error} if POS fails to add the line item
    */
-  addLineItem(variantId: number, quantity: number): Promise<string>;
+  addLineItem(
+    variantId: number,
+    quantity: number,
+    options?: AddLineItemOptions,
+  ): Promise<string>;
 
   /**
    * Remove a specific line item from the cart using its `UUID`. The line item will be completely removed from the cart along with any associated discounts, properties, or selling plans.

packages/ui-extensions/src/surfaces/point-of-sale/types/cart.ts

@@ -263,6 +263,21 @@ export interface Discount {
   type?: string;
 }
 
+/**
+ * Optional configuration for `addLineItem`. Lets a single call create a line item and decorate it with line-item and cart-level properties, avoiding the extra native calls and cart syncs of separate `addLineItemProperties` and `addCartProperties` calls.
+ * @publicDocs
+ */
+export interface AddLineItemOptions {
+  /**
+   * Custom key-value properties to attach to the newly created line item. Equivalent to calling `addLineItemProperties` with the returned `UUID`, but applied in the same operation.
+   */
+  properties?: Record<string, string>;
+  /**
+   * Custom key-value properties to merge into the cart. Equivalent to calling `addCartProperties` in the same operation. Merged with existing cart properties—duplicate keys overwrite existing values.
+   */
+  cartProperties?: Record<string, string>;
+}
+
 /**
  * Specifies the parameters for adding custom properties to line items. Properties are key-value pairs used for storing metadata, tracking information, or integration data.
  * @publicDocs