Choose a version:

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.

Anchor to Use casesUse cases

Search interfaces: Implement custom product search with advanced filtering and sorting.
Recommendations: Build product recommendation systems based on search results.
Inventory lookup: Create inventory tools that lookup product details and variant information.
Upselling: Develop upselling and cross-selling features by searching for complementary products.

Support

Targets (28)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides product search and lookup methods. Access the following properties on shopify to search for products, fetch product details, and retrieve product variants.

Anchor to fetchPaginatedProductVariantsWithProductId fetchPaginatedProductVariantsWithProductId (productId: number, 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.
Anchor to fetchProductsWithIds 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.
Anchor to fetchProductVariantsWithIds 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.
Anchor to fetchProductVariantsWithProductId 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.
Anchor to fetchProductVariantWithId 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.
Anchor to fetchProductWithId 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.
Anchor to searchProducts searchProducts (searchParams: ) => 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.
```
string
```
first
Specifies the number of results to be returned in this page. The maximum number of items that will be returned is 50.
```
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 or not there is another page of results that can be fetched.
```
boolean
```
items
The items returned from the fetch.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
string
```
taxable
Whether this variant is subject to tax calculations. Use for tax computation logic, pricing displays, or implementing tax-exempt product handling.
```
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.
```
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.
```
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.

'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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
ProductOption[]
```
productCategory
The standardized product category classification. Use for product categorization, implementing category-specific business logic, or organizing products by standardized categories.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
T[]
```
idsForResourcesNotFound
The IDs for which a resource was not found.
```
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.
```
string
```
first
Specifies the number of results to be returned in this page. The maximum number of items that will be returned is 50.
```
number
```
queryString
The search term to be used to search for POS products.
```
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`.
```
ProductSortType
```

ProductSortType

'RECENTLY_ADDED' | 'RECENTLY_ADDED_ASCENDING' | 'ALPHABETICAL_A_TO_Z' | 'ALPHABETICAL_Z_TO_A'

Examples

jsx

import {render} from 'preact';

import {useState, useEffect} from 'preact/hooks';

export default async () => {

render(<Extension />, document.body);

};

const Extension = () => {

const [product, setProduct] = useState(null);

useEffect(() => {

const fetchProduct = async () => {

const resultProduct = await shopify.productSearch.fetchProductWithId(1);

setProduct(resultProduct);

};

fetchProduct();

}, []);

return (

<s-page heading="Hello World!">

<s-scroll-box>

<s-text>

{product ? `Product: ${product.title}` : 'Loading...'}

</s-text>

</s-scroll-box>

</s-page>

);

};

Examples

Description

Fetch a single product by ID. This example demonstrates using `shopify.productSearch.fetchById()` to get complete product data including variants, pricing, and inventory information for a single product.

jsx

import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

const Extension = () => {
  const [product, setProduct] = useState(null);

  useEffect(() => {
    const fetchProduct = async () => {
      const resultProduct = await shopify.productSearch.fetchProductWithId(1);
      setProduct(resultProduct);
    };

    fetchProduct();
  }, []);

  return (
    <s-page heading="Hello World!"> 
      <s-scroll-box>
        <s-text>
          {product ? `Product: ${product.title}` : 'Loading...'}
        </s-text>
      </s-scroll-box>
    </s-page>
  );
};

Description

Fetch a single variant by ID. This example demonstrates using `shopify.productSearch.fetchVariantById()` to get variant-specific data including pricing, inventory, and options for a particular variant.

jsx

import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

const Extension = () => {
  const [variant, setVariant] = useState(null);

  useEffect(() => {
    const fetchProductVariant = async () => {
      const resultProductVariant = await shopify.productSearch.fetchProductVariantWithId(1);
      setVariant(resultProductVariant);
    };

    fetchProductVariant();
  }, []);

  return (
    <s-page heading="Hello World!">
      <s-scroll-box>
        <s-text>
          {variant ? `Variant: ${variant.title}` : 'Loading...'}
        </s-text>
      </s-scroll-box>
    </s-page>
  );
};

Description

Fetch multiple products by IDs. This example shows how to use `shopify.productSearch.fetchByIds()` to efficiently fetch data for multiple products in a single request. This improves performance when displaying product lists or related items.

jsx

import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

const Extension = () => {
  const [products, setProducts] = useState([]);

  useEffect(() => {
    const fetchProducts = async () => {
      const results = await shopify.productSearch.fetchProductsWithIds([1, 2, 3]);
      setProducts(results.fetchedResources);
      console.log('IDs not found: ', results.idsForResourcesNotFound);
    };

    fetchProducts();
  }, []);

  return (
    <s-page heading="Hello World!">
      <s-scroll-box>
        <s-text>Found {products.length} products</s-text>
        {products.map((product) => (
          <s-text key={product.id}>{product.title}</s-text>
        ))}
      </s-scroll-box>
    </s-page>
  );
};

Description

Fetch multiple variants by IDs. This example shows how to use `shopify.productSearch.fetchVariantsByIds()` to efficiently fetch data for multiple variants in a single request. This is useful for displaying variant lists or comparisons.

jsx

import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

const Extension = () => {
  const [variants, setVariants] = useState([]);

  useEffect(() => {
    const fetchProductVariants = async () => {
      const results = await shopify.productSearch.fetchProductVariantsWithIds([1, 2, 3]);
      setVariants(results.fetchedResources);
      console.log('IDs not found: ', results.idsForResourcesNotFound);
    };

    fetchProductVariants();
  }, []);

  return (
    <s-page heading="Hello World!">
      <s-scroll-box>
        <s-text>Found {variants.length} variants</s-text>
        {variants.map((variant) => (
          <s-text key={variant.id}>{variant.title}</s-text>
        ))}
      </s-scroll-box>
    </s-page>
  );
};

Description

Fetch paginated variants for a product. This example demonstrates using `shopify.productSearch.fetchVariantsByProductId()` with pagination parameters to load variants page by page. This improves performance and user experience for products with large variant catalogs.

jsx

import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

const Extension = () => {
  const [variants, setVariants] = useState([]);

  useEffect(() => {
    const fetchProductVariants = async () => {
      const results = await shopify.productSearch.fetchPaginatedProductVariantsWithProductId(1, {first: 10});
      setVariants(results.items);
      console.log('Cursor for next page: ', results.lastCursor);
    };

    fetchProductVariants();
  }, []);

  return (
    <s-page heading="Hello World!">
      <s-scroll-box>
        <s-text>Found {variants.length} variants</s-text>
        {variants.map((variant) => (
          <s-text key={variant.id}>{variant.title}</s-text>
        ))}
      </s-scroll-box>
    </s-page>
  );
};

Description

Search for products using a search bar. This example shows how to use `shopify.productSearch.search()` to perform text-based product searches with pagination support. This allows users to find products by name, SKU, or other searchable attributes.

jsx

import {render} from 'preact';
import {useState} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

const Extension = () => {
  const [searchResults, setSearchResults] = useState([]);

  const search = async (event) => {
    const results = await shopify.productSearch.searchProducts({queryString: event.currentTarget.value});
    setSearchResults(results.items);
  };

  return (
    <s-page heading="Hello World!">
      <s-scroll-box>
        <s-search-field
          placeholder="Search products"
          onInput={search}
        />
        <s-text>Found {searchResults.length} products</s-text>
      </s-scroll-box>
    </s-page>
  );
};

Anchor to Best practicesBest practices

Implement efficient pagination: Use appropriate page sizes and cursor-based pagination to balance performance with user experience, especially for large product catalogs.
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.

Anchor to LimitationsLimitations

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.

Was this page helpful?