--- title: Product Search API description: >- The Product Search API provides access to POS native product search functionality, allowing you to search for products, fetch product details, and retrieve product variants with pagination support and flexible sorting options. The API enables both text-based search and direct product lookups by ID. api_version: 2024-10 api_name: pos-ui-extensions source_url: html: >- https://shopify.dev/docs/api/pos-ui-extensions/2024-10/target-apis/standard-apis/product-search-api md: >- https://shopify.dev/docs/api/pos-ui-extensions/2024-10/target-apis/standard-apis/product-search-api.md --- # Product Search API The Product Search API provides access to POS native product search functionality, allowing you to search for products, fetch product details, and retrieve product variants with pagination support and flexible sorting options. The API enables both text-based search and direct product lookups by ID. #### Use cases * **Custom search:** Implement custom product search interfaces with advanced filtering. * **Recommendations:** Build product recommendation systems based on search results. * **Inventory tools:** Create inventory management tools that lookup product details. * **Pagination:** Build custom product catalogs with pagination for large inventories. ### Support Targets (17) ### Supported targets * [pos.​customer-details.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/customer-details#customer-details-action-menu-item-) * [pos.​customer-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/customer-details#customer-details-action-modal-) * [pos.​customer-details.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/customer-details#customer-details-targets) * [pos.​draft-order-details.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/draft-order-details#draft-order-details-action-menu-item-) * [pos.​draft-order-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/draft-order-details#draft-order-details-action-modal-) * [pos.​draft-order-details.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/draft-order-details#draft-order-details-targets) * [pos.​home.​modal.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/home-screen#home-screen-action-modal-) * [pos.​home.​tile.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/home-screen#home-screen-targets) * [pos.​order-details.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/order-details#order-details-action-menu-item-) * [pos.​order-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/order-details#order-details-action-modal-) * [pos.​order-details.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/order-details#order-details-targets) * [pos.​product-details.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/product-details#product-details-action-menu-item-) * [pos.​product-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/product-details#product-details-action-modal-) * [pos.​product-details.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/product-details#product-details-targets) * [pos.​purchase.​post.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/post-purchase#post-purchase-action-menu-item-) * [pos.​purchase.​post.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/post-purchase#post-purchase-action-modal-) * [pos.​purchase.​post.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/post-purchase#post-purchase-targets) ## Properties The `ProductSearchApi` object provides properties for searching and fetching product data. Access these properties through `api.productSearch` to perform product searches and lookups. * **fetchPaginatedProductVariantsWithProductId** **(productId: number, paginationParams: PaginationParams) => Promise\>** **required** Retrieves product variants for a specific product with pagination support. Use when a product has many variants and you need to load them incrementally for better performance. Ideal for products with extensive variant collections that would be too large to load at once. * **fetchProductsWithIds** **(productIds: number\[]) => Promise\>** **required** Retrieves detailed information for multiple products by their IDs. Limited to 50 products maximum—additional IDs are automatically removed. Returns results with both found and not found products clearly identified. Use for bulk product lookups, building product collections, or validating product lists. * **fetchProductVariantsWithIds** **(productVariantIds: number\[]) => Promise\>** **required** Retrieves detailed information for multiple product variants by their IDs. Limited to 50 variants maximum—additional IDs are automatically removed. Returns results with both found and not found variants clearly identified. Use for bulk variant lookups or building variant-specific collections. * **fetchProductVariantsWithProductId** **(productId: number) => Promise\** **required** Retrieves all product variants associated with a specific product ID. Returns all variants at once without pagination. Use for displaying complete variant options, building variant selectors, or analyzing all available configurations for a product. * **fetchProductVariantWithId** **(productVariantId: number) => Promise\** **required** Retrieves detailed information for a single product variant by its ID. Returns `undefined` if the variant doesn't exist or isn't available. Use for displaying variant-specific details like pricing, inventory, or options when working with specific product configurations. * **fetchProductWithId** **(productId: number) => Promise\** **required** Retrieves detailed information for a single product by its ID. Returns `undefined` if the product doesn't exist or isn't available on the POS device. Use for displaying product details, validating product availability, or building product-specific workflows. * **searchProducts** **(searchParams: ProductSearchParams) => Promise\>** **required** Searches for products on the POS device using text queries and sorting options. Returns paginated results with up to 50 products per page. When a query string is provided, results are sorted by relevance. Use for implementing custom search interfaces, product discovery features, or filtered product listings. ### PaginationParams Specifies parameters for cursor-based pagination. Includes the cursor position and the number of results to retrieve per page. * afterCursor Specifies the page cursor. Items after this cursor will be returned in the next page. Use the cursor from previous search results to implement pagination and load additional products as users navigate through search results. ```ts string ``` * first Specifies the number of results to be returned in this page. The maximum number of items that will be returned is 50. Use to control page size based on your UI requirements and performance considerations. ```ts number ``` ### PaginatedResult Represents the result of a paginated query. Contains the data items, pagination cursors for navigating pages, and information about whether more results exist. * hasNextPage Whether there is another page of results that can be fetched. Use to determine whether to show "Load More" buttons, pagination controls, or implement infinite scrolling functionality. ```ts boolean ``` * items The items returned from the fetch operation. Contains the actual search results or fetched resources. Use to access the product or variant data returned from search and fetch operations. ```ts T[] ``` * lastCursor The cursor of the last item. This can be used to fetch more results. The format of this cursor may look different depending on if POS is fetching results from the remote API, or its local database. However, that should not affect its usage with the search functions. ```ts string ``` ### ProductVariant Represents a specific variant of a product with its own SKU, price, and inventory. Contains variant-specific attributes including options, availability, and identification data. * barcode The variant's barcode identifier, if configured. Returns \`undefined\` when no barcode is set. Use for barcode scanning functionality, inventory tracking, or integration with barcode-based systems. ```ts string ``` * compareAtPrice The variant's compare-at price (original or MSRP price) formatted as a string, if set. Returns \`undefined\` when no compare-at price is configured. Use for displaying discounts, sale pricing, or savings calculations. ```ts string ``` * createdAt The \[ISO 8601]\(https://en.wikipedia.org/wiki/ISO\_8601) timestamp when the product variant was created. Use for sorting variants by creation date, implementing "new product" features, or tracking product catalog changes over time. ```ts string ``` * displayName The variant's formatted display name for user interfaces. This may differ from the title and is optimized for display purposes. Use for customer-facing variant names in product listings, cart items, or receipt displays. ```ts string ``` * hasInStockVariants Whether this variant currently has inventory in stock. Returns \`undefined\` when inventory information is not available. Use for stock status displays, availability checks, or filtering in-stock variants. ```ts boolean ``` * id The unique identifier for the product variant. Use this ID for variant-specific operations, cart additions, or inventory lookups. This ID is consistent across all Shopify systems. ```ts number ``` * image The URL of the variant-specific image, if one is configured. Returns \`undefined\` when no variant image is set. Use for displaying variant-specific images in selection interfaces or product galleries. ```ts string ``` * inventoryAtAllLocations The total inventory quantity across all locations for this variant, if available. Returns \`undefined\` when this information is not available. Use for comprehensive inventory views, transfer planning, or multi-location inventory management. ```ts number ``` * inventoryAtLocation The inventory quantity available at the current POS location, if inventory tracking is enabled. Returns \`undefined\` when inventory tracking is disabled. Use for location-specific inventory displays, stock availability checks, or local inventory management. ```ts number ``` * inventoryIsTracked Whether inventory tracking is enabled for this specific variant. When \`false\`, inventory quantities may not be accurate. Use to determine whether to display inventory information or implement inventory-based business logic for this variant. ```ts boolean ``` * inventoryPolicy The inventory policy for this variant, either "DENY" (prevent sales when out of stock) or "CONTINUE" (allow sales when out of stock). Use to implement inventory validation logic and determine whether to allow purchases of out-of-stock items. ```ts ProductVariantInventoryPolicy ``` * options An array of option name-value pairs that define this variant's configuration. For example, \`\[{name: "Size," value: "Large"}, {name: "Color," value: "Blue"}]\`. Returns \`undefined\` for products with only default variants. Use for displaying variant options, building variant selectors, or implementing variant-based logic. ```ts ProductVariantOption[] ``` * position The variant's position order within the product's variant list. Use for maintaining consistent variant ordering in selection interfaces or implementing custom variant sorting logic. ```ts number ``` * price The variant's selling price formatted as a string. Use for price displays, cart calculations, or implementing pricing logic. This represents the current selling price for the variant. ```ts string ``` * product Reference to the parent Product object that this variant belongs to. Returns \`undefined\` in some contexts to avoid circular references. Use when you need access to product-level information from a variant context. ```ts Product ``` * productId The ID of the parent product that this variant belongs to. Use for linking variants back to their parent product, implementing product-level operations, or organizing variants by product. ```ts number ``` * sku The variant's Stock Keeping Unit (SKU) identifier, if configured. Returns \`undefined\` when no SKU is set. Use for inventory management, product identification, or integration with external systems that use SKU-based tracking. ```ts string ``` * taxable Whether this variant is subject to tax calculations. Use for tax computation logic, pricing displays, or implementing tax-exempt product handling. ```ts boolean ``` * title The variant's display title, typically showing the option combinations. For example, \`"Large / Blue"\`. Use for variant selection interfaces, cart displays, or anywhere users need to distinguish between variants. ```ts string ``` * updatedAt The \[ISO 8601]\(https://en.wikipedia.org/wiki/ISO\_8601) timestamp when the product variant was last updated. Use for cache invalidation, tracking recent changes, or implementing "recently updated" product features. ```ts string ``` ### ProductVariantInventoryPolicy The inventory policy determining whether sales can continue when a variant has no inventory available: - \`'DENY'\`: Sales are prevented when inventory reaches zero. Customers can't purchase out-of-stock variants. The "Add to cart" action is disabled or shows "Out of stock". This is the default and recommended policy for most physical products to prevent overselling. - \`'CONTINUE'\`: Sales are allowed even when inventory is zero or negative. Customers can purchase out-of-stock variants, creating backorders. This enables pre-orders, made-to-order products, or drop-shipped items where inventory tracking is less critical. ```ts 'DENY' | 'CONTINUE' ``` ### ProductVariantOption Represents a single option selection for a product variant, showing one chosen value from a product's configuration options. For example, if a product has Size and Color options, a variant might have one option for Size=Large and another for Color=Blue. * name The option category name (for example, \`"Size"\`, \`"Color"\`, \`"Material"\`, \`"Style"\`, \`"Flavor"\`). This is the attribute or dimension along which the product varies. Each product can have up to 3 option names, and each option name can have multiple values. The name is visible to customers in variant selection interfaces. Commonly used for displaying option labels in variant selectors ("Select Size:", "Choose Color:"), building dynamic product configuration UI, or organizing product variations by attribute type. ```ts string ``` * value The selected value for this option that defines this specific variant (for example, \`"Large"\`, \`"Blue"\`, \`"Cotton"\`, \`"V-Neck"\`). This is the specific choice from the available option values that characterizes this variant. For example, if \`name\` is "Size", the \`value\` might be "Large" or "Small". Values are set at the variant level—each variant has a unique combination of option values. Commonly used for displaying the variant's configuration ("Size: Large, Color: Blue"), building variant selection dropdowns, or matching user selections to variants. ```ts string ``` ### Product Represents comprehensive product information including metadata, pricing, variants, and availability. Contains all data needed to display and work with products in the POS interface. * createdAt The \[ISO 8601]\(https://en.wikipedia.org/wiki/ISO\_8601) timestamp when the product was created. Use for sorting products by creation date, implementing "new product" features, or tracking product catalog growth over time. ```ts string ``` * description The product's plain text description without HTML formatting. Use for displaying product information in contexts where HTML is not supported or when you need clean text content for processing. ```ts string ``` * descriptionHtml The product's description with HTML formatting preserved. Use when you need to display rich text content with formatting, links, or other HTML elements in your extension interface. ```ts string ``` * featuredImage The URL of the product's featured image, if one is set. Returns \`undefined\` if no featured image is configured. Use for displaying product images in search results, product listings, or detailed product views. ```ts string ``` * hasInStockVariants Whether the product has any variants currently in stock. Returns \`undefined\` when inventory information is not available. Use for stock status displays, availability filtering, or implementing out-of-stock product handling. ```ts boolean ``` * hasOnlyDefaultVariant Whether the product has only a default variant (no custom options). When \`true\`, the product doesn't require variant selection. Use to simplify product interfaces and skip variant selection steps for single-variant products. ```ts boolean ``` * id The unique identifier for the product. Use this ID for product-specific operations, API calls, or linking to product details. This ID is consistent across all Shopify systems and can be used for external integrations. ```ts number ``` * isGiftCard Whether this product is a gift card. Gift cards have special handling requirements and different business logic. Use to implement gift card-specific workflows, validation, or display special gift card interfaces. ```ts boolean ``` * maxVariantPrice The highest price among all product variants, formatted as a string. Use for displaying price ranges, implementing price-based filtering, or showing complete pricing information for products with multiple variants. ```ts string ``` * minVariantPrice The lowest price among all product variants, formatted as a string. Use for displaying price ranges, implementing price-based filtering, or showing starting prices in product listings. ```ts string ``` * numVariants The total number of variants available for this product. Use to determine whether to show variant selection interfaces, implement variant-specific logic, or optimize variant loading strategies. ```ts number ``` * onlineStoreUrl The URL of the product on the online store, if available. Returns \`undefined\` when the product is not published online or the store doesn't have an online presence. Use for linking to online product pages or sharing product information. ```ts string ``` * options An array of product options that define available variant configurations. For example, size and color. Each option includes available values. Use for building variant selection interfaces or understanding product configuration possibilities. ```ts ProductOption[] ``` * productCategory The standardized product category classification. Use for product categorization, implementing category-specific business logic, or organizing products by standardized categories. ```ts string ``` * productType The product type category as defined by the merchant (For example, "T-Shirt," "Electronics," "Books"). Use for product categorization, filtering, or implementing category-specific business logic. ```ts string ``` * tags An array of tags associated with the product for categorization and organization. Use for product filtering, search enhancement, or implementing tag-based business logic and promotions. ```ts string[] ``` * title The product's display name as configured by the merchant. Use for product listings, search results, and customer-facing displays. This is the primary product identifier that customers will recognize. ```ts string ``` * totalAvailableInventory The total available inventory across all variants and locations, if tracking is enabled. Returns \`undefined\` when inventory tracking is disabled. Use for availability checks, stock level displays, or implementing low-stock alerts. ```ts number ``` * totalInventory The total inventory count across all variants and locations for this product. Use for inventory management, stock level displays, or implementing low-stock warnings and alerts. ```ts number ``` * tracksInventory Whether inventory tracking is enabled for this product. When \`false\`, inventory quantities may not be accurate or meaningful. Use to determine whether to display inventory information or implement inventory-based business logic. ```ts boolean ``` * updatedAt The \[ISO 8601]\(https://en.wikipedia.org/wiki/ISO\_8601) timestamp when the product was last updated. Use for cache invalidation, tracking recent changes, or implementing "recently updated" product features. ```ts string ``` * variants An array of all product variants associated with this product. Each variant contains detailed information including pricing, inventory, and options. Use for building variant selectors, displaying inventory information, or implementing variant-specific functionality. ```ts ProductVariant[] ``` * vendor The product's vendor or brand name as configured by the merchant. Use for filtering products by brand, displaying vendor information, or organizing products by supplier. ```ts string ``` ### ProductOption Represents a product option definition showing one of the configurable attributes for a product (like Size, Color, Material) along with all the possible values customers can choose from. Products can have up to 3 options. * id The unique numeric identifier for this product option configuration. This ID identifies the option definition itself (not a specific option value or variant). Commonly used for option-specific operations, tracking option configurations, or linking options in external systems. ```ts number ``` * name The option category name (for example, \`"Size"\`, \`"Color"\`, \`"Material"\`, \`"Style"\`, \`"Flavor"\`). This is the attribute or dimension along which the product varies. Each product can have up to 3 option names, and each option name can have multiple values. The name is visible to customers in variant selection interfaces. Commonly used for displaying option labels in variant selectors ("Select Size:", "Choose Color:"), building dynamic product configuration UI, or organizing product variations by attribute type. ```ts string ``` * optionValues An array of all available values for this option that customers can choose from (for example, \`\["Small", "Medium", "Large", "X-Large"]\` for a Size option, or \`\["Red", "Blue", "Green", "Black"]\` for a Color option). The order of values in this array typically represents the display order in variant selectors. Each combination of option values across all options creates a unique variant. For example, a product with Size: \[Small, Large] and Color: \[Red, Blue] would have 4 variants (Small/Red, Small/Blue, Large/Red, Large/Blue). Commonly used for building variant selection dropdowns, radio buttons, or swatches, validating user selections, or displaying all available choices for an attribute. ```ts string[] ``` * productId The unique numeric identifier of the parent product to which this option belongs. This links the option definition back to the product it configures. Commonly used for linking options to their parent product, organizing options by product, or implementing product-level option management. ```ts number ``` ### MultipleResourceResult Represents the result of a bulk resource lookup operation. Contains successfully found resources and identifiers for resources that were not found. * fetchedResources The resources that were fetched using the IDs provided. Contains the successfully found products or variants. Use to access the actual data that was retrieved from the bulk fetch operation. ```ts T[] ``` * idsForResourcesNotFound The IDs for which a resource was not found. Use to handle missing products or variants gracefully, provide user feedback about unavailable items, or implement fallback logic for missing resources. ```ts number[] ``` ### ProductSearchParams Specifies the parameters for searching products. Includes query text, pagination options, and sorting preferences for product search operations. * afterCursor Specifies the page cursor. Items after this cursor will be returned in the next page. Use the cursor from previous search results to implement pagination and load additional products as users navigate through search results. ```ts string ``` * first Specifies the number of results to be returned in this page. The maximum number of items that will be returned is 50. Use to control page size based on your UI requirements and performance considerations. ```ts number ``` * queryString The search term used to find products by name, description, or other searchable fields. When provided, results are automatically sorted by relevance to the query, overriding any \`sortType\` setting. Use for implementing text-based product search functionality. ```ts string ``` * sortType Specifies the order in which products should be sorted. When a \`queryString\` is provided, sortType will not have any effect, as the results will be returned in order by relevance to the \`queryString\`. Available options: - \*\*\`RECENTLY\_ADDED\`\*\* - Sorts products by creation date in descending order, displaying the most recently added products first. Use to highlight new inventory additions or showcase latest product arrivals. - \*\*\`RECENTLY\_ADDED\_ASCENDING\`\*\* - Sorts products by creation date in ascending order, displaying the oldest products first. Use when prioritizing established products or implementing chronological browsing from earliest to newest. - \*\*\`ALPHABETICAL\_A\_TO\_Z\`\*\* - Sorts products alphabetically by title from A to Z. Use for product catalogs where alphabetical organization improves browsing efficiency and helps users locate products by name quickly. - \*\*\`ALPHABETICAL\_Z\_TO\_A\`\*\* - Sorts products alphabetically by title from Z to A in reverse order. Use when reverse alphabetical sorting is needed for specialized browsing patterns or user preferences. ```ts ProductSortType ``` ### ProductSortType ```ts 'RECENTLY_ADDED' | 'RECENTLY_ADDED_ASCENDING' | 'ALPHABETICAL_A_TO_Z' | 'ALPHABETICAL_Z_TO_A' ``` Examples ### Examples * #### Fetch a single product by ID ##### Description Retrieve complete product information using a known product ID. This example uses \`fetchProductWithId()\` to get detailed product data including title, variants, and pricing, useful when you need to display or validate specific product information. ##### React ```tsx import React, { useEffect, useState } from 'react' import { Screen, List, Navigator, reactExtension, SearchBar, useApi, ListRow } from '@shopify/ui-extensions-react/point-of-sale'; const Modal = () => { const api = useApi<'pos.home.modal.render'>(); const [data, setData] = useState([]); useEffect(() => { const fetchProduct = async () => { const resultProduct = await api.productSearch.fetchProductWithId(1) if (resultProduct) { const listItem = { id: String(resultProduct.id), leftSide: { label: resultProduct.title, image: { source: resultProduct.featuredImage } } } setData([listItem]) } } fetchProduct(); }, []); return ( ) } export default reactExtension('pos.home.modal.render', () => ); ``` ##### TS ```ts import { SearchBar, Screen, Navigator, extension, ListRow, List, } from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.modal.render', (root, api) => { const list = root.createComponent(List, { imageDisplayStrategy: 'always', data: [], }); const fetchProduct = async () => { const resultProduct = await api.productSearch.fetchProductWithId(1); if (resultProduct) { const listItem = { id: String(resultProduct.id), leftSide: { label: resultProduct.title, image: { source: resultProduct.featuredImage, }, }, }; list.updateProps({data: [listItem]}); } }; const screen = root.createComponent(Screen, { title: 'Home', name: 'Home', }); screen.append(list); const navigator = root.createComponent(Navigator); navigator.append(screen); root.append(navigator); fetchProduct(); }); ``` * #### Fetch a single product variant by ID ##### Description Get detailed information about a specific product variant using its variant ID. This example uses \`fetchProductVariantWithId()\` to retrieve variant-specific data like price, SKU, and inventory, useful for variant-level operations or displaying detailed variant information. ##### React ```tsx import React, { useEffect, useState } from 'react' import { Screen, List, Navigator, reactExtension, SearchBar, useApi, ListRow } from '@shopify/ui-extensions-react/point-of-sale'; const Modal = () => { const api = useApi<'pos.home.modal.render'>(); const [data, setData] = useState([]); useEffect(() => { const fetchProductVariant = async () => { const resultProductVariant = await api.productSearch.fetchProductVariantWithId(1); if (resultProductVariant) { const listItem = { id: String(resultProductVariant.id), leftSide: { label: resultProductVariant.title, image: { source: resultProductVariant.image } } } setData([listItem]) } } fetchProductVariant(); }, []); return ( ) } export default reactExtension('pos.home.modal.render', () => ); ``` ##### TS ```ts import { SearchBar, Screen, Navigator, extension, ListRow, List, } from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.modal.render', (root, api) => { const list = root.createComponent(List, { imageDisplayStrategy: 'always', data: [], }); const fetchProductVariant = async () => { const resultProductVariant = await api.productSearch.fetchProductVariantWithId(1); if (resultProductVariant) { const listItem = { id: String(resultProductVariant.id), leftSide: { label: resultProductVariant.title, image: { source: resultProductVariant.image, }, }, }; list.updateProps({data: [listItem]}); } }; const screen = root.createComponent(Screen, { title: 'Home', name: 'Home', }); screen.append(list); const navigator = root.createComponent(Navigator); navigator.append(screen); root.append(navigator); fetchProductVariant(); }); ``` * #### Fetch multiple product variants by IDs ##### Description Retrieve multiple product variants at once by providing variant IDs. This example demonstrates using \`fetchProductVariantsWithIds()\` to efficiently fetch variant details for multiple items, ideal for bulk operations or displaying collections of variants. ##### React ```tsx import React, { useEffect, useState } from 'react' import { Screen, List, Navigator, reactExtension, SearchBar, useApi, ListRow } from '@shopify/ui-extensions-react/point-of-sale'; const Modal = () => { const api = useApi<'pos.home.modal.render'>(); const [data, setData] = useState([]); useEffect(() => { const fetchProductVariants = async () => { const results = await api.productSearch.fetchProductVariantsWithIds([1, 2, 3]); const data = results.fetchedResources.map((variant): ListRow => { return { id: String(variant.id), leftSide: { label: variant.title, image: { source: variant.image } } } }) console.log('IDs not found: ', results.idsForResourcesNotFound); setData(data) } fetchProductVariants(); }, []); return ( ) } export default reactExtension('pos.home.modal.render', () => ); ``` ##### TS ```ts import { SearchBar, Screen, Navigator, extension, ListRow, List, } from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.modal.render', (root, api) => { const list = root.createComponent(List, { imageDisplayStrategy: 'always', data: [], }); const fetchProductVariants = async () => { const results = await api.productSearch.fetchProductVariantsWithIds([ 1, 2, 3, 4, ]); const data = results.fetchedResources.map((variant): ListRow => { return { id: String(variant.id), leftSide: { label: variant.title, image: { source: variant.image, }, }, }; }); console.log('IDs not found: ', results.idsForResourcesNotFound); list.updateProps({data}); }; const screen = root.createComponent(Screen, { title: 'Home', name: 'Home', }); screen.append(list); const navigator = root.createComponent(Navigator); navigator.append(screen); root.append(navigator); fetchProductVariants(); }); ``` * #### Fetch multiple products by IDs ##### Description Retrieve multiple products simultaneously by providing an array of product IDs. This example shows how to use \`fetchProductsWithIds()\` to efficiently fetch several products in a single operation, reducing API calls and improving performance when working with product collections. ##### React ```tsx import React, { useEffect, useState } from 'react' import { Screen, List, Navigator, reactExtension, SearchBar, useApi, ListRow } from '@shopify/ui-extensions-react/point-of-sale'; const Modal = () => { const api = useApi<'pos.home.modal.render'>(); const [data, setData] = useState([]); useEffect(() => { const fetchProducts = async () => { const results = await api.productSearch.fetchProductsWithIds([1, 2, 3]); const data = results.fetchedResources.map((product): ListRow => { return { id: String(product.id), leftSide: { label: product.title, image: { source: product.featuredImage } } } }) console.log('IDs not found: ', results.idsForResourcesNotFound); setData(data) } fetchProducts(); }, []); return ( ) } export default reactExtension('pos.home.modal.render', () => ); ``` ##### TS ```ts import { SearchBar, Screen, Navigator, extension, ListRow, List, } from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.modal.render', (root, api) => { const list = root.createComponent(List, { imageDisplayStrategy: 'always', data: [], }); const fetchProducts = async () => { const results = await api.productSearch.fetchProductsWithIds([1, 2, 3, 4]); const data = results.fetchedResources.map((product): ListRow => { return { id: String(product.id), leftSide: { label: product.title, image: { source: product.featuredImage, }, }, }; }); console.log('IDs not found: ', results.idsForResourcesNotFound); list.updateProps({data}); }; const screen = root.createComponent(Screen, { title: 'Home', name: 'Home', }); screen.append(list); const navigator = root.createComponent(Navigator); navigator.append(screen); root.append(navigator); fetchProducts(); }); ``` * #### Fetch paginated variants for a product ##### Description Retrieve variants for a product with pagination support to handle products with many variants efficiently. This example shows how to use \`fetchPaginatedProductVariantsWithProductId()\` with pagination options, allowing you to load variants in manageable chunks and implement infinite scroll or load more functionality. ##### React ```tsx import React, { useEffect, useState } from 'react' import { Screen, List, Navigator, reactExtension, SearchBar, useApi, ListRow } from '@shopify/ui-extensions-react/point-of-sale'; const Modal = () => { const api = useApi<'pos.home.modal.render'>(); const [data, setData] = useState([]); useEffect(() => { const fetchProductVariants = async () => { const results = await api.productSearch.fetchPaginatedProductVariantsWithProductId(1, {first: 10}); const data = results.items.map((variant): ListRow => { return { id: String(variant.id), leftSide: { label: variant.title, image: { source: variant.image } } } }) console.log('Cursor for next page: ', results.lastCursor); setData(data) } fetchProductVariants(); }, []); return ( ) } export default reactExtension('pos.home.modal.render', () => ); ``` ##### TS ```ts import { SearchBar, Screen, Navigator, extension, ListRow, List, } from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.modal.render', (root, api) => { const list = root.createComponent(List, { imageDisplayStrategy: 'always', data: [], }); const fetchProductVariants = async () => { const results = await api.productSearch.fetchPaginatedProductVariantsWithProductId(1, { first: 10, }); const data = results.items.map((variant): ListRow => { return { id: String(variant.id), leftSide: { label: variant.title, image: { source: variant.image, }, }, }; }); console.log('Cursor for next page: ', results.lastCursor); list.updateProps({data}); }; const screen = root.createComponent(Screen, { title: 'Home', name: 'Home', }); screen.append(list); const navigator = root.createComponent(Navigator); navigator.append(screen); root.append(navigator); fetchProductVariants(); }); ``` * #### Search for products with a search bar ##### Description Implement product search with a SearchBar component to find products by text query. This example demonstrates using \`search()\` to perform real-time product searches, displaying results in a list as merchants type, enabling quick product discovery and selection. ##### React ```tsx import React, { useState } from 'react' import { Screen, List, Navigator, reactExtension, SearchBar, useApi, ListRow } from '@shopify/ui-extensions-react/point-of-sale'; const Modal = () => { const api = useApi<'pos.home.modal.render'>(); const [data, setData] = useState([]); const search = async (queryString?: string) => { const results = await api.productSearch.searchProducts({queryString}) const data = results.items.map((product): ListRow => { return { id: String(product.id), leftSide: { label: product.title, image: { source: product.featuredImage } } } }) setData(data) } return ( } imageDisplayStrategy='always' data={data} /> ) } export default reactExtension('pos.home.modal.render', () => ); ``` ##### TS ```ts import { SearchBar, Screen, Navigator, extension, ListRow, List, } from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.modal.render', (root, api) => { const list = root.createComponent(List, { imageDisplayStrategy: 'always', data: [], }); const search = async (queryString?: string) => { const results = await api.productSearch.searchProducts({queryString}); const data = results.items.map((product): ListRow => { return { id: String(product.id), leftSide: { label: product.title, image: { source: product.featuredImage, }, }, }; }); list.updateProps({data}); }; const searchBar = root.createFragment(); searchBar.append( root.createComponent(SearchBar, { placeholder: 'Search products', onTextChange: search, onSearch: search, }), ); list.updateProps({listHeaderComponent: searchBar}); const screen = root.createComponent(Screen, { title: 'Home', name: 'Home', }); screen.append(list); const navigator = root.createComponent(Navigator); navigator.append(screen); root.append(navigator); }); ``` ## Best practices * **Handle search results gracefully:** Check for undefined results and empty result sets. * **Optimize search performance:** Consider caching frequently accessed product data and implementing debounced search to reduce API calls while users are typing search queries. * **Provide relevant search options:** Use appropriate sorting options based on your use case—relevance for user searches, alphabetical for browsing, or recently added for highlighting new products. ## Limitations * Product search results are limited to products available on the current POS device and may not include the complete shop catalog if products aren't synced locally. * Bulk operations (`fetchProductsWithIds` and `fetchProductVariantsWithIds`) are limited to 50 items maximum, with additional IDs automatically removed from requests. * Search functionality depends on local product data synchronization and may not reflect real-time inventory or pricing changes until the next sync.