Best practices and limitations

Author: mcvinci

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

@@ -43,6 +43,21 @@ const data: ReferenceEntityTemplateSchema = {
       },
     ],
   },
+
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `\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.\n`,
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `\nEach 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.\n`,
+    },
+  ],
 };
 
 export default data;

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

@@ -219,6 +219,21 @@ const data: ReferenceEntityTemplateSchema = {
       },
     ],
   },
+
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `\n- **Validate operations before execution:** Check cart editability and validate input data before performing cart operations to prevent errors and provide appropriate user feedback.\n- **Use bulk operations for efficiency:** When performing multiple related operations, use bulk methods like \`bulkCartUpdate\`, \`bulkSetLineItemDiscounts\`, and \`bulkAddLineItemProperties\` for better performance.\n- **Handle errors gracefully:** Implement proper error handling for all cart operations, as they may fail due to inventory constraints, validation errors, or business rule violations.\n`,
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `\n- \`RemoteSubscribable\` supports only one subscription at a time. Use \`makeStatefulSubscribable\` if you need multiple components to subscribe to cart events simultaneously.\n- Cart operations may fail due to business rules, inventory constraints, or validation errors—always implement appropriate error handling.\n- Some operations require specific preconditions. For example, customer must be present for address operations.\n`,
+    },
+  ],
 };
 
 export default data;

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

@@ -34,14 +34,20 @@ const data: ReferenceEntityTemplateSchema = {
     ],
   },
   category: 'APIs',
-  related: [
+  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: `\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, or displaying vendor-specific information.\n- **Implement item-specific validation:** Use line item properties like \`taxable\` and \`isGiftCard\` to implement appropriate validation and business logic for different item types.\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.\n`,
     },
     {
-      name: ExtensionTargetType.PosCartLineItemDetailsActionRender,
-      url: '/docs/api/pos-ui-extensions/targets/pos-cart-line-item-details-action-render',
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `\n- The API provides read-only access to line item data—use the Cart API for modifying line item properties, discounts, or other attributes.\n- Line item data reflects the current state and may not include real-time inventory or pricing updates until the cart is refreshed.\n`,
     },
   ],
 };

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

@@ -34,6 +34,21 @@ const data: ReferenceEntityTemplateSchema = {
       },
     ],
   },
+
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `\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.\n`,
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `\n- 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- \`RemoteSubscribable\` supports only one subscription at a time. Use \`makeStatefulSubscribable\` if you need multiple components to subscribe to connectivity changes simultaneously.\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.\n`,
+    },
+  ],
 };
 
 export default data;

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

@@ -34,14 +34,20 @@ const data: ReferenceEntityTemplateSchema = {
     ],
   },
   category: 'APIs',
-  related: [
+  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: `\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.\n`,
     },
     {
-      name: ExtensionTargetType.PosCustomerDetailsActionRender,
-      url: '/docs/api/pos-ui-extensions/targets/pos-customer-details-action-render',
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `\n- 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.\n`,
     },
   ],
 };

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

@@ -47,6 +47,21 @@ const data: ReferenceEntityTemplateSchema = {
       },
     ],
   },
+
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `\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.\n`,
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `\n- 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.\n`,
+    },
+  ],
 };
 
 export default data;

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

@@ -33,6 +33,21 @@ const data: ReferenceEntityTemplateSchema = {
   },
   category: 'APIs',
   related: [],
+
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `\n- **Implement draft order-specific features:** Use the draft order context to enable specialized functionality like draft order conversion, customer assignment, or order modification workflows.\n- **Validate draft order access:** Verify that the draft order ID is valid before performing draft order-specific operations or external API calls.\n`,
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `\n- 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.\n`,
+    },
+  ],
 };
 
 export default data;

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

@@ -34,6 +34,21 @@ const data: ReferenceEntityTemplateSchema = {
       },
     ],
   },
+
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `\n- **Implement proper formatting:** Use the IETF locale format to implement proper date formatting, number formatting, currency display, and text direction based on the merchant's language and region preferences.\n- **Provide fallback locale handling:** Implement fallback behavior for unsupported locales or when localization resources are unavailable, defaulting to a supported language like English.\n`,
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `\n- 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- \`RemoteSubscribable\` supports only one subscription at a time. Use \`makeStatefulSubscribable\` if you need multiple components to subscribe to locale changes simultaneously.\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.\n`,
+    },
+  ],
 };
 
 export default data;

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

@@ -43,6 +43,21 @@ const data: ReferenceEntityTemplateSchema = {
       },
     ],
   },
+
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `\n- **Handle navigation parameters effectively:** Use navigation parameters to pass data between screens, maintaining workflow context and user progress across screen transitions.\n- **Implement proper screen management:** Design screens that can be pushed and popped.\n- **Provide clear navigation controls:** Implement clear navigation controls and feedback so users understand their current location in the workflow and how to navigate between screens.\n`,
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `\n- The Navigation API is only available in action (modal) targets and can't be used in action (menu item), block, or tile targets that don't support multi-screen navigation.\n- Screen navigation is based on screen names and the navigation stack, which differs from URL-based navigation patterns found in web applications.\n- Navigation parameters must be serializable and can't contain functions, complex objects, or circular references.\n`,
+    },
+  ],
 };
 
 export default data;

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

@@ -43,6 +43,21 @@ const data: ReferenceEntityTemplateSchema = {
       },
     ],
   },
+
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `\n- **Implement order-specific features:** Use the order context to enable specialized functionality like order fulfillment, customer communication, or order modification workflows.\n- **Validate order access:** Verify that the order ID is valid before performing order-specific operations or external API calls.\n`,
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `\n- The API provides only basic order information—use Shopify APIs or external systems to fetch additional order details like line items, totals, or fulfillment status.\n- Order data reflects the current POS session and may not include real-time updates from other channels until the session is refreshed.\n`,
+    },
+  ],
 };
 
 export default data;