Resource Picker

The Resource Picker API provides a search-based interface to help users find and select one or more products, collections, or product variants, and then returns the selected resources to your app. Both the app and the user must have the necessary permissions to access the resources selected.

Tip

If you are picking app resources such as product reviews, email templates, or subscription options, you should use the Picker API instead.

Anchor to resource picker optionsResource Picker Options

The Resource Picker accepts a variety of options to customize the picker's behavior.

Anchor to type type 'product' | 'variant' | 'collection' required: The type of resource you want to pick.
Anchor to action action 'add' | 'select' Default: 'add': The action verb appears in the title and as the primary action of the Resource Picker.
Anchor to filter filter: Filters for what resource to show.
Anchor to multiple multiple boolean | number Default: false: Whether to allow selecting multiple items of a specific type or not. If a number is provided, then limit the selections to a maximum of that number of items. When type is Product, the user may still select multiple variants of a single product, even if multiple is false.
Anchor to query query string Default: '': GraphQL initial search query for filtering resources available in the picker. See 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.
Anchor to selectionIds selectionIds [] Default: []: Resources that should be preselected when the picker is opened.

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.
```
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.
```
boolean | undefined
```
hidden
Whether to show hidden resources, referring to products that are not published on any sales channels.
```
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 is not displayed in the search bar when the picker is opened.
```
string
```
variants
Whether to show product variants. Only applies to the Product resource type picker.
```
boolean
```

interface Filters {
  /**
   * Whether to show hidden resources, referring to products that are not published on any sales channels.
   * @defaultValue true
   */
  hidden?: boolean;
  /**
   * Whether to show product variants. Only applies to the Product resource type picker.
   * @defaultValue true
   */
  variants?: boolean;
  /**
   * 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.
   * @defaultValue true
   */
  draft?: boolean | undefined;
  /**
   * 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.
   * @defaultValue true
   */
  archived?: boolean | undefined;
  /**
   * 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 is not displayed in the search bar when the picker is opened.
   */
  query?: string;
}

BaseResource

id
in GraphQL id format, ie 'gid://shopify/Product/1'
```
string
```
variants
```
Resource[]
```

interface BaseResource extends Resource {
  variants?: Resource[];
}

Resource

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

interface Resource {
  /** in GraphQL id format, ie 'gid://shopify/Product/1' */
  id: string;
}

Anchor to resource picker return payloadResource Picker Return Payload

The Resource Picker returns a Promise with an array of the selected resources. The object type in the array varies based on the provided type option.

If the picker is cancelled, the Promise resolves to undefined

Anchor to when type is "collection": when type is "collection": []
Anchor to when type is "product": when type is "product": []
Anchor to when type is "variant": when type is "variant": []

Collection

availablePublicationCount
```
number
```
description
```
string
```
descriptionHtml
```
string
```
handle
```
string
```
id
in GraphQL id format, ie 'gid://shopify/Product/1'
```
string
```
image
```
Image | null
```
productsAutomaticallySortedCount
```
number
```
productsCount
```
number
```
productsManuallySortedCount
```
number
```
publicationCount
```
number
```
ruleSet
```
RuleSet | null
```

seo

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

sortOrder
```
CollectionSortOrder
```
storefrontId
```
string
```
templateSuffix
```
string | null
```
title
```
string
```
updatedAt
```
string
```

export interface Collection extends Resource {
  availablePublicationCount: number;
  description: string;
  descriptionHtml: string;
  handle: string;
  id: string;
  image?: Image | null;
  productsAutomaticallySortedCount: number;
  productsCount: number;
  productsManuallySortedCount: number;
  publicationCount: number;
  ruleSet?: RuleSet | null;
  seo: {
    description?: string | null;
    title?: string | null;
  };
  sortOrder: CollectionSortOrder;
  storefrontId: string;
  templateSuffix?: string | null;
  title: string;
  updatedAt: string;
}

Image

altText
```
string
```
id
```
string
```
originalSrc
```
string
```

interface Image {
  id: string;
  altText?: string;
  originalSrc: string;
}

RuleSet

appliedDisjunctively
```
boolean
```
rules
```
CollectionRule[]
```

interface RuleSet {
  appliedDisjunctively: boolean;
  rules: CollectionRule[];
}

CollectionRule

column
```
string
```
condition
```
string
```
relation
```
string
```

interface CollectionRule {
  column: string;
  condition: string;
  relation: string;
}

CollectionSortOrder

Manual
```
MANUAL
```
BestSelling
```
BEST_SELLING
```
AlphaAsc
```
ALPHA_ASC
```
AlphaDesc
```
ALPHA_DESC
```
PriceDesc
```
PRICE_DESC
```
PriceAsc
```
PRICE_ASC
```
CreatedDesc
```
CREATED_DESC
```
Created
```
CREATED
```
MostRelevant
```
MOST_RELEVANT
```

enum CollectionSortOrder {
  Manual = 'MANUAL',
  BestSelling = 'BEST_SELLING',
  AlphaAsc = 'ALPHA_ASC',
  AlphaDesc = 'ALPHA_DESC',
  PriceDesc = 'PRICE_DESC',
  PriceAsc = 'PRICE_ASC',
  CreatedDesc = 'CREATED_DESC',
  Created = 'CREATED',
  MostRelevant = 'MOST_RELEVANT',
}

Product

availablePublicationCount
```
number
```
createdAt
```
string
```
descriptionHtml
```
string
```
handle
```
string
```
hasOnlyDefaultVariant
```
boolean
```
id
in GraphQL id format, ie 'gid://shopify/Product/1'
```
string
```
images
```
Image[]
```

options

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

productType
```
string
```
publishedAt
```
string | null
```
status
```
ProductStatus
```
tags
```
string[]
```
templateSuffix
```
string | null
```
title
```
string
```
totalInventory
```
number
```
totalVariants
```
number
```
tracksInventory
```
boolean
```
updatedAt
```
string
```
variants
```
Partial<ProductVariant>[]
```
vendor
```
string
```

export interface Product extends Resource {
  availablePublicationCount: number;
  createdAt: string;
  descriptionHtml: string;
  handle: string;
  hasOnlyDefaultVariant: boolean;
  images: Image[];
  options: {
    id: string;
    name: string;
    position: number;
    values: string[];
  }[];
  productType: string;
  publishedAt?: string | null;
  tags: string[];
  templateSuffix?: string | null;
  title: string;
  totalInventory: number;
  totalVariants: number;
  tracksInventory: boolean;
  variants: Partial<ProductVariant>[];
  vendor: string;
  updatedAt: string;
  status: ProductStatus;
}

ProductStatus

Active
```
ACTIVE
```
Archived
```
ARCHIVED
```
Draft
```
DRAFT
```

enum ProductStatus {
  Active = 'ACTIVE',
  Archived = 'ARCHIVED',
  Draft = 'DRAFT',
}

ProductVariant

availableForSale
```
boolean
```
barcode
```
string | null
```
compareAtPrice
```
Money | null
```
createdAt
```
string
```
displayName
```
string
```

fulfillmentService

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

id
in GraphQL id format, ie 'gid://shopify/Product/1'
```
string
```
image
```
Image | null
```
inventoryItem
```
{ id: string; }
```
inventoryManagement
```
ProductVariantInventoryManagement
```
inventoryPolicy
```
ProductVariantInventoryPolicy
```
inventoryQuantity
```
number | null
```
position
```
number
```
price
```
Money
```
product
```
Partial<Product>
```
requiresShipping
```
boolean
```
selectedOptions
```
{ value?: string; }[]
```
sku
```
string | null
```
taxable
```
boolean
```
title
```
string
```
updatedAt
```
string
```
weight
```
number | null
```
weightUnit
```
WeightUnit
```

export interface ProductVariant extends Resource {
  availableForSale: boolean;
  barcode?: string | null;
  compareAtPrice?: Money | null;
  createdAt: string;
  displayName: string;
  fulfillmentService?: {
    id: string;
    inventoryManagement: boolean;
    productBased: boolean;
    serviceName: string;
    type: FulfillmentServiceType;
  };
  image?: Image | null;
  inventoryItem: {id: string};
  inventoryManagement: ProductVariantInventoryManagement;
  inventoryPolicy: ProductVariantInventoryPolicy;
  inventoryQuantity?: number | null;
  position: number;
  price: Money;
  product: Partial<Product>;
  requiresShipping: boolean;
  selectedOptions: {value?: string | null}[];
  sku?: string | null;
  taxable: boolean;
  title: string;
  weight?: number | null;
  weightUnit: WeightUnit;
  updatedAt: string;
}

Money

string

FulfillmentServiceType

GiftCard
```
GIFT_CARD
```
Manual
```
MANUAL
```
ThirdParty
```
THIRD_PARTY
```

enum FulfillmentServiceType {
  GiftCard = 'GIFT_CARD',
  Manual = 'MANUAL',
  ThirdParty = 'THIRD_PARTY',
}

ProductVariantInventoryManagement

Shopify
```
SHOPIFY
```
NotManaged
```
NOT_MANAGED
```
FulfillmentService
```
FULFILLMENT_SERVICE
```

enum ProductVariantInventoryManagement {
  Shopify = 'SHOPIFY',
  NotManaged = 'NOT_MANAGED',
  FulfillmentService = 'FULFILLMENT_SERVICE',
}

ProductVariantInventoryPolicy

Deny
```
DENY
```
Continue
```
CONTINUE
```

enum ProductVariantInventoryPolicy {
  Deny = 'DENY',
  Continue = 'CONTINUE',
}

WeightUnit

Kilograms
```
KILOGRAMS
```
Grams
```
GRAMS
```
Pounds
```
POUNDS
```
Ounces
```
OUNCES
```

enum WeightUnit {
  Kilograms = 'KILOGRAMS',
  Grams = 'GRAMS',
  Pounds = 'POUNDS',
  Ounces = 'OUNCES',
}

Examples

const selected = await shopify.resourcePicker({type: 'product'});

Preview

Examples

Product picker

Default

const selected = await shopify.resourcePicker({type: 'product'});

Alternate resources

Description

Alternate resources

Collection picker

const selected = await shopify.resourcePicker({type: 'collection'});

Product variant picker

const selected = await shopify.resourcePicker({type: 'variant'});

Product picker with preselected resources

Description

Preselected resources

Default

const selected = await shopify.resourcePicker({
  type: 'product',
  selectionIds: [
    {
      id: 'gid://shopify/Product/12345',
      variants: [
        {
          id: 'gid://shopify/ProductVariant/1',
        },
      ],
    },
    {
      id: 'gid://shopify/Product/67890',
    },
  ],
});

Product picker with action verb

Description

Action verb

Default

const selected = await shopify.resourcePicker({
  type: 'product',
  action: 'select',
});

Product picker with multiple selection

Description

Multiple selection

Unlimited selectable items

const selected = await shopify.resourcePicker({
  type: 'product',
  multiple: true,
});

Maximum selectable items

const selected = await shopify.resourcePicker({
  type: 'product',
  multiple: 5,
});

Product picker with filters

Description

Filters

Default

const selected = await shopify.resourcePicker({
  type: 'product',
  filter: {
    hidden: true,
    variants: false,
    draft: false,
    archived: false,
  },
});

Product picker with a custom filter query

Description

Filter query

Default

const selected = await shopify.resourcePicker({
  type: 'product',
  filter: {
    query: 'Sweater',
  },
});

Product picker using returned selection payload

Description

Selection

Default

const selected = await shopify.resourcePicker({type: 'product'});

if (selected) {
  console.log(selected);
} else {
  console.log('Picker was cancelled by the user');
}

Product picker with initial query provided

Description

Initial query

Default

const selected = await shopify.resourcePicker({
  type: 'product',
  query: 'Sweater',
});

Was this page helpful?