Skip to content

Product Types

TypeScript types of products, variants, tags, product options, media, downloadable files and reviews.

The types of this page describe what the product listing and the product page return. The Store API Catalog guide lists every attribute and include, and the SDK Catalog page shows the methods that return them.

Product

Product is a product of the catalog, returned by GET /store/products and GET /store/products/{slug}, and embedded in categories, brands, collections and tags with include=products. The Store API leaves out an attribute that does not apply to the product type or needs an include, so most fields are optional. prices, price_range and calculated_price are in cents. calculated_price and quantity_rule are set on products without variants; a variant product carries them on each variant. rating and reviews_count come with include=rating, and options with include=options. The Product Resource describes each attribute. This is the definition:

interface Product extends Entity, SEOFields, ShippingFields {
  name: string
  slug: string
  sku?: string | null
  barcode: string | null
  summary: string | null
  description: string | null
  security_stock: number | null
  featured: boolean
  is_visible: boolean
  allow_backorder: boolean
  type: ProductType | null
  published_at: string | null
  external_id: string | null
  stock?: number
  in_stock?: boolean
  supplier_id?: ResourceId | null
  brand_id: ResourceId | null
  metadata: Metadata
  supplier?: Supplier
  brand?: Brand
  channels?: Channel[]
  categories?: Category[]
  options?: ProductOption[]
  collections?: Collection[]
  tags?: ProductTag[]
  variants?: ProductVariant[]
  relatedProducts?: Product[]
  images?: Media[] | null
  thumbnail?: Media | null
  files?: ProductFile[] | null
  reviews?: Review[]
  rating?: number | null
  reviews_count?: number
  prices?: Price[]
  price_range?: PriceRange | null
  calculated_price?: CalculatedPrice | null
  quantity_rule?: QuantityRule | null
}

ProductType

ProductType is the type of a product: a standard product holds its own price and stock, a variant product sells its variants, a virtual product skips shipping and can carry downloadable files, and an external product comes from a supplier, identified by external_id. The Store API refuses to add a variant or an external product itself to a cart. See How Products Work. This is the definition:

enum ProductType {
  EXTERNAL = 'external',
  VIRTUAL = 'virtual',
  STANDARD = 'standard',
  VARIANT = 'variant',
}

ProductOption

ProductOption is an attribute the merchant set on a product, such as its sizes or its material, with only the values the product uses. Products carry them as options with include=options, as described in Options. custom_value holds the free text of a text option. This is the definition:

interface ProductOption {
  name: string
  slug: string
  description: string | null
  type: FieldType
  icon: string | null
  custom_value: string | null
  values: ProductOptionValue[]
}

ProductOptionValue

ProductOptionValue is one value of a product option. key is the stored value, a hex code for a color, and value the label to show; both work in filter[option] of the product listing. swatch_url is the swatch image set for this product and value. This is the definition:

interface ProductOptionValue {
  value: string
  key: string
  position: number
  swatch_url: string | null
}

ProductVariant

ProductVariant is one variant of a variant product, such as a size and color combination, returned in included with include=variants, and as the purchasable of a cart line. stock and in_stock give its availability; calculated_price and quantity_rule are set on the product page only, so a listing reads the price of a variant from its prices. The prices are in cents. This is the definition:

interface ProductVariant extends Entity, ShippingFields {
  name: string
  sku?: string | null
  barcode: string | null
  ean: string | null
  upc: string | null
  position: number
  allow_backorder: boolean
  product_id: ResourceId
  stock?: number
  in_stock?: boolean
  metadata: Metadata
  product?: Product
  values?: VariantOptionValue[]
  images?: Media[] | null
  thumbnail?: Media | null
  prices?: Price[]
  calculated_price?: CalculatedPrice | null
  quantity_rule?: QuantityRule | null
}

VariantOptionValue

VariantOptionValue is one option value a variant is built from, such as Color = Black, in the variant's values. The variant picker matches the visitor's choices against these values: key is the stored value (a hex code for a color) and value the label to show. This is the definition:

interface VariantOptionValue {
  value: string
  key: string
  attribute: string
  attribute_slug: string
}

ProductTag

ProductTag is a tag of products, returned by GET /store/tags and by the tags include of a product. See Tags. This is the definition:

interface ProductTag extends Entity {
  name: string
  slug: string | null
  products?: Product[]
}

Media

Media is an image, such as the images and thumbnail of a product, a variant, a category, a brand or a collection, or the logo of a carrier. url is the original file. conversions holds the resized images, keyed by conversion name (large and medium by default); a conversion added after the upload is missing until the media is regenerated, so fall back to url. The Media page covers conversions. This is the definition:

interface Media {
  id: ResourceId
  url: string
  conversions?: Record<string, string>
  name?: string | null
  extension?: string | null
  created_at?: string
  updated_at?: string
}

ProductFile

ProductFile is a downloadable file of a virtual product, in the files of the product and of the order item that bought it. size is in bytes. It never carries a URL: the customer who paid for the order requests a temporary link, as described in Downloading Purchased Files. This is the definition:

interface ProductFile {
  id: ResourceId
  name: string
  extension: string
  size: number
}

Review

Review is an approved review of a product, returned by GET /store/products/{slug}/reviews and GET /store/reviews. rating goes from 1 to 5, and author is null when the account of the reviewer no longer exists. See Reviews. This is the definition:

interface Review extends Entity {
  title: string | null
  content: string | null
  rating: number
  is_recommended: boolean
  author: ReviewAuthor | null
}

ReviewAuthor

ReviewAuthor is the reviewer shown next to a review. name is the first name and the initial of the last name. avatar is the URL of the uploaded avatar, or null, in which case the storefront builds its own fallback from name. This is the definition:

interface ReviewAuthor {
  name: string | null
  avatar: string | null
}

ReviewAggregates

ReviewAggregates is the meta of GET /store/products/{slug}/reviews, computed over the approved reviews. average_rating is rounded to one decimal, or null without reviews, and rating_distribution counts the reviews of each rating from 1 to 5. See Reviews of a Product. This is the definition:

interface ReviewAggregates {
  reviews_count: number
  average_rating: number | null
  rating_distribution: Record<number, number>
}

Last updated on

Edit on GitHub