--- title: Resource Picker API description: >- The Resource Picker API lets merchants search for and select products, collections, or product variants. Use this API when your app needs merchants to choose Shopify resources to work with. api_version: v1.1 source_url: html: >- https://shopify.dev/docs/api/app-home/v1.1-rc/apis/user-interface-and-interactions/resource-picker-api md: >- https://shopify.dev/docs/api/app-home/v1.1-rc/apis/user-interface-and-interactions/resource-picker-api.md api_name: app-home --- # Resource Picker API **Info:** App Bridge isn't versioned with Polaris. App Bridge APIs and web components are identical in every App Home reference version. The Resource Picker API lets merchants search for and select products, collections, or product variants. Use this API when your app needs merchants to choose Shopify resources to work with. The resource picker returns detailed resource information including IDs, titles, images, and metadata. **Tip:** If you need to pick app-specific resources like product reviews, email templates, or subscription options, use the [Picker](https://shopify.dev/docs/api/app-home/v1.1-rc/apis/user-interface-and-interactions/picker-api) API instead. ### Use cases * **Product selection:** Help users find and select products from the store catalog. * **Collection selection:** Allow users to pick collections for promotions, automations, or display. * **Variant selection:** Enable selection of specific product variants for targeted operations. * **Permission-aware:** Select resources that both the app and the user have permissions to access. ### Inputs The `ResourcePickerOptions` object defines how the resource picker behaves, including which resource type to display, selection limits, filters, and preselected items. * **type** **ResourceType** **required** The type of Shopify resource to select: `'product'` for products, `'variant'` for specific product variants, or `'collection'` for collections. This determines what appears in the picker and what data structure is returned. * **action** **'add' | 'select'** **Default: 'add'** The action verb that appears in the title as the primary action of the resource picker. "Add" prompts merchants that they are appending to an existing list, while "select" they'll choose a resource for a specific purpose or replacing selections. * **filter** **Filters** Filtering options that control which resources appear in the resourcepicker. Use filters to restrict resources by publication status, include or exclude variants, or apply custom search criteria. This helps merchants find relevant items faster. * **multiple** **boolean | number** **Default: false** Whether to allow selecting multiple items of a specific type. If a number is provided, limit selections to that maximum. When `type` is `'product'`, merchants can still select multiple variants from a single product even when `multiple` is `false`. * **query** **string** **Default: ''** Initial GraphQL search query for filtering resources available in the resource picker. See [search syntax](https://shopify.dev/docs/api/usage/search-syntax) for more information. This is displayed in the search bar when the picker is opened and can be edited by users. For most use cases, you should use the `filter.query` option instead which doesn't show the query in the UI. * **selection​Ids** **BaseResource\[]** **Default: \[]** Resources that should be preselected when the picker is opened. Use this for edit workflows to show what products are already in a bundle, collection, or promotional set. Merchants can see current selections and modify them before confirming. ### Filters Filter options that control which resources appear in the resource picker. Use filters to restrict the available resources based on publication status, resource type, or custom search criteria. * archived Whether to include archived products in the picker. When \`false\`, archived products are hidden. When \`undefined\`, archived products appear with an archived badge. Only applies when \`type\` is \`'product'\`. Use this to prevent selecting discontinued products. ```ts boolean | undefined ``` * draft Whether to include draft products in the picker. When \`false\`, draft products are hidden. When \`undefined\`, draft products appear with a draft badge. Only applies when \`type\` is \`'product'\`. Use this to prevent selecting products that aren't ready for use. ```ts boolean | undefined ``` * hidden Whether to include products that aren't published on any sales channels. When \`false\`, only products published to at least one sales channel appear in the picker. Use this to ensure merchants only select products that customers can purchase. ```ts boolean ``` * query A GraphQL search query that filters the available resources without showing the query in the picker's search bar. Merchants won't see or edit this filter. See \[search syntax]\(/docs/api/usage/search-syntax) for the query format. Use this to programmatically restrict resources based on attributes like tags, vendor, or product type (for example, \`"tag:featured"\` or \`"vendor:Acme"\`). ```ts string ``` * variants Whether to show product variants in the picker. When \`false\`, merchants can only select products, not individual variants. Only applies when \`type\` is \`'product'\`. Use this to simplify selection when you only need product-level data. ```ts boolean ``` ### BaseResource A resource structure that can optionally include associated variants. Use this type for specifying preselected items in the resource picker when you need to include variant selections. * id The resource identifier in GraphQL global ID format (for example, \`gid://shopify/Product/123\`). ```ts string ``` * variants An array of variant resources to preselect along with the main resource. Only applicable when the main resource is a product that has variants you want to preselect. ```ts Resource[] ``` ### Resource The base resource structure with a unique identifier. * id The resource identifier in GraphQL global ID format (for example, \`gid://shopify/Product/123\`). ```ts string ``` ### Return payload The resource picker returns an array of selected resources when the merchant confirms their selection, or `undefined` if they cancel. The resource structure in the array varies based on the `type` option: products include variants and images, collections include rule sets, and variants include pricing and inventory data. * **when type is "collection":** **Collection\[]** * **when type is "product":** **Product\[]** * **when type is "variant":** **ProductVariant\[]** ### Collection A collection resource selected from the resource picker. Collections are groups of products organized by manual curation or automated rules. Use collection data to access product groupings, organizational information, and collection metadata. * availablePublicationCount The number of sales channels where this collection can be published. Use this to understand the collection's potential reach across different storefronts. ```ts number ``` * description The collection description as plain text without HTML formatting. Use this when you need the description without markup. ```ts string ``` * descriptionHtml The collection description formatted as HTML. Use this to display rich text descriptions with formatting and styling in your UI. ```ts string ``` * handle The URL-friendly unique identifier used in collection URLs (for example, \`'summer-collection'\` in \`/collections/summer-collection\`). Use this to generate collection links or match URL paths. ```ts string ``` * id The collection's unique global identifier (GID). Use this ID for collection-related GraphQL operations. ```ts string ``` * image The featured image displayed for the collection. Use this for collection thumbnails, headers, or preview images. ```ts ResourceImage | null ``` * productsAutomaticallySortedCount The count of products automatically added to the collection based on automation rules. Use this to understand how many products match the collection's criteria. ```ts number ``` * productsCount The total number of products in the collection, including both manually added and automatically included products. Use this to show collection size or for pagination. ```ts number ``` * productsManuallySortedCount The count of products manually added by the merchant. Use this to understand how much manual curation the collection has. ```ts number ``` * publicationCount The number of sales channels where the collection is currently published. Use this to check the collection's actual visibility across storefronts. ```ts number ``` * ruleSet The automation rules that determine which products are automatically included. Present only for automated (smart) collections. When \`null\`, the collection is manually curated. Use this to understand the collection's filtering logic. ```ts RuleSet | null ``` * seo Search engine optimization metadata for the collection. Use this to understand how the collection appears in search engine results. ```ts { description?: string; title?: string; } ``` * sortOrder The default sort order that determines how products are arranged in the collection. This controls the product sequence customers see on the storefront. ```ts CollectionSortOrder ``` * storefrontId The Storefront API identifier for this collection. Use this ID when making Storefront API queries for this collection. ```ts string ``` * templateSuffix The theme template suffix for using custom theme templates (for example, \`'featured'\` to use \`collection.featured.liquid\`). When \`null\`, uses the default collection template. ```ts string | null ``` * title The collection's display name shown to merchants and customers. Use this as the primary collection identifier in lists and displays. ```ts string ``` * updatedAt ISO 8601 timestamp when the collection was last updated. Use this to track changes, sync with external systems, or show freshness indicators. ```ts string ``` ### ResourceImage An image associated with a product, variant, or collection. Use image data to display thumbnails, galleries, or product previews in your extension. * altText Alternative text describing the image for screen readers and accessibility. This text appears when images fail to load. Use descriptive alt text to make your extension accessible. ```ts string ``` * id The unique identifier for the image file. Use this ID for image-related GraphQL operations. ```ts string ``` * originalSrc The full URL to the original image file. Use this URL to display the image in your extension UI. ```ts string ``` ### RuleSet A set of rules that determine which products are automatically included in a collection. Use this to understand how an automated collection populates itself with products. * appliedDisjunctively The logical operator for combining multiple rules. When \`true\`, products are included if they match ANY rule (OR logic). When \`false\`, products must match ALL rules (AND logic). Use this to understand the collection's filtering strategy. ```ts boolean ``` * rules An array of rules that define product inclusion criteria. Each rule checks a different product attribute. Products are added to the collection based on how these rules are combined (see \`appliedDisjunctively\`). ```ts CollectionRule[] ``` ### CollectionRule A single rule that defines product inclusion criteria for an automated collection. Rules filter products based on their attributes to automatically populate a collection. * column The product field to evaluate (for example, \`'title'\`, \`'tag'\`, \`'vendor'\`, or \`'product\_type'\`). This determines which product attribute the rule checks. ```ts string ``` * condition The value to compare against. For example, if checking tags, this might be \`'summer'\` or \`'featured'\`. The product attribute must match this condition value according to the relation. ```ts string ``` * relation The comparison operator that determines how the field is matched (for example, \`'equals'\`, \`'contains'\`, \`'starts\_with'\`, \`'ends\_with'\`, \`'not\_equals'\`). This defines the matching logic between the column and condition. ```ts string ``` ### CollectionSortOrder The sort order that determines how products appear in a collection. This controls the default product arrangement that customers see when viewing the collection on the storefront. * Manual Products arranged in the custom order set by the merchant. Use this when merchants have manually organized products for specific merchandising. ```ts MANUAL ``` * BestSelling Products sorted by sales volume, with best-sellers first. Use this to highlight popular products. ```ts BEST_SELLING ``` * AlphaAsc Products sorted alphabetically by title from A to Z. Use this for easy browsing of product names. ```ts ALPHA_ASC ``` * AlphaDesc Products sorted alphabetically by title from Z to A. Use this for reverse alphabetical ordering. ```ts ALPHA_DESC ``` * PriceDesc Products sorted by price from highest to lowest. Use this to show premium or expensive items first. ```ts PRICE_DESC ``` * PriceAsc Products sorted by price from lowest to highest. Use this to show affordable options first. ```ts PRICE_ASC ``` * CreatedDesc Products sorted by creation date with newest products first. Use this to highlight recently added items. ```ts CREATED_DESC ``` * Created Products sorted by creation date with oldest products first. Use this for chronological ordering. ```ts CREATED ``` * MostRelevant Products sorted by search relevance based on query terms. Use this when the collection is filtered by search. ```ts MOST_RELEVANT ``` ### Product A product configuration. * handle The URL-friendly unique identifier used in product URLs (for example, \`'blue-t-shirt'\`). ```ts string ``` * hasOnlyDefaultVariant Whether the product has only the default variant with no custom options. When \`true\`, the product has no size, color, or other option variations. ```ts boolean ``` * id The product's unique global identifier (GID). ```ts string ``` * onlineStoreUrl The URL to view this product on the online store. Use this to create "View in store" links. ```ts string ``` * options Product options that define how variants differ (for example, Size, Color, Material). Each option has an ID, name, position, and array of possible values. ```ts { id: string; name: string; position: number; values: string[]; }[] ``` * productCategory The standardized product category taxonomy. Use this for product classification in search and organization. ```ts string ``` * productComponents An array of component products that make up this bundle. Each component represents a product included in the bundle configuration. ```ts ProductComponent[] ``` * productType The product category or type used for organization (for example, "T-Shirt", "Shoes"). ```ts string ``` * status The publication status indicating whether the product is active (published), archived (discontinued), or draft (unpublished). ```ts 'ACTIVE' | 'ARCHIVED' | 'DRAFT' ``` * title The product's display name shown to merchants and customers. ```ts string ``` * totalInventory The total available inventory summed across all variants and locations. ```ts number ``` * totalVariants The total number of variants this product has. ```ts number ``` ### ProductComponent A component product that is part of a bundle. Represents an individual product included in a bundle configuration. * componentVariantsCount The count of variants from this product that are used as bundle components. Use this to understand how many variants are configured in bundles. ```ts number ``` * featuredImage The featured image displayed for this component product with ID, URL, and alt text properties. Use this for showing component previews in bundle configuration interfaces. ```ts { id?: string | null; url?: string | null; altText?: string | null; } | null ``` * id The component product's unique global identifier (GID). ```ts string ``` * nonComponentVariantsCount The count of variants from this product that aren't used in any bundles. Use this to identify available variants for adding to bundle configurations. ```ts number ``` * productUrl The admin URL for this component product. Use this to create links to the product's details page in the admin. ```ts string ``` * title The product's display name. Use this to show which product is included in the bundle. ```ts string ``` * totalVariants The total number of variants this component product has. Use this to determine if variant selection is needed for this component. ```ts number ``` ### ProductVariant A product variant configuration. * barcode The barcode, UPC, or ISBN number for the variant. ```ts string ``` * compareAtPrice The original price before any discounts or markdowns. ```ts string ``` * displayName A human-readable display name that combines the product title with the variant's option values (for example, "T-Shirt - Medium / Blue"). ```ts string ``` * id The variant's unique global identifier (GID). ```ts string ``` * price The current selling price for this variant. ```ts string ``` * productVariantComponents An array of component variants that make up this bundle variant. Each component represents a product variant included in the bundle. ```ts ProductVariantComponent[] ``` * selectedOptions The option values that define this specific variant with name and value pairs (for example, Size: Large, Color: Blue). ```ts { name: string; value: string; }[] ``` * sku The Stock Keeping Unit (SKU) identifier for inventory tracking. ```ts string ``` * taxable Whether this variant is subject to taxes. When \`true\`, applicable taxes are calculated at checkout. ```ts boolean ``` * taxCode The harmonized system (HS) tax code for international shipping and customs. ```ts string ``` * title The display name showing only the variant's option values (for example, "Medium / Blue"). ```ts string ``` * weight The physical weight of the variant as a number. ```ts number ``` ### ProductVariantComponent A component variant that is part of a product bundle. Represents an individual product variant included in a bundle configuration. * displayName A human-readable display name that combines the product title with the variant's option values (for example, "T-Shirt - Medium / Blue"). ```ts string ``` * id The component variant's unique global identifier (GID). ```ts string ``` * image The image displayed for this component variant with ID, URL, and alt text properties. Use this for showing component previews in bundle configuration interfaces. ```ts { id?: string | null; url?: string | null; altText?: string | null; } | null ``` * productVariantUrl The admin URL for this product variant. Use this to create links to the variant's details page in the admin. ```ts string ``` * selectedOptions The option values that define this specific component variant with name and value pairs (for example, Size: Large, Color: Blue). ```ts { name: string; value: string; }[] ``` * sku The Stock Keeping Unit (SKU) identifier for this component variant. ```ts string ``` * title The display name showing only the variant's option values (for example, "Medium / Blue"). ```ts string ``` Examples ## Preview ![Select products from the store catalog. This example opens a product resource picker and handles the selection response. The resource picker returns an array of product objects with GIDs, titles, and handles.](https://shopify.dev/assets/assets/images/templated-apis-screenshots/admin/apis/resource-picker-DeAqlQby.png) ### Examples * #### ##### Description Select products from the store catalog. This example opens a product resource picker and handles the selection response. The resource picker returns an array of product objects with GIDs, titles, and handles. ##### js ```js const selected = await shopify.resourcePicker({type: 'product'}); ``` * #### ##### Description Select collections or variants. This example selects collections instead of individual products by setting \`type: "collection"\`, or selects specific product variants by setting \`type: "variant"\`. Use collection mode for choosing product groupings, such as homepage featured collection carousels, navigation menu builders, or promotional campaigns. Use variant mode for choosing individual SKUs, useful for inventory tools, variant-specific promotions, or shipment builders. ##### Collections ```js const selected = await shopify.resourcePicker({type: 'collection'}); ``` ##### Product variants ```js const selected = await shopify.resourcePicker({type: 'variant'}); ``` * #### ##### Description Preselect products. This example opens the resource picker with products already selected by passing GIDs to the \`selectionIds\` option. Use this to pre-populate the picker with current selections for edit workflows, showing what products are already in a bundle, collection, or promotional set. Merchants can see current selections and modify them before confirming. ##### js ```js const selected = await shopify.resourcePicker({ type: 'product', selectionIds: [ { id: 'gid://shopify/Product/12345', variants: [ { id: 'gid://shopify/ProductVariant/1', }, ], }, { id: 'gid://shopify/Product/67890', }, ], }); ``` * #### ##### Description Set action verb. This example customizes the resource picker button text by setting the \`action\` option to "add" or "select". "Add" suggests appending to an existing list, while "select" implies choosing for a specific purpose or replacing selections. This subtle language difference improves clarity for different workflow contexts. ##### js ```js const selected = await shopify.resourcePicker({ type: 'product', action: 'select', }); ``` * #### ##### Description Limit selection count. This example controls how many products merchants can select. Set \`multiple: true\` for unlimited selection useful for mass product taggers, bulk inventory tools, or export utilities. Set \`multiple\` to a number like \`5\` to limit selection count for bundle builders with item limits, featured product sections, or promotional campaigns with maximum product counts. ##### Unlimited selectable items ```js const selected = await shopify.resourcePicker({ type: 'product', multiple: true, }); ``` ##### Maximum selectable items ```js const selected = await shopify.resourcePicker({ type: 'product', multiple: 5, }); ``` * #### ##### Description Filter resources. This example filters the resource picker to show only specific products using the \`filter\` option. Use \`variants: false\` to hide variant information, \`hidden: false\` to exclude hidden products, \`draft: false\` to exclude draft products, or \`archived: false\` to exclude archived products. Combine filters to restrict the picker to live, customer-visible products. ##### js ```js const selected = await shopify.resourcePicker({ type: 'product', filter: { hidden: true, variants: false, draft: false, archived: false, }, }); ``` * #### ##### Description Apply a filter query. This example applies a custom GraphQL search query using the \`query\` property in filters. The query runs server-side and is not visible to merchants. Use it to programmatically restrict results (for example, \`vendor:Acme\` or \`tag:sale\`) without exposing the filter logic. ##### js ```js const selected = await shopify.resourcePicker({ type: 'product', filter: { query: 'Sweater', }, }); ``` * #### ##### Description Handle selection payload. This example handles the selection payload returned by the resource picker. When merchants confirm their selection, the picker returns an array of resource objects. When merchants cancel, it returns \`undefined\` rather than an empty array. Check for \`undefined\` explicitly to distinguish between cancellation and an empty selection. ##### js ```js const selected = await shopify.resourcePicker({type: 'product'}); if (selected) { console.log(selected); } else { console.log('Picker was cancelled by the user'); } ``` * #### ##### Description Start with search query. This example starts the resource picker with a pre-filled search query by passing the \`query\` option. This initializes the picker with a search term already entered, helpful when you know what merchants are likely looking for. Merchants can modify the query, but starting with relevant results saves time in large catalogs. ##### js ```js const selected = await shopify.resourcePicker({ type: 'product', query: 'Sweater', }); ``` ***