From b38d1501bd526dbdbe560fe6e979f92d4cc4812b Mon Sep 17 00:00:00 2001
From: Victor Chu <victor.chu@shopify.com>
Date: Thu, 25 Jun 2026 21:27:02 -0400
Subject: [PATCH] POS cart: add optional options arg to addLineItem

Add an optional third argument to cart.addLineItem so a single call can
create a line item and decorate it with line-item properties, instead of
chaining addLineItem -> addLineItemProperties.

Introduces the AddLineItemOptions type ({properties?}). Backwards
compatible: the third argument is optional. Follows the TAG-friendly
options-bag pattern (extend existing method over new method).

Assisted-By: devx/2ccb68c4-3a6f-43e0-9eb1-37bda8685c84
---
 .changeset/pos-cart-add-line-item-options.md          |  5 +++++
 .changeset/pre.json                                   |  1 +
 .../ui-extensions/src/surfaces/point-of-sale/api.ts   |  1 +
 .../surfaces/point-of-sale/api/cart-api/cart-api.ts   | 10 +++++++++-
 .../src/surfaces/point-of-sale/types/cart.ts          | 11 +++++++++++
 5 files changed, 27 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/pos-cart-add-line-item-options.md

diff --git a/.changeset/pos-cart-add-line-item-options.md b/.changeset/pos-cart-add-line-item-options.md
new file mode 100644
index 0000000000..46b8775fd0
--- /dev/null
+++ b/.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`) in one operation. This avoids the extra native call and cart sync of chaining `addLineItem` → `addLineItemProperties`. Backwards compatible—the third argument is optional. Adds the `AddLineItemOptions` type.
diff --git a/.changeset/pre.json b/.changeset/pre.json
index f8dcd187a4..77fba6451d 100644
--- a/.changeset/pre.json
+++ b/.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",
diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api.ts
index 967e566ecc..32a3a5d6d9 100644
--- a/packages/ui-extensions/src/surfaces/point-of-sale/api.ts
+++ b/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,
diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/cart-api/cart-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/cart-api/cart-api.ts
index 50e6b4baee..d1aba4d46d 100644
--- a/packages/ui-extensions/src/surfaces/point-of-sale/api/cart-api/cart-api.ts
+++ b/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 in the same operation, instead of following up with a separate `addLineItemProperties` call.
+   *
    * @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 properties to apply to the new line item 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.
diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/types/cart.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/cart.ts
index 25ca02fc66..ae4764cbac 100644
--- a/packages/ui-extensions/src/surfaces/point-of-sale/types/cart.ts
+++ b/packages/ui-extensions/src/surfaces/point-of-sale/types/cart.ts
@@ -263,6 +263,17 @@ export interface Discount {
   type?: string;
 }
 
+/**
+ * Optional configuration for `addLineItem`. Lets a single call create a line item and decorate it with line-item properties, avoiding the extra native call and cart sync of a separate `addLineItemProperties` call.
+ * @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>;
+}
+
 /**
  * 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