Template Files
Templates Directory
Custom Templates
Customize Stencil Checkout
Handlebars Syntax and Helpers
Handlebars.js
Handlebars Helpers
Stencil Object Model

Product Objects

Other Product Objects

Also see Common Objects > Common Product Card Model, which documents the product object returned in collections.

Product

Description: Default property that provides detailed product data. Called on the default <theme-name>/templates/pages/product.htmland <theme-name>/templates/pages/amp/product.html templates, and on several partials in the <theme-name>/templates/components/ subdirectory:

  • account/returns-list.html,
  • cart/item-options.html,
  • products/add-to-cart.html,
  • products/event-date.html,
  • products/modals/writeReview.html,
  • products/price.html,
  • products/product-view.html,
  • amp/products/product-options.html,
  • amp/products/product-view.html, and
  • amp/products/product-view-details.html.

Handlebars Expression: {{product}}

Object Properties:

Property Description
id Unique ID for the product
sku Default product variant when no options are selected
mpn Manufacturer Part Number
gtin Global Trade Item Number
url URL to the product detail page
upc Optional UPC code for the product
title Displayed name of the product
description (HTML) description of the product
detail_messages Status messages for display at the top of the product page
min_purchase_quantity Minimum quantity that can be purchased at once
max_purchase_quantity Maximum quantity that can be purchased at once
can_purchase Boolean that indicates whether the product is available for purchase
out_of_stock Boolean that indicates whether the product is out of stock
out_of_stock_message Merchant-defined label to display when a product is out of stock
cart_url URL to the customer’s shopping cart
add_to_wishlist_url URL to add the product to the customer’s wishlist
customizations
Product customizations (for example, a T-shirt size); these correspond to configurable fields and numeric-text product options in the BigCommerce control panel
id Customization ID
display_name Label for this customization, as displayed to customers
type Customization type [text|textarea|NumbersOnlyText|checkbox|select|file]
required Boolean value that indicates whether customer must specify this customization in order to buy the product
condition Boolean value indicating whether to display this product's condition (new, used, or refurbished)
prefill Optional string value to prefill this field
<values> For select type, array of strings listing the available options
<file_types> For file type, string representing the types of allowed files
<file_size> For file type, string representing the maximum file size allowed
integer_only For NumbersOnlyText type, boolean value indicating whether to restrict customer's entries to whole numbers only
default For NumbersOnlyText type, optional string representing a default number that customers can see and overwrite
limit_input For NumbersOnlyText type, boolean indicating whether to impose any limits on the numeric values that customers can enter as strings
limit_input_option For NumbersOnlyText type and limit_input = true, the type of limit: lowest or highest
lowest For NumbersOnlyText type and limit_input = true, minimum allowable value; a value of 0 imposes no limit
highest For NumbersOnlyText type and limit_input = true, maximum allowable value; a value of 0 imposes no limit
options Options for color and pattern swatches displayed for this product
id Product ID
type String indicating size, color, swatch, etc.
display_name Option Name displayed in control panel for this option
required Boolean value that indicates whether customer must specify this option in order to buy the product
condition Boolean value indicating whether to display this product's condition (new, used, or refurbished)
values Array of data (color) or image (pattern) values
label Internal label for this value (not normally displayed to shoppers)
id ID for this value, unique within this values array
selected Boolean indicating whether this value is preselected as the option's default value, upon page load
data Each values member can contain either a data or an image member; data denotes a color
Hex code for this color
image Each values member can contain either a data or an image member; image denotes a pattern, in Stencil image object format. (Note: This image value replaces the {{pattern}} property, which was limited to 18 x 18 pixels, and will be deprecated.)
price References the catalog price object, to access the product’s price
weight Weight of the default variant
height Height of the default variant
width Width of the default variant
depth Depth of the default variant
rating Rating for the product
num_reviews Number of reviews the product has
bulk_discount_rates List of discount rates for the current product
condition Condition of the product
stock_level Current stock level of the product; will be null if storefront stock display is disabled by the merchant, or if the product lacks inventory tracking
shipping Shipping properties for the product
fixed Boolean that indicates whether the product’s shipping price is fixed
price Price object that defines the shipping cost for this product (if shipping cost is fixed)
calculated Boolean that indicates whether the product’s shipping price is calculated at checkout
stock_label Shows whether the product stock level is for on-hand merchandise or pre-orders.
availability Optional availability message set by the merchant
pre_order Availability of the product for pre-order
release_date Release date, if the product is set to pre-order status
error_message Potential error on the page (e.g.: out of stock, form validations)
gift_wrapping Whether or not gift wrapping is enabled
brand Brand of the product
name Displayed name of the brand
url URL to the brand page
main_image Primary image to display when the product details page loads
images List of all images for this product, in Stencil image format (as configured in config.json; used with the {{getImage}} Handlebars helper)
pinterest_js Property to display Pinterest button
facebook_like Property to display Facebook Like button
warranty Optional warranty text set by the merchant
search_keywords Optional search keywords that merchants may enter in the control panel’s "Add a Product" or “Edit a Product” page, to characterize the product in meta tags and storefront searches
tags Keywords by which this product can also be identified
name Name of the tag
custom_fields Extra details to display about the product
name Custom field name
value Custom field value
event_date Property to handle a date-based product
name Name of the event
date_start Event’s start date range
date_end Event’s end date range
earliest_year Event’s starting year
latest_year Event’s ending year
type Type of event

Product Reviews

Description: A list of reviews related to this product. When filtering/limiting, reviews’ default sorting is by review id, from lowest to highest. (Called on the default <theme-name>/templates/pages/product.html<theme-name>/templates/components/ subdirectory:

  • products/product-view.html,
  • products/modals/writeReview.html, and
  • amp/products/product-view.html.)

Handlebars Expression: {{product.reviews}}

Object Properties:

Property Description
start The review that starts the current page of reviews
total Total number of reviews
end Last review on this page
show_review_email Boolean that indicates whether the Write Review form should have an input field for the reviewer’s e-mail address
captcha reCAPTCHA public key (for validating human versus bot visitors)
pagination References the pagination model
list List of reviews
rating Product’s rating (1–5 stars)
title Title of the review
date Date the product was reviewed
text Text content of the product review
name Name of the person providing the review

Related Products

Description: A list of products related to this product. (Called on the default <theme-name>/templates/components/products/tabs.html partial.)

Handlebars Expression: {{product.related_products}}

Object Properties: References the product card model.

Similar Products by Customer Views

Description: A list of products similar to a given product, based on customer’s product browsing history. (Called on the default <theme-name>/templates/components/products/tabs.html partial.)

Handlebars Expression: {{product.similar_by_views}}

Object Properties: References the product card model.

Product Videos

Description: A list of videos for a given product. (Called on the default <theme-name>/templates/pages/product.html template, and on the <theme-name>/templates/components/amp/products/product-view.html partial.)

Handlebars Expression: {{product.videos}}

Object Properties:

Property Description
id ID of the product video
title_short Short title of the product video
title_long Long title of the product video
description_long Long description of the product video
description_short Short description of the product video
length Duration of the product video

Compare

Description: Property to display an array of products on product comparison pages. (Called on the default <theme-name>/templates/pages/compare.html template.)

Handlebars Expression: {{comparisons}}

Object Properties: References the product card model, plus the additional fields listed here:

Property Description
availability How long this product usually takes to ship
brand Object containing brand data for this product
url Brand URL for this product
name Brand name for this product
remove_url URL to remove this product/column from the comparison
custom_fields Array of additional product details – size, color, book's ISBN, DVD's release date, etc. – as name/value pairs
name Displayed name for this custom field
value Value for this custom field’s entry

Download Item

Description: Property for digital (non-physical) products. (Called on the default <theme-name>/templates/pages/account/download-item.htmltemplate.)

Handlebars Expression: {{downloads}}

Object Properties:

Property Description
order_id ID for this order
product_name Name of the digital product
items Array of product components
name Name of this digital item
expired Boolean indicating whether customer’s access/subscription to this item has expired
days_remaining Number of days left in customer’s access/subscription to this item
downloads_remaining Number of times customer may download this item
size File size of this digital item (string, responsively formatted as: 240 KB, 1.1 MB, etc.)
description Description (if entered by merchant) for this item
id ID for this item
images List of all images for the product associated with this list of downloadable items (in Stencil image format)
thumbnail "Primary" image for the product associated with this list of downloadable items (in Stencil image format)

Product Other Details

Description: Property to display custom product details (such as a book’s ISBN code, a DVD’s release date, etc.). (Called on the default <theme-name>/templates/components/products/product-view.html and <theme-name>/templates/components/amp/products/product-view-details.html partials.)

Handlebars Expression: {{product.custom_fields}}

Object Properties:

Property Description
name Displayed name for this category of information
value Displayed value for this product’s entry