--- title: ProductSearch 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: 2025-04 api_name: pos-ui-extensions source_url: html: >- https://shopify.dev/docs/api/pos-ui-extensions/2025-04/target-apis/standard-apis/productsearch-api md: >- https://shopify.dev/docs/api/pos-ui-extensions/2025-04/target-apis/standard-apis/productsearch-api.md --- # Product​Search APIAPIs 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. ## ProductSearchApi The `ProductSearchApi` object provides methods for searching and fetching product data. Access these methods 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. ```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. ```ts number ``` ```ts export interface PaginationParams { /** * Specifies the number of results to be returned in this page. The maximum number of items that will be returned is 50. */ first?: number; /** * Specifies the page cursor. Items after this cursor will be returned. */ afterCursor?: string; } ``` ### 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 or not there is another page of results that can be fetched. ```ts boolean ``` * items The items returned from the fetch. ```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 ``` ```ts export interface PaginatedResult { /** * The items returned from the fetch. */ items: T[]; /** * 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. */ lastCursor?: string; /** * Whether or not there is another page of results that can be fetched. */ hasNextPage: boolean; } ``` ### 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 ``` ```ts export interface ProductVariant { /** * 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. */ id: number; /** * 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. */ createdAt: string; /** * 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. */ updatedAt: string; /** * 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. */ title: string; /** * 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. */ price: string; /** * 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. */ compareAtPrice?: string; /** * Whether this variant is subject to tax calculations. Use for tax computation logic, pricing displays, or implementing tax-exempt product handling. */ taxable: boolean; /** * 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. */ sku?: string; /** * 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. */ barcode?: string; /** * 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. */ displayName: string; /** * 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. */ image?: string; /** * 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. */ inventoryIsTracked: boolean; /** * 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. */ inventoryAtLocation?: number; /** * 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. */ inventoryAtAllLocations?: number; /** * 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. */ inventoryPolicy: ProductVariantInventoryPolicy; /** * 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. */ hasInStockVariants?: boolean; /** * 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. */ options?: ProductVariantOption[]; /** * 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. */ product?: Product; /** * 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. */ productId: number; /** * 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. */ position: number; } ``` ### 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 ``` ```ts export interface ProductVariantOption { /** * 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. */ name: string; /** * 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. */ value: 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 ``` * hasSellingPlanGroups Indicates whether this product or line item has selling plan groups (subscription options) available. When \`true\`, the product offers subscription or recurring payment options that customers can select. When \`false\`, the product is only available for one-time purchase without subscription options. ```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 ``` * requiresSellingPlan Indicates whether this product or line item requires a selling plan (subscription) to be purchased. When \`true\`, the customer must select a subscription or payment plan before adding to cart. When \`false\`, the item can be purchased as a one-time purchase without a selling plan. ```ts boolean ``` * 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 ``` ```ts export interface Product { /** * 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. */ id: number; /** * 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. */ createdAt: string; /** * 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. */ updatedAt: string; /** * 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. */ title: string; /** * 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. */ description: string; /** * 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. */ descriptionHtml: string; /** * 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. */ featuredImage?: string; /** * 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. */ isGiftCard: boolean; /** * 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. */ tracksInventory: boolean; /** * 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. */ vendor: string; /** * 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. */ minVariantPrice: string; /** * 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. */ maxVariantPrice: string; /** * 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. */ productType: string; /** * The standardized product category classification. Use for product categorization, implementing category-specific business logic, or organizing products by standardized categories. */ productCategory: string; /** * 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. */ tags: string[]; /** * 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. */ numVariants: number; /** * 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. */ totalAvailableInventory?: number; /** * 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. */ totalInventory: number; /** * 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. */ variants: ProductVariant[]; /** * 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. */ options: ProductOption[]; /** * 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. */ hasOnlyDefaultVariant: boolean; /** * 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. */ hasInStockVariants?: boolean; /** * 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. */ onlineStoreUrl?: string; /** * Indicates whether this product or line item requires a selling plan (subscription) to be purchased. When `true`, the customer must select a subscription or payment plan before adding to cart. When `false`, the item can be purchased as a one-time purchase without a selling plan. */ requiresSellingPlan?: boolean; /** * Indicates whether this product or line item has selling plan groups (subscription options) available. When `true`, the product offers subscription or recurring payment options that customers can select. When `false`, the product is only available for one-time purchase without subscription options. */ hasSellingPlanGroups?: boolean; } ``` ### 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 ``` ```ts export interface ProductOption { /** * 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. */ id: number; /** * 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. */ name: string; /** * 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. */ optionValues: string[]; /** * 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. */ productId: 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. ```ts T[] ``` * idsForResourcesNotFound The IDs for which a resource was not found. ```ts number[] ``` ```ts export interface MultipleResourceResult { /** * The resources that were fetched using the IDs provided. */ fetchedResources: T[]; /** * The IDs for which a resource was not found. */ idsForResourcesNotFound: 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. ```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. ```ts number ``` * queryString The search term to be used to search for POS products. ```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\`. ```ts ProductSortType ``` ```ts export interface ProductSearchParams extends PaginationParams { /** * The search term to be used to search for POS products. */ queryString?: string; /** * 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`. */ sortType?: ProductSortType; } ``` ### ProductSortType ```ts 'RECENTLY_ADDED' | 'RECENTLY_ADDED_ASCENDING' | 'ALPHABETICAL_A_TO_Z' | 'ALPHABETICAL_Z_TO_A' ``` ## 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. ## Examples Learn how to search for products, fetch product details, and retrieve variants using the native POS search functionality.