[POS UI extensions]: Improved target, API, component descriptions for 2025-10

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

@@ -7,47 +7,58 @@ 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',
   related: [],
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent:
+        "- **Use modals for complex workflows:** Reserve modals for operations that genuinely require more screen space, multiple steps, or complex interactions that can't be handled by simple button actions.\n" +
+        '- **Provide clear entry points:** Use descriptive button labels and titles that clearly indicate what the modal will contain or what action it will perform, helping users understand what to expect.\n' +
+        '- **Handle modal dismissal gracefully:** Ensure your modal-based workflows handle user dismissal, saving progress when possible and providing clear 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.',
+    },
+  ],
   examples: {
-    description: 'Examples of using the Action API.',
+    description:
+      'Learn how to present full-screen modals from tiles and menu items using the Action API.',
     examples: [
       {
         codeblock: generateJsxCodeBlockForActionApi(
-          'Present a modal from post purchase.',
+          'Open a modal from a post-purchase action',
           'present-modal',
         ),
+        description:
+          "Create an action menu item that appears after a purchase is completed. When pressed, it launches a full-screen modal view using the Action API's `presentModal()` method, allowing you to display custom workflows or additional functionality in the post-purchase flow.",
       },
       {
         codeblock: generateJsxCodeBlockForActionApi(
-          'Present a modal from smart grid.',
+          'Open a modal from a smart grid tile',
           'present-modal-tile',
         ),
+        description:
+          "Create a smart grid tile on the POS home screen that launches a full-screen modal when tapped. This example shows how to use the Action API to present detailed views or workflows from your app's home tile, providing quick access to extended functionality.",
       },
     ],
   },

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

@@ -9,42 +9,55 @@ 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',
     },
   ],
   examples: {
-    description: 'Examples of using the Cart Line Item API.',
+    description:
+      'Learn how to access line item information in cart line item action contexts.',
     examples: [
       {
         codeblock: generateJsxCodeBlockForCartLineItemApi(
-          'Retrieve the ID of the cart line item.',
+          'Display the line item ID',
           'id',
         ),
+        description:
+          'Access the unique identifier of the current line item in a cart line item action context. This example shows how to use `shopify.cartLineItem.id` to retrieve the line item ID, which can be used for tracking, analytics, or performing operations on the specific item.',
       },
     ],
   },
-  category: 'APIs',
-  related: [
+  category: 'Target APIs',
+  subCategory: 'Contextual APIs',
+  related: [],
+  subSections: [
     {
-      name: ExtensionTargetType.PosCartLineItemDetailsActionMenuItemRender,
-      url: '/docs/api/pos-ui-extensions/targets/pos-cart-line-item-details-action-menu-item-render',
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent:
+        '- **Handle optional properties gracefully:** Check for `undefined` values in optional properties like `price`, `productId`, `title`, `sku`, `vendor`, and selling plan-related fields before using them in your extension logic.\n' +
+        '- **Use line item context effectively:** Use the line item data to create contextual experiences—for example, showing different interfaces for gift cards versus regular products, subscription items versus one-time purchases, or displaying vendor-specific information.\n' +
+        '- **Implement item-specific validation:** Use line item properties like `taxable`, `isGiftCard`, `requiresSellingPlan`, and `hasSellingPlanGroups` to implement appropriate validation and business logic for different item types.\n' +
+        '- **Handle selling plans appropriately:** When working with subscription products, check `requiresSellingPlan` and `sellingPlan` properties.\n' +
+        '- **Access related data efficiently:** Use `productId` and `variantId` to fetch additional product information when needed, but avoid unnecessary API calls by using the data already available in the line item.',
     },
     {
-      name: ExtensionTargetType.PosCartLineItemDetailsActionRender,
-      url: '/docs/api/pos-ui-extensions/targets/pos-cart-line-item-details-action-render',
+      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.\n' +
+        '- Line item data reflects the current state and may not include real-time inventory, pricing, or selling plan updates until the cart is refreshed.\n' +
+        "- Selling plan information may be limited during refund or exchange operations where digest values aren't available.",
     },
   ],
 };

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

@@ -9,26 +9,52 @@ 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',
   related: [],
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent:
+        '- **Handle connectivity changes gracefully:** Use the `subscribe` method to automatically adapt your extension behavior when connectivity changes.\n' +
+        '- **Design for connectivity awareness:** Design your extension to handle network interruptions, informing users when network-dependent features are unavailable and providing clear guidance on next steps.\n' +
+        '- **Provide clear connectivity feedback:** Display connectivity status to users when it affects functionality, helping them understand why certain features may be limited or unavailable.\n' +
+        '- **Queue operations during outages:** Implement queuing mechanisms 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.\n" +
+        '- Connectivity status reflects Internet connectivity only and may not indicate the quality or speed of the connection, which could affect API performance.\n' +
+        "- The API monitors general Internet connectivity but doesn't provide specific information about Shopify service availability or API endpoint availability.",
+    },
+  ],
   examples: {
-    description: 'Examples of using the Connectivity API',
+    description:
+      'Learn how to monitor Internet connectivity status and respond to network changes.',
     examples: [
       {
         codeblock: generateJsxCodeBlockForConnectivityApi(
-          'Subscribe to connectivity changes.',
+          'Monitor Internet connectivity status',
           'subscribe',
         ),
+        description:
+          'Subscribe to connectivity state changes to build network-aware extensions that respond to connectivity changes. This example shows how to use `shopify.connectivity.subscribe()` to receive real-time notifications when the device goes online or offline, allowing you to adapt your UI or disable features when Internet access is unavailable.',
       },
     ],
   },

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

@@ -7,43 +7,52 @@ 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',
     },
   ],
   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 action context. This example shows how to use `shopify.customer.id` to retrieve the customer ID, which can be used for personalization, fetching additional customer data, or building customer-specific features.',
       },
     ],
   },
-  category: 'APIs',
-  related: [
+  category: 'Target APIs',
+  subCategory: 'Contextual APIs',
+  related: [],
+  subSections: [
     {
-      name: ExtensionTargetType.PosCustomerDetailsActionMenuItemRender,
-      url: '/docs/api/pos-ui-extensions/targets/pos-customer-details-action-menu-item-render',
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent:
+        '- **Use customer ID for data lookups:** Use the customer ID to fetch additional customer information from external systems, CRM platforms, or Shopify APIs when building comprehensive customer experiences.\n' +
+        '- **Implement customer-specific features:** Use the customer context to enable personalized functionality like customer-specific pricing, loyalty program integration, or customized product recommendations.\n' +
+        '- **Validate customer access:** Verify that the customer ID is valid before performing customer-specific operations or external API calls.',
     },
     {
-      name: ExtensionTargetType.PosCustomerDetailsActionRender,
-      url: '/docs/api/pos-ui-extensions/targets/pos-customer-details-action-render',
+      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.\n' +
+        '- Customer data reflects the current POS session and may not include real-time updates from other channels until the session is refreshed.',
     },
   ],
 };

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

@@ -7,38 +7,68 @@ const generateJsxCodeBlockForDeviceApi = (title: string, fileName: string) =>
 const data: ReferenceEntityTemplateSchema = {
   name: 'Device API',
   description:
-    'The Device API allows the UI Extension to retrieve device information including the device name and ID.',
+    'The Device API provides access to device information and capabilities, allowing you to retrieve device details, check device types, and adapt your extension behavior based on the POS hardware characteristics. The API enables device-aware functionality and responsive design based on device form factors.',
   isVisualComponent: false,
   type: 'APIs',
   definitions: [
     {
       title: 'DeviceApi',
-      description: '',
+      description:
+        '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.',
       type: 'DeviceApiContent',
     },
   ],
-  category: 'APIs',
+  category: 'Target APIs',
+  subCategory: 'Platform APIs',
   related: [],
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent:
+        '- **Implement responsive design:** Use device type information to adapt your interface layouts, component sizes, and interaction patterns based on the device form factor and capabilities.\n' +
+        '- **Handle async device queries:** Handle the Promise-based device methods with async/await or `.then()` patterns, and implement appropriate error handling for device query failures.\n' +
+        '- **Cache device information appropriately:** Consider caching device information after the initial query to avoid repeated async calls, but ensure you handle cases where device characteristics might change during the session.\n' +
+        '- **Provide device-appropriate experiences:** Design different user experiences for tablets versus other devices, taking advantage of larger screens while ensuring functionality works across all supported device types.',
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent:
+        '- Device information queries are asynchronous and may take time to resolve, so always handle the Promise-based responses appropriately in your extension logic.\n' +
+        "- The Device API provides read-only access to device information and can't be used to modify device settings or capabilities.\n" +
+        "- Device type detection is limited to basic form factor identification (tablet vs. non-tablet) and doesn't provide detailed hardware specifications or capabilities.",
+    },
+  ],
   examples: {
-    description: 'Examples of using the Device API.',
+    description:
+      'Learn how to access device information and adapt your extension based on device characteristics.',
     examples: [
       {
         codeblock: generateJsxCodeBlockForDeviceApi(
-          'Retrieve name of the device.',
-          'name',
+          'Check if the device is a tablet',
+          'tablet',
         ),
+        description:
+          'Determine whether the extension is running on a tablet form factor. This example shows how to use `shopify.device.isTablet()` to check the device type, allowing you to adapt your UI layout, component sizes, or features based on whether the device is a tablet or other form factor.',
       },
       {
         codeblock: generateJsxCodeBlockForDeviceApi(
-          'Retrieve the ID of the device.',
+          'Display the device ID',
           'device-id',
         ),
+        description:
+          'Access the unique identifier of the POS device. This example demonstrates using `shopify.device.id` to retrieve the device ID, which can be used for device-specific configurations, tracking, or associating data with particular devices.',
       },
       {
         codeblock: generateJsxCodeBlockForDeviceApi(
-          'Check if device is a tablet.',
-          'tablet',
+          'Display the device name',
+          'name',
         ),
+        description:
+          'Access the name of the POS device running your extension. This example shows how to use `shopify.device.name` to retrieve the device name, which can be useful for debugging, analytics, or displaying device-specific information to users.',
       },
     ],
   },