@shopify/ui-extensions 2025.7.2 → 2025.8.0

package/src/surfaces/admin/components/Text/Text.doc.ts

@@ -15,8 +15,8 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'TextProps',
     },
   ],
-  category: 'Components',
-  subCategory: 'Titles and text',
+  category: 'UI components',
+  subCategory: 'Typography and content',
   defaultExample: {
     image: 'text-default.png',
     codeblock: {

package/src/surfaces/admin/components/TextArea/TextArea.doc.ts

@@ -15,7 +15,7 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'TextAreaProps',
     },
   ],
-  category: 'Components',
+  category: 'UI components',
   subCategory: 'Forms',
   defaultExample: {
     image: 'textarea-default.png',

package/src/surfaces/admin/components/TextField/TextField.doc.ts

@@ -15,7 +15,7 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'TextFieldProps',
     },
   ],
-  category: 'Components',
+  category: 'UI components',
   subCategory: 'Forms',
   defaultExample: {
     image: 'textfield-default.png',

package/src/surfaces/admin/components/URLField/URLField.doc.ts

@@ -14,7 +14,7 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'URLFieldProps',
     },
   ],
-  category: 'Components',
+  category: 'UI components',
   subCategory: 'Forms',
   defaultExample: {
     image: 'urlfield-default.png',

package/src/surfaces/point-of-sale/api.ts

@@ -89,6 +89,7 @@ export type {
   CartUpdateInput,
   Customer,
   LineItem,
+  LineItemComponent,
   Discount,
   SetLineItemPropertiesInput,
   SetLineItemDiscountInput,

package/src/surfaces/point-of-sale/event/data/BaseApi.ts

@@ -1,3 +1,6 @@
 import {StorageApi} from '../../render/api/storage-api/storage-api';
 
+/**
+ * Base API access provided to extension targets, currently providing access to persistent storage for saving and retrieving extension data across sessions.
+ */
 export type BaseApi = StorageApi;

package/src/surfaces/point-of-sale/event/data/BaseData.ts

@@ -1,8 +1,23 @@
 import type {ConnectivityState, Device, Session} from '../../../point-of-sale';
 
+/**
+ * Base data object provided to all extension targets containing device information, session context, and connectivity state. This data is available at extension initialization and provides essential context about the runtime environment.
+ */
 export interface BaseData {
+  /**
+   * The current Internet connectivity state of the POS device. Indicates whether the device is connected to or disconnected from the Internet. This state updates in real-time as connectivity changes, allowing extensions to adapt behavior for offline scenarios, show connectivity warnings, or queue operations for when connectivity is restored.
+   */
   connectivity: ConnectivityState;
+  /**
+   * Comprehensive information about the physical POS device where the extension is currently running. Includes the device name, unique device ID, and form factor information (tablet vs other). This data is static for the session and helps extensions adapt to different device types, log device-specific information, or implement device-based configurations.
+   */
   device: Device;
+  /**
+   * The [IETF BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) locale string for the current POS session (for example, `"en-US"`, `"fr-CA"`, `"de-DE"`). This indicates the merchant's language and regional preferences. Commonly used for internationalization (i18n), locale-specific date/time/number formatting, translating UI text, and providing localized content. The locale remains constant for the session and reflects the language selected in POS settings.
+   */
   locale: string;
+  /**
+   * Comprehensive information about the current POS session including shop ID and domain, authenticated user, pinned staff member, active location, currency settings, and POS version. This session data remains constant for the session duration and provides critical context for business logic, permissions, API authentication, and transaction processing. Session data updates when users switch locations or change pinned staff members.
+   */
   session: Session;
 }

package/src/surfaces/point-of-sale/event/data/CartUpdateEventData.ts

@@ -2,6 +2,12 @@ import {BaseData} from './BaseData';
 import {Cart} from '../../api';
 import {BaseApi} from './BaseApi';
 
+/**
+ * The data object provided to cart update extension targets. Contains the current cart state along with device, session, and connectivity information. This data is passed to extensions whenever the cart changes, enabling real-time cart monitoring and cart-based business logic.
+ */
 export interface CartUpdateEventData extends BaseData, BaseApi {
+  /**
+   * The complete current `Cart` object containing all cart data including line items with products and quantities, pricing totals (subtotal, tax, grand total), associated customer information, applied discounts, custom properties, and editability state. This represents the cart's state at the moment the extension is triggered, reflecting all recent changes. The cart object is read-only in this context—modifications should be made through the Cart API methods.
+   */
   cart: Cart;
 }

package/src/surfaces/point-of-sale/event/data/CashTrackingSessionData.ts

@@ -1,17 +1,44 @@
 import {BaseData} from './BaseData';
 import {BaseApi} from './BaseApi';
 
+/**
+ * The data object provided to cash tracking session start extension targets. Contains information about a newly opened cash tracking session along with device and session context.
+ */
 export interface CashTrackingSessionStartData extends BaseData, BaseApi {
+  /**
+   * The cash tracking session start data containing the session identifier and the time when the session began. Cash tracking sessions represent the period during which a cash drawer is open and being used for transactions, typically corresponding to a staff member's shift.
+   */
   cashTrackingSessionStart: {
+    /**
+     * The unique numeric identifier for this cash tracking session. This ID matches the ID from when the session was opened and can be used to correlate session start and end events, retrieve session-specific data, or link all transactions that occurred during this session.
+     */
     id: number;
+    /**
+     * The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp when the cash tracking session was opened and began (for example, `"2024-05-15T09:00:00Z"`). This marks the start of the session and can be compared with `closingTime` to calculate the total session duration or shift length.
+     */
     openingTime: string;
   };
 }
 
+/**
+ * The data object provided to cash tracking session complete extension targets. Contains information about a completed cash tracking session including when it opened and closed, along with device and session context.
+ */
 export interface CashTrackingSessionCompleteData extends BaseData, BaseApi {
+  /**
+   * The cash tracking session complete data containing the session identifier, opening time, and closing time. This represents the full lifecycle of a cash drawer session from opening to closing.
+   */
   cashTrackingSessionComplete: {
+    /**
+     * The unique numeric identifier for this cash tracking session. This ID matches the ID from when the session was opened and can be used to correlate session start and end events, retrieve session-specific data, or link all transactions that occurred during this session.
+     */
     id: number;
+    /**
+     * The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp when the cash tracking session was opened and began (for example, `"2024-05-15T09:00:00Z"`). This marks the start of the session and can be compared with `closingTime` to calculate the total session duration or shift length.
+     */
     openingTime: string;
+    /**
+     * The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp when the cash tracking session was closed and ended (for example, `"2024-05-15T17:30:00Z"`). This marks when the staff member completed their shift, closed out the cash drawer, and finalized the session. The time between `openingTime` and `closingTime` represents the active session duration. Commonly used for shift reporting, calculating hours worked, or determining the timeframe for session-specific transactions.
+     */
     closingTime: string;
   };
 }

package/src/surfaces/point-of-sale/event/data/ExchangeTransactionData.ts

@@ -1,10 +1,28 @@
 import {BaseTransactionComplete} from '../../types/base-transaction-complete';
 import {LineItem} from '../../types/cart';
 
+/**
+ * Defines the data structure for completed exchange transactions.
+ */
 export interface ExchangeTransactionData extends BaseTransactionComplete {
+  /**
+   * The transaction type identifier, always 'Sale' for sale transactions.
+   */
   transactionType: 'Exchange';
+  /**
+   * The return ID for the completed return transaction.
+   */
   returnId?: number;
+  /**
+   * The exchange ID if the return is part of an exchange transaction.
+   */
   exchangeId?: number;
+  /**
+   * An array of line items added to the customer in the exchange.
+   */
   lineItemsAdded: LineItem[];
+  /**
+   * An array of line items removed from the customer in the exchange.
+   */
   lineItemsRemoved: LineItem[];
 }

package/src/surfaces/point-of-sale/event/data/ReprintReceiptData.ts

@@ -1,7 +1,16 @@
 import {BaseTransactionComplete} from '../../types/base-transaction-complete';
 import {OrderLineItem} from '../../types/order';
 
+/**
+ * Defines the data structure for receipt reprint requests.
+ */
 export interface ReprintReceiptData extends BaseTransactionComplete {
+  /**
+   * The transaction type identifier, always 'Sale' for sale transactions.
+   */
   transactionType: 'Reprint';
+  /**
+   * An array of line items included in the sale transaction.
+   */
   lineItems: OrderLineItem[];
 }

package/src/surfaces/point-of-sale/event/data/ReturnTransactionData.ts

@@ -1,10 +1,28 @@
 import {BaseTransactionComplete} from '../../types/base-transaction-complete';
 import {LineItem} from '../../types/cart';
 
+/**
+ * Defines the data structure for completed return transactions.
+ */
 export interface ReturnTransactionData extends BaseTransactionComplete {
+  /**
+   * The transaction type identifier, always 'Sale' for sale transactions.
+   */
   transactionType: 'Return';
+  /**
+   * The refund ID if a refund was issued for the return.
+   */
   refundId?: number;
+  /**
+   * The return ID for the completed return transaction.
+   */
   returnId?: number;
+  /**
+   * The exchange ID if the return is part of an exchange transaction.
+   */
   exchangeId?: number;
+  /**
+   * An array of line items included in the sale transaction.
+   */
   lineItems: LineItem[];
 }

package/src/surfaces/point-of-sale/event/data/SaleTransactionData.ts

@@ -1,8 +1,20 @@
 import {BaseTransactionComplete} from '../../types/base-transaction-complete';
 import {LineItem} from '../../types/cart';
 
+/**
+ * Defines the data structure for completed sale transactions.
+ */
 export interface SaleTransactionData extends BaseTransactionComplete {
+  /**
+   * The transaction type identifier, always 'Sale' for sale transactions.
+   */
   transactionType: 'Sale';
+  /**
+   * The UUID of the draft checkout if the sale originated from a draft order.
+   */
   draftCheckoutUuid?: string;
+  /**
+   * An array of line items included in the sale transaction.
+   */
   lineItems: LineItem[];
 }

package/src/surfaces/point-of-sale/event/data/TransactionCompleteData.ts

@@ -5,14 +5,41 @@ import type {ReturnTransactionData} from './ReturnTransactionData';
 import type {ReprintReceiptData} from './ReprintReceiptData';
 import {BaseApi} from './BaseApi';
 
+/**
+ * The data object provided to receipt targets containing transaction details.
+ */
 export interface TransactionCompleteData extends BaseData, BaseApi {
+  /**
+   * Provides access to persistent local storage methods for your POS UI extension. Use this to store, retrieve, and manage data that persists across sessions.
+   */
+  storage: BaseApi['storage'];
+  /**
+   * The transaction data, which can be one of the following types:
+   * - `SaleTransactionData`: Defines the data structure for completed sale transactions.
+   * - `ReturnTransactionData`: Defines the data structure for completed return transactions.
+   * - `ExchangeTransactionData`: Defines the data structure for completed exchange transactions.
+   */
   transaction:
     | SaleTransactionData
     | ReturnTransactionData
     | ExchangeTransactionData;
 }
 
+/**
+ * The data object provided to receipt targets containing transaction details and reprint information.
+ */
 export interface TransactionCompleteWithReprintData extends BaseData, BaseApi {
+  /**
+   * Provides access to persistent local storage methods for your POS UI extension. Use this to store, retrieve, and manage data that persists across sessions.
+   */
+  storage: BaseApi['storage'];
+  /**
+   * The transaction data, which can be one of the following types:
+   * - `SaleTransactionData`: Defines the data structure for completed sale transactions.
+   * - `ReturnTransactionData`: Defines the data structure for completed return transactions.
+   * - `ExchangeTransactionData`: Defines the data structure for completed exchange transactions.
+   * - `ReprintReceiptData`: Defines the data structure for receipt reprint requests.
+   */
   transaction:
     | SaleTransactionData
     | ReturnTransactionData

package/src/surfaces/point-of-sale/event/output/BaseOutput.ts

@@ -1,8 +1,22 @@
 interface ExtensionError extends Error {
+  /**
+   * The severity level of this error:
+   * - `'error'`: A critical error that prevents the extension from completing successfully. Errors typically block the user workflow and require resolution before proceeding.
+   * - `'warning'`: A non-critical issue that doesn't prevent extension execution but indicates a problem or unexpected condition. Warnings allow the workflow to continue but should be logged or displayed to users.
+   */
   level: 'error' | 'warning';
+  /**
+   * The human-readable error message describing what went wrong. This message should be clear and actionable, helping merchants understand the issue and how to resolve it (for example, "Product not found", "Invalid discount code", "Insufficient inventory"). The message may be displayed to users in the POS interface depending on the error severity and context.
+   */
   message: string;
 }
 
+/**
+ * Base output structure that extensions can return to communicate errors and warnings back to the POS system. Extensions populate this interface when they encounter issues during execution.
+ */
 export interface BaseOutput {
+  /**
+   * An array of errors or warnings encountered during extension execution. Each error includes a severity level (`'error'` or `'warning'`) and a descriptive message. Multiple errors can be reported simultaneously. Returns `undefined` or empty array when the extension executes successfully without issues. Critical errors may prevent transaction completion, while warnings allow the transaction to proceed but indicate issues that should be addressed.
+   */
   errors?: ExtensionError[];
 }

package/src/surfaces/point-of-sale/render/api/action-api/action-api.ts

@@ -1,14 +1,12 @@
 export interface ActionApiContent {
-  /** Presents the `action-overlay.render` extension target on top of present view.
-   *
-   * For example: if we are calling presentModal() from pos.purchase.post.action.menu-item.render,
-   * it should present pos.purchase.post.action.render.
+  /**
+   * Presents the corresponding action (modal) target on top of the current view as a full-screen modal. For example, calling this method from `pos.purchase.post.action.menu-item.render` presents `pos.purchase.post.action.render`. Use to launch detailed workflows, complex forms, or multi-step processes that require more screen space than simple components provide.
    */
   presentModal(): void;
 }
 
 /**
- * Access the Action API to present your app in a full screen modal.
+ * The `ActionApi` object provides methods for presenting modal interfaces. Access these methods through `api.action` to launch full-screen modal experiences.
  */
 export interface ActionApi {
   action: ActionApiContent;

package/src/surfaces/point-of-sale/render/api/cart-api/cart-api.ts

@@ -10,33 +10,38 @@ import type {
 } from '../../../types/cart';
 
 /**
- * Access and modify the merchant’s current cart.
+ * The `CartApi` object provides access to cart management functionality and real-time cart state monitoring. Access these properties through `api.cart` to interact with the current POS cart.
  */
 export interface CartApi {
   cart: CartApiContent;
 }
 
+/**
+ * Defines the type of discount applied at the cart level. Specifies whether the discount is percentage-based, fixed amount, or discount code redemption.
+ */
 export type CartDiscountType = 'Percentage' | 'FixedAmount' | 'Code';
 
+/**
+ * Defines the type of discount applied to individual line items. Specifies whether the discount is percentage-based or a fixed amount reduction.
+ */
 export type LineItemDiscountType = 'Percentage' | 'FixedAmount';
 
 export interface CartApiContent {
   /**
-   * Provides a subscription to POS cart changes.
-   * Provides an initial value and a callback to subscribe to value changes. Currently supports only one subscription.
-   * You can utilize `makeStatefulSubscribable` on a `RemoteSubscribable` to implement multiple subscriptions.
-   * Using `makeStatefulSubscribable` or the corresponding hooks counts as a subscription.
+   * Subscribes to real-time cart state changes. Provides initial cart value and triggers callbacks on updates. Supports only one active subscription—use `makeStatefulSubscribable` for multiple subscribers.
    */
   subscribable: RemoteSubscribable<Cart>;
 
-  /** Bulk update the cart
+  /**
+   * Perform a bulk update of the entire cart state including note, discounts, customer, line items, and properties. Returns the updated cart object after the operation completes with enhanced validation and error handling.
    *
    * @param cartState the cart state to set
    * @returns the updated cart
    */
   bulkCartUpdate(cartState: CartUpdateInput): Promise<Cart>;
 
-  /** Apply a cart level discount
+  /**
+   * Apply a cart-level discount with the specified type (`'Percentage'`, `'FixedAmount'`, or `'Code'`), title, and optional amount. For discount codes, omit the `amount` parameter. Enhanced validation ensures proper discount application.
    *
    * @param type the type of discount applied (example: 'Percentage')
    * @param title the title attributed with the discount
@@ -49,81 +54,82 @@ export interface CartApiContent {
   ): Promise<void>;
 
   /**
-   * Add a code discount to the cart
+   * Apply a discount code to the cart. The system will validate the code and apply the appropriate discount if the code is valid and applicable to the current cart contents with improved error messaging.
    *
    * @param code the code for the discount to add to the cart
    */
   addCartCodeDiscount(code: string): Promise<void>;
 
   /**
-   * Remove the cart discount
+   * Remove the current cart-level discount. This only affects cart-level discounts and does not impact line item discounts or automatic discount eligibility.
    */
   removeCartDiscount(): Promise<void>;
 
   /**
-   * Remove all cart and line item discounts
+   * Remove all discounts from both the cart and individual line items. Set `disableAutomaticDiscounts` to `true` to prevent automatic discounts from being reapplied after removal with enhanced discount allocation handling.
    *
    * @param disableAutomaticDiscounts Whether or not automatic discounts should be enabled after removing the discounts.
    */
   removeAllDiscounts(disableAutomaticDiscounts: boolean): Promise<void>;
 
   /**
-   * Clear the cart
+   * Remove all line items and reset the cart to an empty state. This action can't be undone and will clear all cart contents including line items, discounts, properties, and selling plans.
    */
   clearCart(): Promise<void>;
 
   /**
-   * Set the customer in the cart
+   * Associate a customer with the current cart using the customer object containing the customer `ID`. This enables customer-specific pricing, discounts, and checkout features with enhanced customer data validation.
    *
    * @param customer the customer object to add to the cart
    */
   setCustomer(customer: Customer): Promise<void>;
 
   /**
-   * Remove the current customer from the cart
+   * Remove the currently associated customer from the cart, converting it back to a guest cart without customer-specific benefits or information while preserving cart contents.
    */
   removeCustomer(): Promise<void>;
 
   /**
-   * Add a custom sale to the cart
+   * Add a custom sale item to the cart with specified quantity, title, price, and taxable status. Returns the `UUID` of the created line item for future operations and property management.
    *
    * @param customSale the custom sale object to add to the cart
-   * @returns {string} the uuid of the line item added
+   * @returns {string} the UUID of the line item added
    */
   addCustomSale(customSale: CustomSale): Promise<string>;
 
   /**
-   * Add a line item by variant ID to the cart
+   * 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.
    *
    * @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
-   * @returns {string} the uuid of the line item added
+   * @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>;
 
   /**
-   * Remove the line item at this uuid from the cart
+   * 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.
    *
    * @param uuid the uuid of the line item that should be removed
    */
   removeLineItem(uuid: string): Promise<void>;
 
   /**
-   * Adds custom properties to the cart
+   * Add custom key-value properties to the cart for storing metadata, tracking information, or integration data. Properties are merged with existing cart properties with enhanced validation and conflict resolution.
    *
    * @param properties the custom key to value object to attribute to the cart
    */
   addCartProperties(properties: Record<string, string>): Promise<void>;
 
   /**
-   * Removes the specified cart properties
+   * Remove specific cart properties by their keys. Only the specified property keys will be removed while other properties remain intact with improved error handling for non-existent keys.
    *
    * @param keys the collection of keys to be removed from the cart properties
    */
   removeCartProperties(keys: string[]): Promise<void>;
 
   /**
-   * Adds custom properties to the specified line item
+   * Add custom properties to a specific line item using its `UUID`. Properties are merged with existing line item properties for metadata storage and tracking with enhanced validation.
    *
    * @param uuid the uuid of the line item to which the properties should be stringd
    * @param properties the custom key to value object to attribute to the line item
@@ -134,7 +140,7 @@ export interface CartApiContent {
   ): Promise<void>;
 
   /**
-   * Adds custom properties to multiple line items at the same time.
+   * Add properties to multiple line items simultaneously using an array of inputs containing line item `UUIDs` and their respective properties for efficient bulk operations with enhanced validation and error reporting.
    *
    * @param lineItemProperties the collection of custom line item properties to apply to their respective line items.
    */
@@ -143,7 +149,7 @@ export interface CartApiContent {
   ): Promise<void>;
 
   /**
-   * Removes the specified line item properties
+   * Remove specific properties from a line item by `UUID` and property keys. Only the specified keys will be removed while other properties remain intact with improved error handling.
    *
    * @param uuid the uuid of the line item to which the properties should be removed
    * @param keys the collection of keys to be removed from the line item properties
@@ -151,7 +157,7 @@ export interface CartApiContent {
   removeLineItemProperties(uuid: string, keys: string[]): Promise<void>;
 
   /**
-   * Add a discount on a line item to the cart
+   * Apply a discount to a specific line item using its `UUID`. Specify the discount type (`'Percentage'` or `'FixedAmount'`), title, and amount value with improved discount allocation tracking.
    *
    * @param uuid the uuid of the line item that should receive a discount
    * @param type the type of discount applied (example: 'Percentage')
@@ -166,7 +172,7 @@ export interface CartApiContent {
   ): Promise<void>;
 
   /**
-   * Set line item discounts to multiple line items at the same time.
+   * Apply discounts to multiple line items simultaneously. Each input specifies the line item `UUID` and discount details for efficient bulk discount operations with enhanced validation and allocation tracking.
    *
    * @param lineItemDiscounts a map of discounts to add. They key is the uuid of the line item you want to add the discount to. The value is the discount input.
    */
@@ -175,14 +181,14 @@ export interface CartApiContent {
   ): Promise<void>;
 
   /**
-   * Sets an attributed staff to all line items in the cart.
+   * Set the attributed staff member for all line items in the cart using the staff `ID`. Pass `undefined` to clear staff attribution from all line items with enhanced staff validation and tracking.
    *
    * @param staffId the ID of the staff. Providing undefined will clear the attributed staff from all line items.
    */
   setAttributedStaff(staffId: number | undefined): Promise<void>;
 
   /**
-   * Sets an attributed staff to a specific line items in the cart.
+   * Set the attributed staff member for a specific line item using the staff `ID` and line item `UUID`. Pass `undefined` as `staffId` to clear attribution from the line item with improved validation and error handling.
    *
    * @param staffId the ID of the staff. Providing undefined will clear the attributed staff on the line item.
    * @param lineItemUuid the UUID of the line item.
@@ -193,28 +199,28 @@ export interface CartApiContent {
   ): Promise<void>;
 
   /**
-   * Remove all discounts from a line item
+   * Remove all discounts from a specific line item identified by its `UUID`. This will clear any custom discounts applied to the line item while preserving discount allocation history.
    *
    * @param uuid the uuid of the line item whose discounts should be removed
    */
   removeLineItemDiscount(uuid: string): Promise<void>;
 
   /**
-   * Add an address to the customer (Customer must be present)
+   * Add a new address to the customer associated with the cart. The customer must be present in the cart before adding addresses with enhanced address validation and formatting.
    *
    * @param address the address object to add to the customer in cart
    */
   addAddress(address: Address): Promise<void>;
 
   /**
-   * Delete an address from the customer (Customer must be present)
+   * Delete an existing address from the customer using the address `ID`. The customer must be present in the cart to perform this operation with improved error handling for invalid address `IDs`.
    *
    * @param addressId the address ID to delete
    */
   deleteAddress(addressId: number): Promise<void>;
 
   /**
-   * Update the default address for the customer (Customer must be present)
+   * Set a specific address as the default address for the customer using the address `ID`. The customer must be present in the cart to update the default address with enhanced validation.
    *
    * @param addressId the address ID to set as the default address
    */

package/src/surfaces/point-of-sale/render/api/cart-line-item-api/cart-line-item-api.ts

@@ -1,11 +1,11 @@
 import type {LineItem} from '../../../types/cart';
 
 /**
- * Access to the selected line item in the merchant’s current cart.
+ * The `CartLineItemApi` object provides access to the current line item. Access this property through `api.cartLineItem` to interact with the current line item context.
  */
 export interface CartLineItemApi {
   /**
-   * The selected line item in the merchant’s current cart.
+   * The selected line item in the merchant's current cart. Provides complete line item data including product information, pricing, discounts, properties, and metadata. Use for displaying item details and implementing item-specific functionality.
    */
   cartLineItem: LineItem;
 }

package/src/surfaces/point-of-sale/render/api/connectivity-api/connectivity-api.ts

@@ -2,23 +2,25 @@ import type {RemoteSubscribable} from '@remote-ui/async-subscription';
 
 export type ConnectivityStateSeverity = 'Connected' | 'Disconnected';
 
+/**
+ * Represents the current Internet connectivity status of the device. Indicates whether the device is connected or disconnected from the Internet.
+ */
 export interface ConnectivityState {
   /**
-   * Whether the device is connected to the internet
+   * Whether the device is connected to the Internet. Returns either `Connected` or `Disconnected` to indicate the current Internet connectivity status. Use for implementing connectivity-aware functionality, displaying connectivity indicators, or controlling network-dependent features.
    */
   internetConnected: ConnectivityStateSeverity;
 }
 
 export interface ConnectivityApiContent {
   /**
-   * Creates a subscription to changes in connectivity.
-   * Provides an initial value and a callback to subscribe to value changes.
+   * Creates a subscription to changes in connectivity. Provides an initial value and a callback to subscribe to value changes. Use for implementing connectivity-aware functionality and reactive connectivity handling.
    */
   subscribable: RemoteSubscribable<ConnectivityState>;
 }
 
 /**
- * Access information about the device connectivity
+ * The `ConnectivityApi` object provides access to current connectivity information and change notifications. Access these properties through `api.connectivity` to monitor network status.
  */
 export interface ConnectivityApi {
   connectivity: ConnectivityApiContent;

package/src/surfaces/point-of-sale/render/api/customer-api/customer-api.ts

@@ -1,10 +1,13 @@
+/**
+ * The `CustomerApi` object provides access to customer data in customer-specific extension contexts. Access this property through `shopify.customer` to retrieve information about the customer currently being viewed or interacted with in the POS interface.
+ */
 export interface CustomerApi {
   customer: CustomerApiContent;
 }
 
 export interface CustomerApiContent {
   /**
-   * The unique identifier for the customer
+   * The unique identifier for the customer. Use for customer lookups, applying customer-specific pricing, enabling personalized features, and integrating with external systems.
    */
   id: number;
 }