[POS UI extensions version 2025-10]: Refine example descriptions, limitations, and links (#3605)

* Refine example descriptions

* Refine limitations

* Add cross-reference to other component docs

Fix version

Fix type error

Move subSection to original position

* Add missing example descriptions

Fixes

* Further refinements

Wording

* Integrate feedback from Tim

* POS UI extensions components reference docs updates (#3607)

* Update Components section to remove inappropriate content from limitations sections and add to description

* Linting

* Formatting, typos, and other minor revisions

---------

Co-authored-by: Michelle Vinci <[email protected]>

* POS UI extensions components reference docs updates (#3607)

* Update Components section to remove inappropriate content from limitations sections and add to description

* Linting

* Formatting, typos, and other minor revisions

---------

Co-authored-by: Michelle Vinci <[email protected]>

* code styling

---------

Co-authored-by: Tim Trevor <[email protected]>

Author: mcvinci

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

@@ -36,8 +36,9 @@ const data: ReferenceEntityTemplateSchema = {
       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.',
+      sectionContent: `
+The \`presentModal()\` method must be called from a user interaction (such as a button click or tile tap) and can't be invoked programmatically during extension initialization or from background operations.
+`,
     },
   ],
   examples: {
@@ -50,15 +51,15 @@ const data: ReferenceEntityTemplateSchema = {
           '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.",
+          '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. With this pattern, you can implement complex, multi-step operations.',
       },
       {
         codeblock: generateJsxCodeBlockForActionApi(
           '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.",
+          '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. This pattern is well-suited 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

@@ -27,11 +27,11 @@ const data: ReferenceEntityTemplateSchema = {
     examples: [
       {
         codeblock: generateJsxCodeBlockForCartLineItemApi(
-          'Display the line item ID',
+          'Retrieve 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.',
+          '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. This can be used for modifying the item, applying discounts, or implementing item-specific functionality.',
       },
     ],
   },
@@ -43,21 +43,22 @@ const data: ReferenceEntityTemplateSchema = {
       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.',
+      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.\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.",
+      sectionContent: `
+- 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.
+`,
     },
   ],
 };

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

@@ -38,10 +38,9 @@ const data: ReferenceEntityTemplateSchema = {
       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.",
+      sectionContent: `
+Connectivity status reflects Internet connectivity only and may not indicate the quality or speed of the connection, which could affect API performance.
+`,
     },
   ],
   examples: {
@@ -54,7 +53,7 @@ const data: ReferenceEntityTemplateSchema = {
           '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.',
+          '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. This enables adaptive behavior for offline-capable features or network-dependent operations.',
       },
     ],
   },

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

@@ -25,11 +25,11 @@ const data: ReferenceEntityTemplateSchema = {
     examples: [
       {
         codeblock: generateJsxCodeBlockForCustomerApi(
-          'Display the customer ID',
+          'Retrieve 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.',
+          '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. This can be used for fetching additional customer data, implementing loyalty features, or building personalized customer experiences.',
       },
     ],
   },
@@ -41,18 +41,19 @@ const data: ReferenceEntityTemplateSchema = {
       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.',
+      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.\n' +
-        '- Customer data reflects the current POS session and may not include real-time updates from other channels until the session is refreshed.',
+      sectionContent: `
+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/customer-api.doc.ts

@@ -32,15 +32,6 @@ const data: ReferenceEntityTemplateSchema = {
         '- **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:
@@ -52,23 +43,23 @@ const data: ReferenceEntityTemplateSchema = {
           '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.',
+          'Check if the POS device is running on tablet hardware to adapt your UI accordingly. This example shows how to use `shopify.device.isTablet()` to determine the device form factor. This enables responsive layouts and touch-optimized interfaces for tablet devices versus traditional POS terminals.',
       },
       {
         codeblock: generateJsxCodeBlockForDeviceApi(
-          'Display the device ID',
+          'Retrieve 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.',
+          'Access the unique identifier of the current POS device. This example demonstrates using `shopify.device.id` to retrieve the device ID. This enables device-specific configurations, analytics tracking, or multi-device coordination features.',
       },
       {
         codeblock: generateJsxCodeBlockForDeviceApi(
-          'Display the device name',
+          'Retrieve 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.',
+          'Retrieve the name of the current POS device. This example shows how to use `shopify.device.name` to get the device name configured in POS settings. This is useful for device identification, multi-device workflows, or displaying location-specific information.',
       },
     ],
   },

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

@@ -27,17 +27,19 @@ const data: ReferenceEntityTemplateSchema = {
     examples: [
       {
         codeblock: generateJsxCodeBlockForDraftOrderApi(
-          'Display the draft order ID',
+          'Retrieve a draft order ID',
           'id',
         ),
         description:
-          'Access the unique identifier of the current draft order in a draft order detail action context. This example shows how to use `shopify.draftOrder.id` to retrieve the draft order ID, which can be used for tracking, fetching additional order data, or implementing draft order-specific workflows.',
+          'Access the unique identifier of the current draft order in a draft order detail context. This example shows how to use `shopify.draftOrder.id` to retrieve the draft order ID. This can be used for fetching additional order data, implementing custom workflows, or building draft order-specific features.',
       },
       {
         codeblock: generateJsxCodeBlockForDraftOrderApi(
           "Retrieve a draft order's name, ID, and associated customer ID",
           'draft-order-details',
         ),
+        description:
+          'Access multiple properties from the draft order object including name, ID, and customer information. This example demonstrates using `shopify.draftOrder` to retrieve comprehensive draft order details. This enables building contextual interfaces and implementing order-specific workflows.',
       },
     ],
   },
@@ -58,9 +60,9 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'Generic',
       anchorLink: 'limitations',
       title: 'Limitations',
-      sectionContent:
-        '- The API provides only basic draft order information—use Shopify APIs or external systems to fetch additional draft order details like line items, totals, or timestamps.\n' +
-        '- Draft order data reflects the current POS session and may not include real-time updates from other channels until the session is refreshed.',
+      sectionContent: `
+Draft order 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/draft-order-api.doc.ts

@@ -32,15 +32,6 @@ const data: ReferenceEntityTemplateSchema = {
         '- **Cache localized content:** Consider caching translated content and locale-specific formatting to improve performance, but ensure you invalidate caches when locale changes occur through subscription updates.\n' +
         '- **Provide fallback locale handling:** Implement fallback behavior for unsupported locales or when localization resources are unavailable, defaulting to a supported language like English.',
     },
-    {
-      type: 'Generic',
-      anchorLink: 'limitations',
-      title: 'Limitations',
-      sectionContent:
-        "- The Locale API provides read-only access to locale information and can't be used to change the merchant's locale settings, which must be configured through POS system settings.\n" +
-        "- Locale changes are detected through the subscription mechanism, but the API doesn't provide historical locale information or change timestamps.\n" +
-        '- The locale format follows IETF standards, but the specific locales available depend on POS system configuration and may vary between different Shopify POS installations.',
-    },
   ],
   examples: {
     description:
@@ -52,7 +43,7 @@ const data: ReferenceEntityTemplateSchema = {
           'subscribe',
         ),
         description:
-          "Subscribe to locale changes to build internationalized extensions that automatically adapt to the merchant's language settings. This example shows how to use `shopify.locale.subscribe()` to receive real-time notifications when the merchant changes their language, allowing you to update your UI text, date formats, and number formats accordingly.",
+          "Subscribe to locale changes to monitor the merchant's language settings in real time. This example shows how to use `shopify.locale.subscribe()` and `shopify.locale.ianaCode` to detect when the merchant changes their language preference. This enables dynamic content localization and internationalized user experiences.",
       },
     ],
   },