@shopify/ui-extensions 2025.10.8 → 2025.10.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopify/ui-extensions",
-  "version": "2025.10.8",
+  "version": "2025.10.9",
   "scripts": {
     "docs:admin": "node ./docs/surfaces/admin/build-docs.mjs",
     "docs:checkout": "bash ./docs/surfaces/checkout/build-docs.sh",
@@ -152,6 +152,11 @@
     "access": "public",
     "@shopify:registry": "https://registry.npmjs.org/"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Shopify/ui-extensions.git",
+    "directory": "packages/ui-extensions"
+  },
   "files": [
     "build",
     "src",

package/src/shared.ts

@@ -940,15 +940,15 @@ export interface GraphQLError {
 }
 
 /**
- * Represents a read-only value managed on the main thread that an extension can subscribe to.
- *
- * Example: Checkout uses this to manage the state of an object and
- * communicate state changes to extensions running in a sandboxed web worker.
- *
- * This interface is compatible with [Preact's ReadonlySignal](https://github.com/preactjs/signals/blob/a023a132a81bd4ba4a0bebb8cbbeffbd8c8bbafc/packages/core/src/index.ts#L700-L709).
- *
+ * Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern.
  */
 export interface ReadonlySignalLike<T> {
+  /**
+   * The current value of the locale string in IETF format. For example, `"en-US"`, `"fr-CA"`, or `"de-DE"`. This property provides immediate access to the current locale without requiring subscription setup. Use for one-time locale checks or initial internationalization setup.
+   */
   readonly value: T;
+  /**
+   * Subscribes to locale changes and calls the provided function whenever the locale updates. Returns an unsubscribe function to clean up the subscription. Use to automatically update your extension content when merchants change their language settings during POS sessions.
+   */
   subscribe(fn: (value: T) => void): () => void;
 }

package/src/surfaces/admin/api/intents/examples/edit-metafield-definition.js

@@ -2,6 +2,7 @@ const {intents} = useApi(TARGET);
 
 const activity = await intents.invoke('edit:shopify/MetafieldDefinition', {
   value: 'gid://shopify/MetafieldDefinition/123456789',
+  data: {ownerType: 'product'},
 });
 
 const response = await activity.complete;

package/src/surfaces/admin/api/intents/examples/edit-metaobject-definition.js

@@ -1,7 +1,7 @@
 const {intents} = useApi(TARGET);
 
 const activity = await intents.invoke('edit:shopify/MetaobjectDefinition', {
-  value: 'gid://shopify/MetaobjectDefinition/123456789',
+  data: {type: 'my_metaobject_definition_type'},
 });
 
 const response = await activity.complete;

package/src/surfaces/admin/components/Icon/icon-data.json

@@ -0,0 +1,9 @@
+{
+  "iconPreviewData": {
+    "jsxFile": "./templates/icon-renderer/icon-preview.jsx",
+    "icons": "__AUTO_GENERATED_ICONS__",
+    "bodyContent": "<div id=\"app\"></div>",
+    "customStyles": "padding: 0px; margin: 0px; margin-top: 8px; max-width: 584px; overflow: hidden; background: #FFF, border: 1px solid #ccc; border-radius: 8px;",
+    "hashes": "__AUTO_GENERATED_HASHES__"
+  }
+}

package/src/surfaces/point-of-sale/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 `shopify.action` to launch full-screen modal experiences.
  */
 export interface ActionApi {
   action: ActionApiContent;

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

@@ -11,31 +11,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 `shopify.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 read-only access to the current cart state and allows subscribing to cart changes.
-   * The `value` property provides the current cart state, and `subscribe` allows listening to changes.
+   * Provides read-only access to the current cart state and allows subscribing to cart changes. The `value` property provides the current cart state, and `subscribe` allows listening to changes with improved performance and memory management.
    */
   current: ReadonlySignalLike<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
@@ -48,84 +55,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.
-   * Returns the uuid of the line item added, or the empty string if the user dismissed an oversell guard modal without adding anything.
-   * Throws if POS fails to add the line item. Throws if POS fails to add the line item.
+   * 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, or the empty string if the user dismissed an oversell guard modal
+   * @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
@@ -136,7 +141,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.
    */
@@ -145,7 +150,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
@@ -153,7 +158,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')
@@ -168,7 +173,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.
    */
@@ -177,14 +182,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.
@@ -195,35 +200,35 @@ 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
    */
   updateDefaultAddress(addressId: number): Promise<void>;
 
   /**
-   * Add a selling plan to a line item in the cart.
+   * Add a selling plan to a line item in the cart using the line item `UUID`, selling plan `ID`, and selling plan name. Optionally provide delivery interval and interval count for improved performance, otherwise POS will fetch them after syncing the cart.
    *
    * @param uuid the uuid of the line item that should receive the selling plan
    * @param sellingPlanId the ID of the selling plan to add to the line item
@@ -231,7 +236,7 @@ export interface CartApiContent {
   addLineItemSellingPlan(input: SetLineItemSellingPlanInput): Promise<void>;
 
   /**
-   * Remove the selling plan from a line item in the cart.
+   * Remove the selling plan from a line item in the cart using the line item `UUID`. This will clear any subscription or recurring purchase configuration from the line item.
    *
    * @param uuid the uuid of the line item whose selling plan should be removed
    */

package/src/surfaces/point-of-sale/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/api/connectivity-api/connectivity-api.ts

@@ -2,23 +2,25 @@ import type {ReadonlySignalLike} from '../../../../shared';
 
 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
+   * The Internet connection status of the POS device.
    */
   internetConnected: ConnectivityStateSeverity;
 }
 
 export interface ConnectivityApiContent {
   /**
-   * Provides read-only access to the current connectivity state and allows subscribing to connectivity changes.
-   * The `value` property provides the current connectivity state, and `subscribe` allows listening to changes.
+   * Provides read-only access to the current connectivity state and allows subscribing to connectivity changes. Use for implementing connectivity-aware functionality and reactive connectivity handling.
    */
   current: ReadonlySignalLike<ConnectivityState>;
 }
 
 /**
- * Access information about the device connectivity
+ * The `ConnectivityApi` object provides access to current connectivity information and change notifications. Access these properties through `shopify.connectivity` to monitor network status.
  */
 export interface ConnectivityApi {
   connectivity: ConnectivityApiContent;

package/src/surfaces/point-of-sale/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;
 }

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

@@ -1,20 +1,20 @@
 export interface DeviceApiContent {
   /**
-   * The name of the device
+   * The name of the device as configured by the merchant or system. Use for displaying device information in interfaces, logging, or support contexts where device identification is helpful.
    */
   name: string;
   /**
-   * The string ID of the device
+   * Retrieves the unique string identifier for the device. Returns a promise that resolves to the device ID. Use for device-specific data storage, analytics tracking, or implementing device-based permissions and configurations.
    */
   getDeviceId(): Promise<string>;
   /**
-   * Whether the device is a tablet
+   * Determines whether the device is a tablet form factor. Returns a promise that resolves to `true` for tablets, `false` for other device types. Use for implementing responsive design, optimizing touch targets, or providing device-appropriate user experiences.
    */
   isTablet(): Promise<boolean>;
 }
 
 /**
- * Access information about the device, like name and ID
+ * The `DeviceApi` object provides access to device information and capabilities. Access these properties and methods through `shopify.device` to retrieve device details and check device characteristics.
  */
 export interface DeviceApi {
   device: DeviceApiContent;

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

@@ -1,20 +1,23 @@
+/**
+ * The `DraftOrderApi` object provides access to draft order data in draft order-specific extension contexts. Access this property through `shopify.draftOrder` to retrieve information about the draft order currently being viewed or interacted with in the POS interface.
+ */
 export interface DraftOrderApi {
   draftOrder: DraftOrderApiContent;
 }
 
 export interface DraftOrderApiContent {
   /**
-   * The unique identifier for the draft order
+   * The unique identifier for the draft order. Use for draft order lookups, implementing order-specific functionality, and integrating with external systems.
    */
   id: number;
 
   /**
-   * The name of the draft order
+   * The name of the draft order as configured by the merchant. Use for draft order identification, displays, and customer-facing interfaces.
    */
   name: string;
 
   /**
-   * The unique identifier of the customer associated with the draft order
+   * The unique identifier of the customer associated with the draft order. Returns `undefined` if no customer is associated. Use for customer-specific functionality and personalized experiences.
    */
   customerId?: number;
 }

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

@@ -2,14 +2,13 @@ import type {ReadonlySignalLike} from '../../../../shared';
 
 export interface LocaleApiContent {
   /**
-   * Provides read-only access to the current IETF-formatted locale and allows subscribing to locale changes.
-   * The `value` property provides the current locale, and `subscribe` allows listening to changes.
+   * Provides read-only access to the current IETF-formatted locale and allows subscribing to locale changes. The `value` property provides the current locale, and `subscribe` allows listening to changes. Use for internationalization, locale-specific formatting, and reactive updates when merchants change language settings.
    */
   current: ReadonlySignalLike<string>;
 }
 
 /**
- * Access the merchant’s current locale (in [IETF format](https://en.wikipedia.org/wiki/IETF_language_tag)) to internationalize your extension content.
+ * The `LocaleApi` object provides access to current locale information and change notifications. Access these properties through `shopify.locale` to retrieve and monitor locale data.
  */
 export interface LocaleApi {
   locale: LocaleApiContent;

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

@@ -1,44 +1,52 @@
+/**
+ * Specifies configuration options for navigation operations. Allows passing state data that persists across navigation transitions.
+ */
 export interface NavigationNavigateOptions {
   /**
-   * Developer-defined information to be stored in the associated NavigationHistoryEntry once the navigation is complete, retrievable via getState().
+   * Developer-defined information to be stored in the associated `NavigationHistoryEntry` once the navigation is complete, retrievable using `getState()`. Use to pass data between navigation states or implement stateful navigation workflows.
    */
   state?: unknown;
 }
 
 /**
- * The NavigationHistoryEntry interface of the Navigation API represents a single navigation history entry.
+ * Represents a single entry in the navigation history stack. Contains the URL and unique identifier for tracking navigation state and implementing history-based navigation.
  */
 export interface NavigationHistoryEntry {
-  /** Returns the key of the history entry. This is a unique, UA-generated value that represents the history entry's slot in the entries list rather than the entry itself. */
+  /**
+   * A unique, UA-generated value that represents the history entry's slot in the entries list rather than the entry itself. Use for tracking navigation history or implementing navigation-based logic.
+   */
   key: string;
   /**
-   * Returns the URL of this history entry.
+   * The URL of this history entry. Returns `null` if no URL is associated with the entry. Use for URL-based navigation logic, deep-linking, or displaying current location information.
    */
   url: string | null;
   /**
-   * Returns a clone of the available state associated with this history entry.
+   * Returns a clone of the available state associated with this history entry. Use to retrieve navigation state data that was passed during navigation or to implement state-based navigation logic.
    */
   getState(): unknown;
 }
 
 export interface Navigation {
   /**
-   * The navigate() method navigates to a specific URL, updating any provided state in the history entries list.
+   * Navigates to a specific URL, updating any provided state in the history entries list. Returns a promise that resolves when navigation is complete. Use for programmatic navigation between screens, implementing custom navigation controls, or deep-linking to specific modal states.
    */
   navigate: (url: string, options?: NavigationNavigateOptions) => Promise<void>;
   /**
-   * The currentEntry read-only property of the Navigation interface returns a NavigationHistoryEntry object representing the location the user is currently navigated to right now.
+   * Returns a `NavigationHistoryEntry` object representing the location the user is currently navigated to. Use to access current URL, navigation state, or implement navigation-aware functionality based on the current location.
    */
   currentEntry: NavigationHistoryEntry;
   /**
-   * The back() method of the Navigation interface navigates to the previous entry in the history list.
+   * Navigates to the previous entry in the history list. Use for implementing back buttons, breadcrumb navigation, or allowing users to return to previous screens in multi-step workflows.
    */
   back(): void;
 }
 
+/**
+ * The global `window` object provides control over the extension modal lifecycle. Access these properties and methods directly through the global `window` object to manage the modal interface programmatically.
+ */
 export interface Window {
   /**
-   * The close() method of the window interface closes the extension screen.
+   * Closes the extension screen and dismisses the modal interface. Use to programmatically close the modal after completing a workflow, canceling an operation, or when user action is no longer required. This provides the same behavior as the user dismissing the modal through the UI.
    */
   close(): void;
 }

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

@@ -1,26 +1,26 @@
 /**
- * Interface to access the order
+ * The `OrderApi` object provides access to order data in order-specific extension contexts. Access this property through `shopify.order` to retrieve information about the order currently being viewed or interacted with in the POS interface.
  */
 export interface OrderApi {
   order: OrderApiContent;
 }
 
 /**
- * Interface for Order details
+ * The `OrderApi` object provides access to order data. Access this property through `shopify.order` to interact with the current order context.
  */
 export interface OrderApiContent {
   /**
-   * The unique identifier for the order
+   * The unique identifier for the order. Use for order lookups, implementing order-specific functionality, and integrating with external systems.
    */
   id: number;
 
   /**
-   * The name of the order
+   * The name of the order as configured by the merchant. Use for order identification, displays, and customer-facing interfaces.
    */
   name: string;
 
   /**
-   * The unique identifier of the customer associated with the order
+   * The unique identifier of the customer associated with the order. Returns `undefined` if no customer is associated. Use for customer-specific functionality and personalized experiences.
    */
   customerId?: number;
 }

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

@@ -1,18 +1,14 @@
 import {PinPadOptions, PinValidationResult} from '../types/pin-pad';
 
 export interface PinPadApiContent {
-  /** Shows a PIN pad to the user in a modal dialog.
+  /**
+   * Shows a PIN pad to the user in a modal dialog. The `onSubmit` function is called when the PIN is submitted and should validate the PIN, returning `'accept'` or `'reject'`.
    *
-   * `onSubmit` is called when the PIN is submitted for validation by the user. The callback
-   * should validate the PIN and accept or reject it.
+   * • **When accepted**: Modal dismisses and triggers the `onDismissed` callback—perform any post-validation navigation in this callback rather than in `onSubmit`.
    *
-   * If the PIN is accepted, the modal will be dismissed and the `onDismissed` callback
-   * (provided via `options`) will be called. It is recommended that any post-validation
-   * navigation is performed in this callback rather than in `onSubmit`.
-   *
-   * If the PIN is rejected, the optional `errorMessage` will be displayed to the user and the modal
-   * will not be dismissed.
+   * • **When rejected**: Displays the optional `errorMessage` and keeps the modal open.
    *
+   * Use for implementing secure authentication workflows, access control, or PIN-based verification systems.
    */
   showPinPad(
     onSubmit: (
@@ -23,7 +19,7 @@ export interface PinPadApiContent {
 }
 
 /**
- * Access the PIN Pad API for PIN pad functionality in a modal.
+ * The `PinPadApi` object provides methods for displaying secure PIN entry interfaces. Access these methods through `shopify.pinPad` to show PIN pad modals and handle PIN validation.
  */
 export interface PinPadApi {
   pinPad: PinPadApiContent;