@shopify/ui-extensions 2025.10.8 → 2025.10.10

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

@@ -1,19 +1,15 @@
 /**
- * Access the print API for printing functionality
+ * The `PrintApi` object provides methods for triggering document printing. Access these methods through `shopify.print` to initiate print operations with various document types.
  */
 export interface PrintApiContent {
   /**
-   * Trigger a print dialog.
+   * Triggers a print dialog for the specified document source. The `print()` method accepts either:
    *
-   * The src must be either:
-   * - A relative path that will be appended to your app's [application_url](/docs/apps/build/cli-for-apps/app-configuration#application_url)
-   * - A full URL to your app's backend that will be used to return the document to print
+   * • A relative path that will be appended to your app's [`application_url`](/docs/apps/build/cli-for-apps/app-configuration)
    *
-   * Supported document types:
-   * - HTML documents (recommended for best printing experience)
-   * - Text files
-   * - Image files (PNG, JPEG, etc.)
-   * - PDF files (Note: On Android devices, PDFs will be downloaded and must be printed using an external application)
+   * • A full URL to your app's backend that will be used to return the document to print
+   *
+   * Returns a promise that resolves when content is ready and the native print dialog appears. Use for printing custom documents, receipts, labels, or reports.
    *
    * @param src the source URL of the content to print.
    * @returns Promise<void> that resolves when content is ready and native print dialog appears.
@@ -22,8 +18,11 @@ export interface PrintApiContent {
 }
 
 /**
- * Interface for printing
+ * The `PrintApi` object provides methods for triggering document printing. Access these methods through `shopify.print` to initiate print operations with various document types.
  */
 export interface PrintApi {
+  /**
+   * The `PrintApi` object provides methods for triggering document printing. Access these methods through `shopify.print` to initiate print operations with various document types.
+   */
   print: PrintApiContent;
 }

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

@@ -1,14 +1,17 @@
+/**
+ * The `ProductApi` object provides access to product and variant data in product-specific extension contexts. Access this property through `shopify.product` to retrieve information about the product or variant currently being viewed or interacted with in the POS interface.
+ */
 export interface ProductApi {
   product: ProductApiContent;
 }
 
 export interface ProductApiContent {
   /**
-   * The unique identifier for the product.
+   * The unique identifier for the product. Use for product lookups, implementing product-specific functionality, and integrating with external systems.
    */
   id: number;
   /**
-   * The unique identifier for the product variant.
+   * The unique identifier for the product variant. Use for variant-specific operations, cart additions, and inventory management.
    */
   variantId: number;
 }

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

@@ -9,7 +9,7 @@ export type ProductSortType =
   | 'ALPHABETICAL_Z_TO_A';
 
 /**
- * Base interface for pagination.
+ * Specifies parameters for cursor-based pagination. Includes the cursor position and the number of results to retrieve per page.
  */
 export interface PaginationParams {
   /**
@@ -23,7 +23,7 @@ export interface PaginationParams {
 }
 
 /**
- * Interface for product search
+ * Specifies the parameters for searching products. Includes query text, pagination options, and sorting preferences for product search operations.
  */
 export interface ProductSearchParams extends PaginationParams {
   /**
@@ -37,47 +37,61 @@ export interface ProductSearchParams extends PaginationParams {
 }
 
 export interface ProductSearchApiContent {
-  /** Search for products on the POS device.
+  /**
+   * Searches for products on the POS device using text queries and sorting options. Returns paginated results with up to 50 products per page. When a query string is provided, results are sorted by relevance. Use for implementing custom search interfaces, product discovery features, or filtered product listings.
+   *
    * @param searchParams The parameters for the product search.
    */
   searchProducts(
     searchParams: ProductSearchParams,
   ): Promise<PaginatedResult<Product>>;
 
-  /** Fetches a single product's details.
+  /**
+   * Retrieves detailed information for a single product by its ID. Returns `undefined` if the product doesn't exist or isn't available on the POS device. Use for displaying product details, validating product availability, or building product-specific workflows.
+   *
    * @param productId The ID of the product to lookup.
    */
   fetchProductWithId(productId: number): Promise<Product | undefined>;
 
-  /** Fetches multiple products' details.
+  /**
+   * Retrieves detailed information for multiple products by their IDs. Limited to 50 products maximum—additional IDs are automatically removed. Returns results with both found and not found products clearly identified. Use for bulk product lookups, building product collections, or validating product lists.
+   *
    * @param productIds Specifies the array of product IDs to lookup. This is limited to 50 products. All excess requested IDs will be removed from the array.
    */
   fetchProductsWithIds(
     productIds: number[],
   ): Promise<MultipleResourceResult<Product>>;
 
-  /** Fetches a single product variant's details.
+  /**
+   * Retrieves detailed information for a single product variant by its ID. Returns `undefined` if the variant doesn't exist or isn't available. Use for displaying variant-specific details like pricing, inventory, or options when working with specific product configurations.
+   *
    * @param productVariantId The ID of the product variant to lookup.
    */
   fetchProductVariantWithId(
     productVariantId: number,
   ): Promise<ProductVariant | undefined>;
 
-  /** Fetches multiple product variants' details.
+  /**
+   * Retrieves detailed information for multiple product variants by their IDs. Limited to 50 variants maximum—additional IDs are automatically removed. Returns results with both found and not found variants clearly identified. Use for bulk variant lookups or building variant-specific collections.
+   *
    * @param productVariantIds Specifies the array of product variant IDs to lookup. This is limited to 50 product variants. All excess requested IDs will be removed from the array.
    */
   fetchProductVariantsWithIds(
     productVariantIds: number[],
   ): Promise<MultipleResourceResult<ProductVariant>>;
 
-  /** Fetches all product variants associated with a product.
+  /**
+   * Retrieves all product variants associated with a specific product ID. Returns all variants at once without pagination. Use for displaying complete variant options, building variant selectors, or analyzing all available configurations for a product.
+   *
    * @param productId The product ID. All variants' details associated with this product ID are returned.
    */
   fetchProductVariantsWithProductId(
     productId: number,
   ): Promise<ProductVariant[]>;
 
-  /** Fetches a page of product variants associated with a product.
+  /**
+   * Retrieves product variants for a specific product with pagination support. Use when a product has many variants and you need to load them incrementally for better performance. Ideal for products with extensive variant collections that would be too large to load at once.
+   *
    * @param paginationParams The parameters for pagination.
    */
   fetchPaginatedProductVariantsWithProductId(
@@ -87,7 +101,7 @@ export interface ProductSearchApiContent {
 }
 
 /**
- * Access Point of Sale's native product search functionality.
+ * The `ProductSearchApi` object provides methods for searching and retrieving product information. Access these methods through `shopify.productSearch` to search products and fetch detailed product data.
  */
 export interface ProductSearchApi {
   productSearch: ProductSearchApiContent;

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

@@ -3,40 +3,58 @@ import type {ReadonlySignalLike} from '../../../../shared';
 /** The scanner source the POS device supports. */
 export type ScannerSource = 'camera' | 'external' | 'embedded';
 
+/**
+ * Represents the data from a scanner event. Contains the scanned string data and the hardware source that captured the scan.
+ */
 export interface ScannerSubscriptionResult {
-  /** The string data from the last scanner event received. */
+  /**
+   * The string data from the last scanner event received. Contains the scanned barcode, QR code, or other scannable data. Returns `undefined` when no scan data is available. Use to process scanned content and implement scan-based business logic.
+   */
   data?: string;
-  /** The scanning source from which the scan event came. */
+  /**
+   * The scanning source from which the scan event came. Returns one of the following scanner types:
+   *
+   * • `'camera'` - Built-in device camera used for scanning
+   * • `'external'` - External scanner hardware connected to the device
+   * • `'embedded'` - Embedded scanner hardware built into the device
+   */
   source?: ScannerSource;
 }
 
+/**
+ * Represents the available scanner hardware sources on the device. Provides reactive access to the list of scanners that can be used for scanning operations.
+ */
 export interface ScannerSources {
   /**
-   * The current available scanner sources.
-   * The `value` property provides the current sources, and `subscribe` allows listening to changes.
+   * Current available scanner sources with subscription support. The `value` property provides current sources, and `subscribe` listens for changes. Use to monitor which scanners are available.
    */
   current: ReadonlySignalLike<ScannerSource[]>;
 }
 
+/**
+ * Represents the scanner interface for accessing scan events and subscription management. Provides real-time access to scanned data through a reactive signal pattern.
+ */
 export interface ScannerData {
   /**
-   * The current scan data.
-   * The `value` property provides the current scan result, and `subscribe` allows listening to new scans.
+   * Current available scanner sources with subscription support. The `value` property provides current sources, and `subscribe` listens for changes. Use to monitor which scanners are available.
    */
   current: ReadonlySignalLike<ScannerSubscriptionResult>;
 }
 
 export interface ScannerApiContent {
   /**
-   * Provides read-only access to scanner data and allows subscribing to new scan events.
+   * Access current scan data and subscribe to new scan events. Use to receive real-time scan results.
    */
   scannerData: ScannerData;
   /**
-   * Provides read-only access to the available scanner sources on the POS device.
+   * Access available scanner sources on the device. Use to check which scanners are available (camera, external, or embedded).
    */
   sources: ScannerSources;
 }
 
+/**
+ * The `ScannerApi` object provides access to scanning functionality and scanner source information. Access these properties through `shopify.scanner` to monitor scan events and available scanner sources.
+ */
 export interface ScannerApi {
   scanner: ScannerApiContent;
 }

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

@@ -2,20 +2,17 @@ import type {Session} from '../../types/session';
 
 export interface SessionApiContent {
   /**
-   * Access information on the current POS session.
+   * Provides comprehensive information about the current POS session including shop details, user authentication, location data, staff member information, currency settings, and POS version. This data is static for the duration of the session and updates when users switch locations or staff members change.
    */
   currentSession: Session;
   /**
-   * Get a fresh session token for communication with your app's backend service.
-   * When the authenticated user (the user that logged into Shopify POS with their email address) doesn't have the correct app permissions enabled for your app, null will be returned. This is irrelevant of which POS Staff member is pinned in, as those are not authenticated users.
-   * For more information, see our [app permissions documentation](https://help.shopify.com/en/manual/your-account/users/roles/permissions/store-permissions#apps-and-channels-permissions).
-   * Calls to Shopify APIs must be made by your app’s backend service.
+   * Generates a fresh session token for secure communication with your app's backend service. Returns `undefined` when the authenticated user lacks proper app permissions. The token is a Shopify OpenID Connect ID Token that should be used in `Authorization` headers for backend API calls. This is based on the authenticated user, not the pinned staff member.
    */
   getSessionToken: () => Promise<string | undefined>;
 }
 
 /**
- * Access information on the current Session, including data on the current shop, user, staff and location.
+ * The `SessionApi` object provides access to current session information and authentication methods. Access these properties and methods through `shopify.session` to retrieve shop data and generate secure tokens. These methods enable secure API calls while maintaining user privacy and [app permissions](https://help.shopify.com/manual/your-account/users/roles/permissions/store-permissions#apps-and-channels-permissions).
  */
 export interface SessionApi {
   session: SessionApiContent;

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

@@ -1,5 +1,8 @@
 import {Storage} from '../../types/storage';
 
+/**
+ * The `StorageApi` object provides access to persistent local storage methods for your POS UI extension. Access these methods through `shopify.storage` to store, retrieve, and manage data that persists across sessions.
+ */
 export interface StorageApi {
   storage: Storage;
 }

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

@@ -1,16 +1,26 @@
+/**
+ * Specifies configuration options for displaying toast notifications. Controls the duration and display behavior of temporary notification messages.
+ */
 export interface ShowToastOptions {
+  /**
+   * The duration in milliseconds that the toast message should remain visible before automatically dismissing. If not specified, the toast will use the default system duration. Use shorter durations for simple confirmations and longer durations for important messages that users need time to read.
+   */
   duration?: number;
 }
 
 export interface ToastApiContent {
   /**
-   * Show a toast.
+   * Displays a toast notification with the specified text content. The message appears as a temporary overlay that automatically dismisses after the specified duration. Use for providing immediate user feedback, confirming actions, or communicating status updates without interrupting the user's workflow.
+   *
    * @param content The text content to display.
    * @param options An object containing ShowToastOptions.
    */
   show: (content: string, options?: ShowToastOptions) => void;
 }
 
+/**
+ * The `ToastApi` object provides methods for displaying temporary notification messages. Access these methods through `shopify.toast` to show user feedback and status updates.
+ */
 export interface ToastApi {
   toast: ToastApiContent;
 }

package/src/surfaces/point-of-sale/components/Badge.d.ts

@@ -12,18 +12,30 @@ import type {BadgeProps, Key, Ref} from './components-shared.d.ts';
 
 export type ComponentChildren = any;
 /**
- * Used when an element does not have children.
+ * The base props for elements without children, providing key, ref, and slot properties.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
+  /**
+   * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation.
+   */
   key?: Key;
+  /**
+   * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations.
+   */
   ref?: Ref<TClass>;
+  /**
+   * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component.
+   */
   slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base props for elements with children, extending `BaseElementProps` with children support.
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
+  /**
+   * The child elements to render within this component.
+   */
   children?: ComponentChildren;
 }
 export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
@@ -31,7 +43,14 @@ export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 declare const tagName = 's-badge';
 export interface BadgeJSXProps extends Pick<BadgeProps, 'id'> {
   /**
-   * Sets the tone of the Badge, based on the intention of the information being conveyed.
+   * Determines the visual appearance and semantic meaning of the badge. Badges rely on the tone system for semantic meaning, so using custom styling may not clearly convey meaning to merchants. Available options:
+   * - `'auto'` - Lets the system automatically choose the appropriate tone based on context.
+   * - `'neutral'` - Gray styling for general status information that doesn't require emphasis.
+   * - `'info'` - Blue styling for informational content and neutral updates.
+   * - `'success'` - Green styling for positive states, completed actions, and successful operations.
+   * - `'caution'` - Yellow styling for situations that need attention but aren't urgent.
+   * - `'warning'` - Orange styling for important notices that require merchant awareness.
+   * - `'critical'` - Red styling for errors, failures, and urgent issues requiring immediate action.
    *
    * @default 'auto'
    */
@@ -40,7 +59,7 @@ export interface BadgeJSXProps extends Pick<BadgeProps, 'id'> {
     'auto' | 'neutral' | 'info' | 'success' | 'warning' | 'critical' | 'caution'
   >;
   /**
-   * The content of the Badge.
+   * The child elements to render within this component.
    */
   children?: ComponentChildren;
 }

package/src/surfaces/point-of-sale/components/Banner.d.ts

@@ -17,18 +17,30 @@ import type {
 
 export type ComponentChildren = any;
 /**
- * Used when an element does not have children.
+ * The base props for elements without children, providing key, ref, and slot properties.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
+  /**
+   * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation.
+   */
   key?: Key;
+  /**
+   * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations.
+   */
   ref?: Ref<TClass>;
+  /**
+   * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component.
+   */
   slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base props for elements with children, extending `BaseElementProps` with children support.
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
+  /**
+   * The child elements to render within this component.
+   */
   children?: ComponentChildren;
 }
 export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
@@ -36,13 +48,19 @@ export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 declare const tagName = 's-banner';
 export interface BannerJSXProps extends Pick<BannerProps, 'heading' | 'id'> {
   /**
-   * Determines whether the banner is hidden.
+   * Controls whether the banner is visible or hidden. When set to `true`, the banner will be hidden from view. Use this to programmatically show or hide banners based on application state. Default is `false`.
    *
    * @default false
    */
   hidden?: BannerProps['hidden'];
   /**
-   * Sets the tone of the Banner, based on the intention of the information being conveyed.
+   * Sets the visual appearance of the banner. The tone determines the color scheme. Available options:
+   *
+   * - `'auto'` - Lets the system automatically choose the appropriate tone based on context.
+   * - `'success'` - Green styling for positive outcomes and successful operations.
+   * - `'info'` - Blue styling for general information and neutral updates.
+   * - `'warning'` - Orange styling for important notices that require attention.
+   * - `'critical'` - Red styling for errors and urgent issues requiring immediate action.
    *
    * @default 'auto'
    */
@@ -51,11 +69,11 @@ export interface BannerJSXProps extends Pick<BannerProps, 'heading' | 'id'> {
     'auto' | 'success' | 'info' | 'warning' | 'critical'
   >;
   /**
-   * The action taken when the Banner is pressed.
+   * The primary action element displayed within the banner, typically a button. Use this slot to provide interactive elements that allow users to respond to the banner's message, such as "Dismiss," "Learn More," or "Retry" buttons.
    */
   primaryAction?: ComponentChild;
   /**
-   * The content of the Banner.
+   * The child elements to render within this component.
    */
   children?: ComponentChildren;
 }

package/src/surfaces/point-of-sale/components/Box.d.ts

@@ -21,140 +21,137 @@ import type {
 
 export type ComponentChildren = any;
 /**
- * Used when an element does not have children.
+ * The base props for elements without children, providing key, ref, and slot properties.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
+  /**
+   * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation.
+   */
   key?: Key;
+  /**
+   * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations.
+   */
   ref?: Ref<TClass>;
+  /**
+   * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component.
+   */
   slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base props for elements with children, extending `BaseElementProps` with children support.
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
+  /**
+   * The child elements to render within this component.
+   */
   children?: ComponentChildren;
 }
 export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 
 declare const tagName = 's-box';
+/**
+ * Defines the available padding size options using a semantic scale. Provides consistent spacing values that align with the POS design system.
+ */
 export type PaddingKeyword = SizeKeyword | 'none';
 export interface BoxJSXProps {
   /**
-   * A unique identifier for the element.
+   * A unique identifier for the element used for targeting with CSS, JavaScript, or accessibility features.
    */
   id?: string;
   /**
-   * Adjust the block size.
+   * The block size of the container. Auto automatically sizes based on the container's children.
    *
    * @default 'auto'
    */
   blockSize?: SizeUnitsOrAuto;
   /**
-   * Adjust the inline size.
+   * The inline size of the container. Auto automatically sizes based on the container's children.
    *
    * @default 'auto'
    */
   inlineSize?: SizeUnitsOrAuto;
   /**
-   * Adjust the maximum block size.
+   * The maximum block size constraint for the container.
    *
    * @default 'none'
    */
   maxBlockSize?: SizeUnitsOrNone;
   /**
-   * Adjust the maximum inline size.
+   * The maximum inline size constraint for the container.
    *
    * @default 'none'
    */
   maxInlineSize?: SizeUnitsOrNone;
   /**
-   * Adjust the minimum block size.
+   * The minimum block size constraint for the container.
    *
    * @default '0'
    */
   minBlockSize?: SizeUnits;
   /**
-   * Adjust the minimum inline size.
+   * The minimum inline size constraint for the container.
    *
    * @default '0'
    */
   minInlineSize?: SizeUnits;
   /**
-   * Adjust the padding of all edges.
-   *
-   * [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) is
-   * supported. Note that, contrary to the CSS, it uses flow-relative values and the order is:
+   * The padding applied to all edges of the container. Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Shorthand_properties#edges_of_a_box) using flow-relative values in the order:
    *
    * - 4 values: `block-start inline-end block-end inline-start`
    * - 3 values: `block-start inline block-end`
    * - 2 values: `block inline`
    *
    * For example:
+   *
    * - `large` means block-start, inline-end, block-end and inline-start paddings are `large`.
    * - `large none` means block-start and block-end paddings are `large`, inline-start and inline-end paddings are `none`.
    * - `large none large` means block-start padding is `large`, inline-end padding is `none`, block-end padding is `large` and inline-start padding is `none`.
    * - `large none large small` means block-start padding is `large`, inline-end padding is `none`, block-end padding is `large` and inline-start padding is `small`.
    *
-   * A padding value of `auto` will use the default padding for the closest container that has had its usual padding removed.
+   * An `auto` value inherits the default padding from the closest container that has removed its usual padding.
    *
    * @default 'none'
    */
   padding?: MaybeAllValuesShorthandProperty<PaddingKeyword>;
   /**
-   * Adjust the block-padding.
-   *
-   * - `large none` means block-start padding is `large`, block-end padding is `none`.
-   *
-   * This overrides the block value of `padding`.
+   * The block-axis padding for the container. Overrides the block value of the `padding` property.
    *
    * @default '' - meaning no override
    */
   paddingBlock?: MaybeTwoValuesShorthandProperty<PaddingKeyword> | '';
   /**
-   * Adjust the block-start padding.
-   *
-   * This overrides the block-start value of `paddingBlock`.
+   * The block-start padding for the container. Overrides the block-start value of the `paddingBlock` property.
    *
    * @default '' - meaning no override
    */
   paddingBlockStart?: PaddingKeyword | '';
   /**
-   * Adjust the block-end padding.
-   *
-   * This overrides the block-end value of `paddingBlock`.
+   * The block-end padding for the container. Overrides the block-end value of the `paddingBlock` property.
    *
    * @default '' - meaning no override
    */
   paddingBlockEnd?: PaddingKeyword | '';
   /**
-   * Adjust the inline padding.
-   *
-   * - `large none` means inline-start padding is `large`, inline-end padding is `none`.
-   *
-   * This overrides the inline value of `padding`.
+   * The inline-axis padding for the container. Supports two-value syntax where `large none` sets inline-start to `large` and inline-end to `none`. Overrides the inline value of the `padding` property.
    *
    * @default '' - meaning no override
    */
   paddingInline?: MaybeTwoValuesShorthandProperty<PaddingKeyword> | '';
   /**
-   * Adjust the inline-start padding.
-   *
-   * This overrides the inline-start value of `paddingInline`.
+   * The inline-start padding for the container. Overrides the inline-start value of the `paddingInline` property.
    *
    * @default '' - meaning no override
    */
   paddingInlineStart?: PaddingKeyword | '';
   /**
-   * Adjust the inline-end padding.
-   *
-   * This overrides the inline-end value of `paddingInline`.
+   * The inline-end padding for the container. Overrides the inline-end value of the `paddingInline` property.
    *
    * @default '' - meaning no override
    */
   paddingInlineEnd?: PaddingKeyword | '';
   /**
-   * The content of the Box.
+   * The child elements to render within this component.
    */
   children?: ComponentChildren;
 }