Merge pull request #3560 from Shopify/pos-ui-extensions-2026-01-api-prop-descriptions

[POS UI extensions]: Improved target, API, component descriptions for 2026-01

Author: mcvinci

packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/action-api.doc.ts

@@ -7,47 +7,60 @@ const generateJsxCodeBlockForActionApi = (title: string, fileName: string) =>
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Action API',
-  description: `
-The Action API allows an action extension to modally present its corresponding modal target.
-
-#### Supporting targets
-- ${TargetLink.PosHomeTileRender}
-- ${TargetLink.PosPurchasePostActionMenuItemRender}
-- ${TargetLink.PosPurchasePostBlockRender}
-- ${TargetLink.PosOrderDetailsActionMenuItemRender}
-- ${TargetLink.PosOrderDetailsBlockRender}
-- ${TargetLink.PosProductDetailsActionMenuItemRender}
-- ${TargetLink.PosProductDetailsBlockRender}
-- ${TargetLink.PosCustomerDetailsActionMenuItemRender}
-- ${TargetLink.PosCustomerDetailsBlockRender}
-- ${TargetLink.PosDraftOrderDetailsActionMenuItemRender}
-- ${TargetLink.PosDraftOrderDetailsBlockRender}
-`,
+  description:
+    'The Action API provides modal presentation functionality for POS UI extensions, allowing you to launch full-screen modal interfaces from menu items, tiles, and block targets. The API enables navigation between different targets within your extension.',
   isVisualComponent: false,
   type: 'APIs',
   definitions: [
     {
       title: 'ActionApi',
-      description: '',
+      description:
+        'The `ActionApi` object provides methods for presenting modal interfaces. Access these methods through `shopify.action` to launch full-screen modal experiences.',
       type: 'ActionApiContent',
     },
   ],
-  category: 'APIs',
+  category: 'Target APIs',
+  subCategory: 'Standard APIs',
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `
+- **Use modals for complex workflows:** Reserve for operations requiring more space, multiple steps, or complex interactions.
+- **Provide clear entry points:** Use descriptive button labels and titles that indicate what the modal will contain.
+- **Handle dismissal gracefully:** Save progress when possible and provide feedback about incomplete operations.
+`,
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `
+Each extension can only present one modal at a time. Subsequent calls to \`presentModal()\` while a modal is already open may be ignored or replace the current modal.
+`,
+    },
+  ],
   related: [],
   examples: {
-    description: 'Examples of using the Action API.',
+    description:
+      'Learn how to launch modal workflows from menu items, tiles, and blocks.',
     examples: [
       {
         codeblock: generateJsxCodeBlockForActionApi(
-          'Present a modal from post purchase.',
+          'Launch a modal from a menu item',
           'present-modal',
         ),
+        description:
+          'Present a full-screen modal from menu item actions in detail screens. This example shows how to use `shopify.action.presentModal()` to launch a modal workflow from post-purchase, order details, or other action menu item contexts, enabling complex multi-step operations.',
       },
       {
         codeblock: generateJsxCodeBlockForActionApi(
-          'Present a modal from smart grid.',
+          'Launch a modal from a smart grid tile',
           'present-modal-tile',
         ),
+        description:
+          'Present a full-screen modal from smart grid tiles on the POS home screen. This example demonstrates using `shopify.action.presentModal()` to launch modal workflows from tile interactions, perfect for high-frequency tasks that require additional UI beyond the tile itself.',
       },
     ],
   },

packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/cart-api.doc.ts

@@ -9,44 +9,59 @@ const generateJsxCodeBlockForCartLineItemApi = (
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Cart Line Item API',
-  description: `
-The Cart Line Item API provides an extension with data about the current Cart Line Item.
-
-#### Supporting targets
-- ${TargetLink.PosCartLineItemDetailsActionMenuItemRender}
-- ${TargetLink.PosCartLineItemDetailsActionRender}
-`,
+  description:
+    'The Cart Line Item API provides read-only access to a specific line item in the cart. Use this API to get line item details like product information, pricing, discounts, and custom properties. This allows you to build features that respond to the specific item a customer is viewing or interacting with.',
   isVisualComponent: false,
   type: 'APIs',
   definitions: [
     {
       title: 'CartLineItemApi',
-      description: '',
+      description:
+        'The `CartLineItemApi` object provides access to the current line item. Access this property through `api.cartLineItem` to interact with the current line item context.',
       type: 'CartLineItemApi',
     },
   ],
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `
+- **Handle optional properties:** Check for \`undefined\` in optional properties like \`price\`, \`productId\`, \`title\`, \`sku\`, and vendor before use.
+- **Create contextual experiences:** Use line item data to show different interfaces for gift cards, subscriptions, or vendor-specific information.
+- **Implement item-specific validation:** Use properties like \`taxable\`, \`isGiftCard\`, and \`requiresSellingPlan\` for appropriate business logic.
+- **Handle selling plans:** When working with subscriptions, check \`requiresSellingPlan\` and \`sellingPlan\` to provide appropriate subscription management.
+- **Access related data efficiently:** Use \`productId\` and \`variantId\` to fetch additional info when needed, but avoid unnecessary API calls.
+`,
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `
+- The API provides read-only access to line item data—use the Cart API for modifying line item properties, discounts, selling plans, or other attributes.
+- Line item data reflects the current state and may not include real-time inventory, pricing, or selling plan updates until the cart is refreshed.
+- Selling plan information may be limited during refund or exchange operations where digest values aren't available.
+`,
+    },
+  ],
   examples: {
-    description: 'Examples of using the Cart Line Item API.',
+    description:
+      'Learn how to access line item information in cart line item contexts.',
     examples: [
       {
         codeblock: generateJsxCodeBlockForCartLineItemApi(
-          'Retrieve the ID of the cart line item.',
+          'Display the cart line item ID',
           'id',
         ),
+        description:
+          'Access the unique identifier of the current cart line item in line item detail contexts. This example shows how to use `shopify.cartLineItem.id` to retrieve the line item ID, which can be used for modifying the item, applying discounts, or implementing item-specific functionality.',
       },
     ],
   },
-  category: 'APIs',
-  related: [
-    {
-      name: ExtensionTargetType.PosCartLineItemDetailsActionMenuItemRender,
-      url: '/docs/api/pos-ui-extensions/targets/pos-cart-line-item-details-action-menu-item-render',
-    },
-    {
-      name: ExtensionTargetType.PosCartLineItemDetailsActionRender,
-      url: '/docs/api/pos-ui-extensions/targets/pos-cart-line-item-details-action-render',
-    },
-  ],
+  category: 'Target APIs',
+  subCategory: 'Contextual APIs',
+  related: [],
 };
 
 export default data;

packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/cart-line-item-api.doc.ts

@@ -9,41 +9,57 @@ const generateJsxCodeBlockForCashDrawerApi = (
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Cash Drawer API',
-  description: `
-The Cash Drawer API is an API exposed to extensions for cash drawer functionality, specifically allowing UI extensions to control cash drawer operations.
-
-#### Supporting targets
-- ${TargetLink.PosHomeTileRender}
-- ${TargetLink.PosHomeModalRender}
-- ${TargetLink.PosPurchasePostActionMenuItemRender}
-- ${TargetLink.PosPurchasePostActionRender}
-- ${TargetLink.PosPurchasePostBlockRender}
-- ${TargetLink.PosReturnPostActionMenuItemRender}
-- ${TargetLink.PosReturnPostActionRender}
-- ${TargetLink.PosReturnPostBlockRender}
-- ${TargetLink.PosExchangePostActionMenuItemRender}
-- ${TargetLink.PosExchangePostActionRender}
-- ${TargetLink.PosExchangePostBlockRender}
-`,
+  description:
+    'The Cash Drawer API provides programmatic control over cash drawer hardware connected to POS devices. Use this API to trigger cash drawer operations for manual cash handling, custom payment workflows, or register management tasks.',
   isVisualComponent: false,
   type: 'APIs',
   definitions: [
     {
       title: 'CashDrawerApi',
-      description: 'Interface for handling cash drawer operations.',
-      type: 'CashDrawerApi',
+      description:
+        'The `CashDrawerApi` object provides methods for controlling cash drawer hardware. Access these methods through `shopify.cashDrawer` to trigger cash drawer operations.',
+      type: 'CashDrawerApiContent',
+    },
+  ],
+  category: 'Target APIs',
+  subCategory: 'Platform APIs',
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `
+- **Implement error handling:** Wrap \`cashDrawer.open()\` calls in try-catch blocks. Show clear error messages with resolution steps.
+- **Require authorization:** Implement authorization checks before opening for non-transaction operations. Consider PIN entry, manager approval, or staff permissions.
+- **Provide user feedback:** Show immediate confirmations like "Cash drawer opened successfully" so staff know the operation completed.
+- **Log operations for audit:** Track all openings including timestamps, staff info, and reason for loss prevention and compliance.
+- **Test without hardware:** Handle scenarios where no drawer is connected with fallback workflows or clear messaging.
+- **Consider timing:** Open at appropriate moments. Avoid opening multiple times in quick succession or in inappropriate workflow states.
+`,
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `
+- The Cash Drawer API requires compatible cash drawer hardware connected to the POS device through supported peripheral connections (USB, network, or Bluetooth depending on device and hardware model).
+- The API only triggers the drawer opening mechanism and cannot detect whether the drawer is currently open, closed, or physically jammed. Your extension is responsible for any required state tracking.
+- Cash drawer operations are subject to POS hardware capabilities and may not be available on all device configurations. The API will return errors on devices without cash drawer support.
+`,
     },
   ],
-  category: 'APIs',
   related: [],
   examples: {
-    description: 'Examples of using the Cash Drawer API',
+    description:
+      'Learn how to programmatically control cash drawer hardware operations.',
     examples: [
       {
         codeblock: generateJsxCodeBlockForCashDrawerApi(
-          'Open the cash drawer',
+          'Trigger the cash drawer to open',
           'default.example',
         ),
+        description:
+          'Open the cash drawer programmatically for manual cash handling or custom workflows. This example shows how to use `shopify.cashDrawer.open()` to trigger the connected cash drawer hardware, useful for no-sale transactions, manual cash operations, or register management tasks that require direct cash access.',
       },
     ],
   },

packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/cash-drawer-api.doc.ts

@@ -9,26 +9,54 @@ const generateJsxCodeBlockForConnectivityApi = (
 const data: ReferenceEntityTemplateSchema = {
   name: 'Connectivity API',
   description:
-    'The Connectivity API enables POS UI extensions to retrieve device connectivity information, such as whether the device has an internet connection.',
+    'The Connectivity API provides access to device connectivity information, allowing you to monitor Internet connection status and respond to connectivity changes in real-time. The API enables both immediate connectivity checks and dynamic updates when network conditions change.',
   isVisualComponent: false,
   type: 'APIs',
   definitions: [
     {
       title: 'ConnectivityApi',
-      description: '',
+      description:
+        'The `ConnectivityApi` object provides access to current connectivity information and change notifications. Access these properties through `shopify.connectivity` to monitor network status.',
       type: 'ConnectivityApiContent',
     },
   ],
-  category: 'APIs',
+  category: 'Target APIs',
+  subCategory: 'Platform APIs',
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `
+- **Handle changes gracefully:** Use \`subscribe\` to adapt behavior when connectivity changes.
+- **Design for network interruptions:** Inform users when network-dependent features are unavailable and provide guidance.
+- **Display connectivity status:** Show status when it affects functionality to help users understand limitations.
+- **Queue operations during outages:** Implement queuing for non-critical operations that can be deferred until connectivity is restored.
+`,
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `
+- The Connectivity API provides read-only access to connectivity information and can't be used to control or modify network settings on the device.
+- Connectivity status reflects Internet connectivity only and may not indicate the quality or speed of the connection, which could affect API performance.
+- The API monitors general Internet connectivity but doesn't provide specific information about Shopify service availability or API endpoint availability.
+`,
+    },
+  ],
   related: [],
   examples: {
-    description: 'Examples of using the Connectivity API',
+    description:
+      'Learn how to monitor network connectivity status and respond to connectivity changes.',
     examples: [
       {
         codeblock: generateJsxCodeBlockForConnectivityApi(
-          'Subscribe to connectivity changes.',
+          'Monitor network connectivity changes',
           'subscribe',
         ),
+        description:
+          'Subscribe to connectivity changes to monitor network status in real time. This example demonstrates using `shopify.connectivity.subscribe()` and `shopify.connectivity.connected` to detect when the device goes online or offline, enabling adaptive behavior for offline-capable features or network-dependent operations.',
       },
     ],
   },

packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/connectivity-api.doc.ts

@@ -7,45 +7,56 @@ const generateJsxCodeBlockForCustomerApi = (title: string, fileName: string) =>
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Customer API',
-  description: `
-The customer API provides an extension with data about the current customer.
-
-#### Supporting targets
-- ${TargetLink.PosCustomerDetailsActionMenuItemRender}
-- ${TargetLink.PosCustomerDetailsActionRender}
-- ${TargetLink.PosCustomerDetailsBlockRender}
-`,
+  description:
+    'The Customer API provides read-only access to customer data. Use this API to get customer information and build personalized experiences based on the selected customer context. The API offers the customer identifier for linking to customer data and enabling customer-specific features.',
   isVisualComponent: false,
   type: 'APIs',
   definitions: [
     {
       title: 'CustomerApi',
-      description: '',
+      description:
+        'The `CustomerApi` object provides access to customer data. Access this property through `shopify.customer` to interact with the current customer context.',
       type: 'CustomerApiContent',
     },
   ],
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `
+- **Use customer ID for lookups:** Fetch additional customer information from external systems or Shopify APIs using the customer ID.
+- **Enable personalized features:** Use customer context for customer-specific pricing, loyalty programs, or product recommendations.
+- **Validate customer access:** Verify the customer ID is valid before performing operations or API calls.
+`,
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `
+- The API provides only the customer identifier—use Shopify APIs or external systems to fetch additional customer details like name, email, or purchase history.
+- Customer data reflects the current POS session and may not include real-time updates from other channels until the session is refreshed.
+`,
+    },
+  ],
   examples: {
-    description: 'Examples of using the Customer API.',
+    description:
+      'Learn how to access customer information in customer detail contexts.',
     examples: [
       {
         codeblock: generateJsxCodeBlockForCustomerApi(
-          'Retrieve the ID of the customer.',
+          'Display the customer ID',
           'id',
         ),
+        description:
+          'Access the unique identifier of the current customer in a customer detail context. This example shows how to use `shopify.customer.id` to retrieve the customer ID, which can be used for fetching additional customer data, implementing loyalty features, or building personalized customer experiences.',
       },
     ],
   },
-  category: 'APIs',
-  related: [
-    {
-      name: ExtensionTargetType.PosCustomerDetailsActionMenuItemRender,
-      url: '/docs/api/pos-ui-extensions/targets/pos-customer-details-action-menu-item-render',
-    },
-    {
-      name: ExtensionTargetType.PosCustomerDetailsActionRender,
-      url: '/docs/api/pos-ui-extensions/targets/pos-customer-details-action-render',
-    },
-  ],
+  category: 'Target APIs',
+  subCategory: 'Contextual APIs',
+  related: [],
 };
 
 export default data;