Skip to main content

Products and collections

A product represents an individual item for sale in a Shopify store. A collection represents a grouping of products that a shop owner can create to organize them or make their shops easier to browse.

This guide introduces the ways that you can configure products and collections using the GraphQL Storefront API.


You can use the Storefront API to complete the following tasks related to products and collections:

Tip

If you're new to the Storefront API, then you can get started by learning how to query products and collections.


You can use the Storefront API to filter products in a collection. This functionality lets you build a desired customer experience on a storefront, such as the ability to narrow down the search results that you display to customers.

For example, you might want to filter products in a collection based on product type, vendor, variant options, price, and whether the product is in stock.


You can retrieve metafields with the Storefront API to access additional information from different types of resources.

By default, the Storefront API can't read metafields. To expose specific metafields to the Storefront API, you need to use the GraphQL Admin API. For each metafield that you want to expose, you need to create a MetafieldStorefrontVisibility record.

Each MetafieldStorefrontVisibility record exposes all metafields that belong to the specified resource and have a specified namespace and key combination.

A product has two metafields: Metafield 1 and Metafield 2. Only Metafield 1 has a MetafieldStorefrontVisibility record. The Admin API can read both metafields, but the Storefront API can read only Metafield 1.

Anchor to Retrieving metafieldsRetrieving metafields

You can retrieve metafields on the following resources with the Storefront API:

ResourceDescription
ArticleAn article in an online store blog.
BlogAn online store blog.
CollectionA grouping of products.
CustomerA customer account with the store. Customer accounts store contact information for the customer, saving logged-in customers the trouble of having to provide it at every checkout.
OrderA customer's request to purchase one or more products from a store.
PageA page to hold static HTML content. Each Page object represents a custom page on the online store.
ProductAn individual item for sale in a Shopify store.
ProductVariantA different version of a product, such as differing sizes or differing colors.
ShopA collection of the general settings and information about a store.

After you've exposed metafields with the GraphQL Admin API, and retrieved them with the Storefront API, you can hide metafields from the Storefront API again if you no longer need to access them. For example, you could hide all product metafields that have namespace testapp and the key pizza-size-inches from the Storefront API.


You can display a product's availability for local pickup using the following API components:

  • storeAvailability: An object that represents a product variant's availability for in-store pickup at a location, including the estimated amount of time that it takes for the pickup to be ready. StoreAvailability is a connection field on the ProductVariant object.
  • Location: An object that represents a physical location, including the location's name, address, and latitude and longitude coordinates.
  • @inContext: A directive that provides the ability to contextualize the response. For example, the @inContext directive accepts a preferredLocationId argument which effects how in-store availability results are sorted.

The following screenshot provides an example of a local pickup option displayed on a custom storefront:

An example of a local pickup option displayed on a custom storefront

Anchor to Subscription productsSubscription products

You can use the Storefront API to retrieve subscription products on a storefront. Subscription products can be accessed from the sellingPlan object.

Selling plans represent how products and variants can be sold and purchased. A selling plan group contains selling plans and represents a selling method. For example, "Subscribe and save" is a selling method where customers pay for goods or services per delivery.

When a customer makes a purchase on a storefront, they're buying a variant. Each variant is associated with a price. The variant's price can be adjusted based on an applied fixed or percentage discount, and whether it's purchased with a selling plan.

A selling plan allocation associates a variant with a selling plan. Selling plan allocations describe which selling plans are available for each variant, and what their impact is on pricing.

The following diagram shows the relationships between a selling plan group, products, variants, and selling plans:

A diagram showing the relationships between a selling plan group, products, variants, and selling plans

Get familiar with the Storefront API by exploring guides that cover common use cases, and the complete reference for the GraphQL Storefront API.



Was this page helpful?