Product
APIs
The ProductSearch API gives extensions access to the native product search and fetching functionality of Shopify POS. The interface provides numerous functions to search for products by query, or to fetch the details of one or more products or product variants.
Anchor to productsearchapiProductSearchApi
- Anchor to fetchPaginatedProductVariantsWithProductIdfetchPaginatedProductVariantsWithProductId(productId: number, paginationParams: PaginationParams) => Promise<PaginatedResult<ProductVariant>>required
Fetches a page of product variants associated with a product.
- Anchor to fetchProductsWithIdsfetchProductsWithIds(productIds: number[]) => Promise<MultipleResourceResult<Product>>required
Fetches multiple products' details.
- Anchor to fetchProductVariantsWithIdsfetchProductVariantsWithIds(productVariantIds: number[]) => Promise<MultipleResourceResult<ProductVariant>>required
Fetches multiple product variants' details.
- Anchor to fetchProductVariantsWithProductIdfetchProductVariantsWithProductId(productId: number) => Promise<ProductVariant[]>required
Fetches all product variants associated with a product.
- Anchor to fetchProductVariantWithIdfetchProductVariantWithId(productVariantId: number) => Promise<ProductVariant>required
Fetches a single product variant's details.
- Anchor to fetchProductWithIdfetchProductWithId(productId: number) => Promise<Product>required
Fetches a single product's details.
- Anchor to searchProductssearchProducts(searchParams: ProductSearchParams) => Promise<PaginatedResult<Product>>required
Search for products on the POS device.
PaginationParams
Base interface for pagination.
- 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
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
Contains a page of fetched results.
- 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
export interface PaginatedResult<T> {
/**
* 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
- barcode
string - compareAtPrice
string - createdAt
string - displayName
string - hasInStockVariants
boolean - id
number - image
string - inventoryAtAllLocations
number - inventoryAtLocation
number - inventoryIsTracked
boolean - inventoryPolicy
ProductVariantInventoryPolicy - options
ProductVariantOption[] - position
number - price
string - product
Product - productId
number - sku
string - taxable
boolean - title
string - updatedAt
string
export interface ProductVariant {
id: number;
createdAt: string;
updatedAt: string;
title: string;
price: string;
compareAtPrice?: string;
taxable: boolean;
sku?: string;
barcode?: string;
displayName: string;
image?: string;
inventoryIsTracked: boolean;
inventoryAtLocation?: number;
inventoryAtAllLocations?: number;
inventoryPolicy: ProductVariantInventoryPolicy;
hasInStockVariants?: boolean;
options?: ProductVariantOption[];
product?: Product;
productId: number;
position: number;
}ProductVariantInventoryPolicy
'DENY' | 'CONTINUE'ProductVariantOption
- name
string - value
string
export interface ProductVariantOption {
name: string;
value: string;
}Product
- createdAt
string - description
string - descriptionHtml
string - featuredImage
string - hasInStockVariants
boolean - hasOnlyDefaultVariant
boolean - hasSellingPlanGroups
boolean - id
number - isGiftCard
boolean - maxVariantPrice
string - minVariantPrice
string - numVariants
number - onlineStoreUrl
string - options
ProductOption[] - productCategory
string - productType
string - requiresSellingPlan
boolean - tags
string[] - title
string - totalAvailableInventory
number - totalInventory
number - tracksInventory
boolean - updatedAt
string - variants
ProductVariant[] - vendor
string
export interface Product {
id: number;
createdAt: string;
updatedAt: string;
title: string;
description: string;
descriptionHtml: string;
featuredImage?: string;
isGiftCard: boolean;
tracksInventory: boolean;
vendor: string;
minVariantPrice: string;
maxVariantPrice: string;
productType: string;
productCategory: string;
tags: string[];
numVariants: number;
totalAvailableInventory?: number;
totalInventory: number;
variants: ProductVariant[];
options: ProductOption[];
hasOnlyDefaultVariant: boolean;
hasInStockVariants?: boolean;
onlineStoreUrl?: string;
requiresSellingPlan?: boolean;
hasSellingPlanGroups?: boolean;
}ProductOption
- id
number - name
string - optionValues
string[] - productId
number
export interface ProductOption {
id: number;
name: string;
optionValues: string[];
productId: number;
}MultipleResourceResult
The result of a fetch function where the input is multiple IDs. This object contains the resources that were found, as well as an array of IDs specifying which IDs, if any, did not correspond to a resource.
- fetchedResources
The resources that were fetched using the IDs provided.
T[] - idsForResourcesNotFound
The IDs for which a resource was not found.
number[]
export interface MultipleResourceResult<T> {
/**
* The resources that were fetched using the IDs provided.
*/
fetchedResources: T[];
/**
* The IDs for which a resource was not found.
*/
idsForResourcesNotFound: number[];
}ProductSearchParams
Interface for product search
- 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
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
'RECENTLY_ADDED' | 'RECENTLY_ADDED_ASCENDING' | 'ALPHABETICAL_A_TO_Z' | 'ALPHABETICAL_Z_TO_A'Was this section helpful?
Anchor to examplesExamples
Examples of using the Cart API
Anchor to example-search-for-products-with-a-search-barSearch for products with a search bar
Anchor to example-fetch-a-specific-product-with-a-product-idFetch a specific product with a product ID
Anchor to example-fetch-multiple-products-by-specifying-product-idsFetch multiple products by specifying product IDs
Anchor to example-fetch-a-specific-product-variant-with-a-variant-idFetch a specific product variant with a variant ID
Anchor to example-fetch-multiple-product-variants-by-specifying-variant-idsFetch multiple product variants by specifying variant IDs
Anchor to example-fetch-a-page-of-product-variants-with-a-specific-product-idFetch a page of product variants with a specific product ID
Was this section helpful?
Search for products with a search bar
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.target.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>
);
};
Examples
Search for products with a search bar
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.target.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> ); };Fetch a specific product with a product ID
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> ); };Fetch multiple products by specifying product IDs
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> ); };Fetch a specific product variant with a variant ID
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> ); };Fetch multiple product variants by specifying variant IDs
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> ); };Fetch a page of product variants with a specific product ID
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> ); };