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.

How it works

Anchor link to section titled "How it works"

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

Filter products in a collection
Retrieve metafields from different resources
Support local pickup on storefronts
Manage subscription products on storefronts

Product filtering

Anchor link to section titled "Product filtering"

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.

Metafields

Anchor link to section titled "Metafields"

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.

Retrieving metafields

Anchor link to section titled "Retrieving metafields"

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

Resource	Description
Article	An article in an online store blog.
Blog	An online store blog.
Collection	A grouping of products.
Customer	A 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.
Order	A customer's request to purchase one or more products from a store.
Page	A page to hold static HTML content. Each `Page` object represents a custom page on the online store.
Product	An individual item for sale in a Shopify store.
ProductVariant	A different version of a product, such as differing sizes or differing colors.
Shop	A collection of the general settings and information about a store.

Hiding metafields

Anchor link to section titled "Hiding metafields"

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.

Local pickup

Anchor link to section titled "Local pickup"

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:

Subscription products

Anchor link to section titled "Subscription 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: