---
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_name: app-home
source_url:
  html: https://shopify.dev/docs/api/app-home/apis/user-interface-and-interactions/resource-picker-api
  md: https://shopify.dev/docs/api/app-home/apis/user-interface-and-interactions/resource-picker-api.md
---

# Resource Picker API

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-bridge-library/apis/picker) 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.

* **selectionIds**

  **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

* archived

  Whether to show \[archived products]\(https://help.shopify.com/en/manual/products/details?shpxid=70af7d87-E0F2-4973-8B09-B972AAF0ADFD#product-availability). Only applies to the Product resource type picker. Setting this to undefined will show a badge on draft products.

  ```ts
  boolean | undefined
  ```

* draft

  Whether to show \[draft products]\(https://help.shopify.com/en/manual/products/details?shpxid=70af7d87-E0F2-4973-8B09-B972AAF0ADFD#product-availability). Only applies to the Product resource type picker. Setting this to undefined will show a badge on draft products.

  ```ts
  boolean | undefined
  ```

* hidden

  Whether to show hidden resources, referring to products that are not published on any sales channels.

  ```ts
  boolean
  ```

* query

  GraphQL initial search query for filtering resources available in the picker. See \[search syntax]\(https://shopify.dev/docs/api/usage/search-syntax) for more information. This query is not visible to merchants and runs server-side. Use it to programmatically restrict results (for example, \`vendor:Acme\`) without exposing the filter logic.

  ```ts
  string
  ```

* variants

  Whether to show product variants. Only applies to the Product resource type picker.

  ```ts
  boolean
  ```

### BaseResource

* id

  in GraphQL id format, ie 'gid://shopify/Product/1'

  ```ts
  string
  ```

* variants

  ```ts
  Resource[]
  ```

### Resource

* id

  in GraphQL id format, ie 'gid://shopify/Product/1'

  ```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

* availablePublicationCount

  ```ts
  number
  ```

* description

  ```ts
  string
  ```

* descriptionHtml

  ```ts
  string
  ```

* handle

  ```ts
  string
  ```

* id

  in GraphQL id format, ie 'gid://shopify/Product/1'

  ```ts
  string
  ```

* image

  ```ts
  Image | null
  ```

* productsAutomaticallySortedCount

  ```ts
  number
  ```

* productsCount

  ```ts
  number
  ```

* productsManuallySortedCount

  ```ts
  number
  ```

* publicationCount

  ```ts
  number
  ```

* ruleSet

  ```ts
  RuleSet | null
  ```

* seo

  ```ts
  { description?: string; title?: string; }
  ```

* sortOrder

  ```ts
  CollectionSortOrder
  ```

* storefrontId

  ```ts
  string
  ```

* templateSuffix

  ```ts
  string | null
  ```

* title

  ```ts
  string
  ```

* updatedAt

  ```ts
  string
  ```

### Image

* altText

  ```ts
  string
  ```

* id

  ```ts
  string
  ```

* originalSrc

  ```ts
  string
  ```

### RuleSet

* appliedDisjunctively

  ```ts
  boolean
  ```

* rules

  ```ts
  CollectionRule[]
  ```

### CollectionRule

* column

  ```ts
  string
  ```

* condition

  ```ts
  string
  ```

* relation

  ```ts
  string
  ```

### CollectionSortOrder

* Manual

  ```ts
  MANUAL
  ```

* BestSelling

  ```ts
  BEST_SELLING
  ```

* AlphaAsc

  ```ts
  ALPHA_ASC
  ```

* AlphaDesc

  ```ts
  ALPHA_DESC
  ```

* PriceDesc

  ```ts
  PRICE_DESC
  ```

* PriceAsc

  ```ts
  PRICE_ASC
  ```

* CreatedDesc

  ```ts
  CREATED_DESC
  ```

* Created

  ```ts
  CREATED
  ```

* MostRelevant

  ```ts
  MOST_RELEVANT
  ```

### Product

* availablePublicationCount

  ```ts
  number
  ```

* createdAt

  ```ts
  string
  ```

* descriptionHtml

  ```ts
  string
  ```

* handle

  ```ts
  string
  ```

* hasOnlyDefaultVariant

  ```ts
  boolean
  ```

* id

  in GraphQL id format, ie 'gid://shopify/Product/1'

  ```ts
  string
  ```

* images

  ```ts
  Image[]
  ```

* options

  ```ts
  { id: string; name: string; position: number; values: string[]; }[]
  ```

* productType

  ```ts
  string
  ```

* publishedAt

  ```ts
  string | null
  ```

* status

  ```ts
  ProductStatus
  ```

* tags

  ```ts
  string[]
  ```

* templateSuffix

  ```ts
  string | null
  ```

* title

  ```ts
  string
  ```

* totalInventory

  ```ts
  number
  ```

* totalVariants

  ```ts
  number
  ```

* tracksInventory

  ```ts
  boolean
  ```

* updatedAt

  ```ts
  string
  ```

* variants

  ```ts
  Partial<ProductVariant>[]
  ```

* vendor

  ```ts
  string
  ```

### ProductStatus

* Active

  ```ts
  ACTIVE
  ```

* Archived

  ```ts
  ARCHIVED
  ```

* Draft

  ```ts
  DRAFT
  ```

### ProductVariant

* availableForSale

  ```ts
  boolean
  ```

* barcode

  ```ts
  string | null
  ```

* compareAtPrice

  ```ts
  Money | null
  ```

* createdAt

  ```ts
  string
  ```

* displayName

  ```ts
  string
  ```

* fulfillmentService

  ```ts
  { id: string; inventoryManagement: boolean; productBased: boolean; serviceName: string; type: FulfillmentServiceType; }
  ```

* id

  in GraphQL id format, ie 'gid://shopify/Product/1'

  ```ts
  string
  ```

* image

  ```ts
  Image | null
  ```

* inventoryItem

  ```ts
  { id: string; }
  ```

* inventoryManagement

  ```ts
  ProductVariantInventoryManagement
  ```

* inventoryPolicy

  ```ts
  ProductVariantInventoryPolicy
  ```

* inventoryQuantity

  ```ts
  number | null
  ```

* position

  ```ts
  number
  ```

* price

  ```ts
  Money
  ```

* product

  ```ts
  Partial<Product>
  ```

* requiresShipping

  ```ts
  boolean
  ```

* selectedOptions

  ```ts
  { value?: string; }[]
  ```

* sku

  ```ts
  string | null
  ```

* taxable

  ```ts
  boolean
  ```

* title

  ```ts
  string
  ```

* updatedAt

  ```ts
  string
  ```

* weight

  ```ts
  number | null
  ```

* weightUnit

  ```ts
  WeightUnit
  ```

### Money

```ts
string
```

### FulfillmentServiceType

* GiftCard

  ```ts
  GIFT_CARD
  ```

* Manual

  ```ts
  MANUAL
  ```

* ThirdParty

  ```ts
  THIRD_PARTY
  ```

### ProductVariantInventoryManagement

* Shopify

  ```ts
  SHOPIFY
  ```

* NotManaged

  ```ts
  NOT_MANAGED
  ```

* FulfillmentService

  ```ts
  FULFILLMENT_SERVICE
  ```

### ProductVariantInventoryPolicy

* Deny

  ```ts
  DENY
  ```

* Continue

  ```ts
  CONTINUE
  ```

### WeightUnit

* Kilograms

  ```ts
  KILOGRAMS
  ```

* Grams

  ```ts
  GRAMS
  ```

* Pounds

  ```ts
  POUNDS
  ```

* Ounces

  ```ts
  OUNCES
  ```

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://cdn.shopify.com/shopifycloud/shopify-dev/production/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',
  });
  ```

***