Common Objects

Certain Stencil objects can be accessed through multiple other Stencil objects. For example, the image object is exposed through the Category, Product, Product Options, and other objects. Its structure is consistent for all objects/properties that access it.

This consistent behavior is true for each of the common objects documented in the following subsection.

Debugging Your Theme

The Stencil framework provides built-in debugging tools to aid in your custom front-end development. When you want to see what data is available on the page you are working on, you can simply add the debug query string to your store’s localhost URL. Here is an example:

http://localhost:3000/product/this-is-a-sample-product?debug=context This will return a list of all the objects available on the page, in JSON syntax. If you want to view the available JSON objects and rendered page at the same time, simply change the debug value to bar. Below is an example:

http://localhost:3000/product/this-is-a-sample-product?debug=bar

Catalog Price

Description: Exposes catalog price and currency-related properties in both raw numeric, and formatted string, formats. Tax settings display configuration will determine which properties are available.

Available through:

Object Properties:

Property Description Type
with_tax Price including tax object
↳ currency Currency code string
"USD"
↳ formatted String representation of the above price, including currency formatting string
"$216.50"
↳ value Raw numeric value of the above price number
216.5
without_tax Price excluding tax object
↳ currency Currency code string
"USD"
↳ formatted String representation of the above price, including currency formatting string
"$200.00"
↳ value Raw numeric value of the above price number
200
non_sale_price_with_tax Non-sale price, including tax (can be displayed alongside standard with_tax during sale events) object
↳ currency Currency code string
"USD"
↳ formatted String representation of the above price, including currency formatting string
"$243.56"
↳ value Raw numeric value of the above price number
243.56
non_sale_price_without_tax Non-sale price, excluding tax (can be displayed alongside standard without_tax during sale events) object
↳ currency Currency code string
"USD"
↳ formatted String representation of the above price, including currency formatting string
"$225.00"
↳ value Raw numeric value of the above price number
225.00
rrp_with_tax List (i.e., manufacturer’s suggested retail) price, including tax object
↳ currency Currency code string
"USD"
↳ formatted String representation of the above price, including currency formatting string
"$242.48"
↳ value Raw numeric value of the above price number
242.48
rrp_without_tax List (i.e., suggested retail) price, excluding tax object
↳ currency Currency code string
"USD"
↳ formatted String representation of the above price, including currency formatting string
"$224.00"
↳ value Raw numeric value of the above price number
224
saved Amount customer saved, compared to list price object
↳ currency Currency code string
"USD"
↳ formatted String representation of the above price, including currency formatting string
"$25.98"
↳ value Raw numeric value of the above price number
25.98
tax_label Tax label (VAT, sales tax, etc.) displayed to customers. string
"Tax"
price_range See Price Range Object

Price

Description: Exposes price- and currency-related properties in both raw numeric, and formatted string, formats.

Available through:

Object Properties:

Property Description
currency Currency code
formatted String representation of the price, including currency formatting
value Raw numeric value of the price

Price Range

Description: For products with several variants with different prices, a price range is available which exposes the minimum and maximum variant price.

Object Properties:

Property Description Type
retail_price_range Product Price Range object
↳ max The minimum variant price for the product object
    ↳ with_tax Price including tax object
        ↳ currency Currency code string
"USD"
        ↳formatted String representation of the above price, including currency formatting string
"$37.89"
        ↳ value Raw numeric value of the above price number
37.89
    ↳ without_tax Price without tax object
        ↳ currency Currency price is displayed in string
USD
        ↳ formatted String representation of the above price, including currency formatting string
"$35.00"
        ↳ value Raw numeric value of the above price number
35
↳ min The minimum variant price for the product object
    ↳ with_tax Price including tax object
       ↳currency Currency code string
"USD"
        ↳formatted String representation of the above price, including currency formatting string
"$37.89"
        ↳ value Raw numeric value of the above price number
37.89
    ↳ without_tax Price without tax object
        ↳ currency Currency price is displayed in string
"USD"
        ↳ formatted String representation of the above price, including currency formatting string
"$35.00"
        ↳ value Raw numeric value of the above price number
35

Available through:

Object/Property:{{product.price}


Stencil Image

Description: Exposes a URL and an “alt” string for images used in the Stencil framework

Object Properties:

Property Description
data Internal URL to product or category image
alt Corresponding text to display for missing images, accessible screen readers, etc.

Available through:

Stencil Handlebars Helper: {{getImage}}

Common Object: Common Product Card Model

Object/Property: {{category.image}}

Arrays/Elements: {{product.options.image}}, {{product.images}}, {{downloads.items.images}}, {{downloads.items.thumbnail}}, {{category.subcategories.image}}, {{order.items.image}}, {{customer.orders.image}}, {{brands.image}}, {{order.items.shipping_rows.image}}

Usage Example:

{{getImage image "thumbnail"}}


Common Product Card Model

Description: A model for a product’s basic, primary properties. Typically used for list components that show multiple products, each in its own “card” or panel.

Object Properties:

Property Description Format
id ID of the product integer
sku The product’s SKU (stock keeping unit)/product code, as a string; if the SKU field is not populated, then null string or null
name Name of the product string
url URL to product detail page for the product string
availability Typical shipping time for the product; used to populate “Usually ships within…” fields string
rating Product’s rating number
brand Brand properties for the product (includes the name property) object
↳ name Name of the brand string
↳ url URL of the brand string
add_to_cart_url URL that adds this product to customer’s cart string
category Categories the product belongs to. array
price References the catalog price object, to access price properties in both raw-numeric and formatted/string formats object
summary Summary description of the product string
image Default image for the product, in Stencil image format object
images Array of a product’s images, in Stencil image format; currently limited to 5 images array object
date_added Date the product was added to this BigCommerce storefront string Ex. "Aug 15th 2018"
pre_order Product’s availability for pre-order boolean
show_cart_action Indicates whether the product is available for purchase boolean
has_options Indicates whether customer is required to specify options when ordering the product Boolean
stock_level If inventory tracking is turned on: The number of items available for sale (0 or more). If inventory tracking is turned off: A “null” string. number or null
low_stock_level If inventory tracking is turned on: Sets a threshold low-stock level. You can use conditional logic to display a “limited availability” badge if the stock_levelproperty’s value falls below this threshold. If inventory tracking is turned off: A “null” string. number or “null”
qty_in_cart Quantity of this item in the customer’s cart number
custom_fields Array of custom fields for this product; custom fields can be used for purposes like: alternate brand name, merchandising title for the product, product type, “gift idea” indicator, etc. array
↳ id Unique (integer) identifier for this custom field integer
↳ name Name of this custom field string
↳ value Value for this custom field string
num_reviews Number of product reviews number
weight Weight of the product object
↳ formatted String representation of weight on storefront string
↳ value Numerical value of weight number
out_of_stock_message Text to display when the product is out of stock. If no message is configured, returns false. string or false
release_date Release date, if the product is set to pre-order status string Ex. Available: Aug 6th 2019

Available through:

Object: {{comparisons}}

Arrays/Elements: {{product.related_products}}, {{product.similar_by_views}}, {{category.products}}, {{cart.suggested_products}}, {{customer.recently_viewed_products}}