main_image properties
alt
data
Stencil theme object schemas describe the data available to Handlebars templates on BigCommerce storefronts. The context any template can render is the union of two sets:
templates/pages/*.html file.If an object is not listed in either set below, it is not in context on that page.
When running stencil start locally, append ?debug=context to any storefront URL to dump the full context object as JSON. Use ?debug=bar to see the rendered page and the JSON side-by-side. This is the fastest way to confirm what’s actually in scope for any given route — including whether {{customer}} is present.
Available on every Handlebars template. No frontmatter declaration required.
In addition to the globals above, each templates/pages/*.html file in the table below receives the listed page-specific objects.
Routes that are not in the table — for example templates/pages/auth/login.html, templates/pages/errors.html, templates/pages/account/orders.html — have no documented page-specific context beyond the globals above. Some account-related templates also receive {{customer}}; see the callout under the table for the documented surface, and use ?debug=context to confirm for any specific route.
{{customer}} on account-related templates
{{customer}} is documented as available to templates and components with customer context, including contact-form pages and partials under account/ (for example account/address-list.html, account/messages-form.html, account/wishlist-list.html) and common/subscription-form.html. Coverage for other templates/pages/account/* routes is not formally documented — use ?debug=context (above) to confirm {{customer}} is present on the specific route you’re working on, and access nested data via {{customer.orders}}, {{customer.addresses}}, etc.
Elements of marketing banners at the page’s top and bottom.
Scope: global
Handlebars expressions:
{{banners}}{{{banners}}}Handlebars formatting exception: where a banner contains HTML, the banner helper must be placed in triple braces ({{{banners}}}). Double braces would escape the HTML.
{{banners}} returns only the first 50 banners on each page.
Properties:
Array of HTML content/strings, for custom bottom-banner content; banners are populated from the BigCommerce control panel
Array of HTML content/strings, for custom top-banner content; banners are populated from the BigCommerce control panel
Blog-specific properties for the blog feature within BigCommerce storefronts. Called on the default templates/components/blog/post.html partial.
Scope: global and template
Handlebars expression: {{blog}}
Available to blog and blog-post templates and components.
Properties:
Blog description.
Blog name.
The blog’s tag.
URL to the blog page.
Available on every page.
Properties:
Blog name.
URL to the blog page.
The brand object for the page calling the object.
Available on: templates/pages/brand.html
Handlebars expression: {{brand}}
Properties:
Boolean that defines whether product-filtering search is enabled for the store.
A list of all possible search filters for this brand.
Name of the brand
An array of product card models.
An array of selected facets.
Boolean corresponding to merchant’s control panel selection whether or not to enable product comparisons.
URL of the brand page. Only letters, numbers, dots (.), dashes (-), underscores (_), and forward slashes (/) are allowed. Must be 1-1024 characters, consisting of segments divided by ”/”. Each segment must be 1-256 characters.
Search result items for brand matches.
Available on: templates/pages/search.html
Handlebars expression: {{brand_results}}
Properties:
All brands available on the storefront.
Available on: templates/pages/brands.html
Handlebars expression: {{brands}}
Breadcrumb trail for the current page. Available on virtually all pages that have a breadcrumb trail.
Scope: global
Handlebars expression: {{breadcrumbs}}
A list of images, text, and style assets for a storefront’s image slideshow.
Available on: templates/pages/home.html
Handlebars expression: {{carousel}}
Properties:
Object containing properties for each slide in the slideshow.
Alt text for the image.
Text displayed on a call-to-action button defined by the merchant.
Color of the button.
Heading message defined by the merchant.
Color of the heading text.
Path to the image file used on this slide.
Subheading defined by the merchant.
Color of the subheading text
URL to which the image will link.
Indicates how often (in seconds) the slides will change; the value must be between 1 and 90,000 seconds.
Cart-specific properties for the current session. Contains cart_id if one exists.
Available on: templates/pages/cart.html
Handlebars expression: {{cart}}
Properties:
Generates checkout buttons for third-party payments (PayPal, Google Checkout, etc.)
List of coupons applied to the cart; default sorting is by coupon ID, from lowest to highest.
Discount being applied to the cart in the current session.
List of gift certificates applied to the cart.
Price object that defines the cost associated with adding gift wrapping to the items in the cart.
Price object that defines the total cost of all the items in the cart. Incorporates estimated shipping, discounts, taxes, and gift wrapping.
Unique ID of the coupon.
Corresponding text to display for missing images, accessible screen readers, etc.
Internal URL to the image.
Total number of items in the cart.
URL to remove gift certificate from the cart.
Price object that defines the cart item’s list price (MSRP); can be used to display struck-out list prices.
Boolean indicating whether the wrapping options are shown.
Current configuration of the shipping estimator for this session’s current cart; will be null/undefined if the cart contains no physical products.
Countries available to ship to.
The city/town that the customer selected for the shipping estimate.
The state/province/region that the customer selected for the shipping estimate.
The ZIP/postal code that the customer selected for the shipping estimate.
Boolean indicating whether the merchant wants to show the shipping estimator to customers.
List of states/provinces/regions for the country.
Boolean: If > 1 physical items are in the cart, and checkout button is displayed: whether to also display the “Ship to multiple addresses” / “Multiple Shipping Addresses” user option.
Boolean that determines whether to show a checkout button.
Price object that defines the total cost of all the items in the cart. Might or might not include tax, based on the tax display settings the merchant has configured. Excludes shipping, discounts, and gift wrapping.
List of all applicable taxes for the cart.
Price object that defines the cost of the applied tax.
Boolean that indicates whether taxes are included in the total price for the cart’s contents.
Returns the cart ID if one exists. To return more cart information, use the Storefront Cart API.
Scope: global
Handlebars expression: {{cart_id}}
All categories shown in the current page context. Default sorting is by category ID, from lowest to highest.
Scope: global
Handlebars expression: {{categories}}
The category object for the page calling the object. When retrieving a collection of categories, default sorting is by category ID, from lowest to highest.
Available on: templates/pages/category.html, plus several partials in <theme-name>/templates/components/: category/shop-by-price.html and category/sidebar.html.
Handlebars expression: {{category}}
Properties:
Merchant-defined description of the category.
Message displayed when a product is out of stock, and inventory settings are configured to redirect to a category: “Sorry, the product you tried to view is currently out of stock, here are some similar products we have available.” (This phrasing is set by the BigCommerce App.)
Boolean that defines whether product-filtering search is enabled for the store.
Available search facets.
Unique ID for the category.
Merchant-defined category name.
Selected search facets.
Exposes price- and currency-related properties in both raw numeric, and formatted string, formats. It will return empty for stores with faceted search enabled who are not explicitly requesting this information in their front matter.
Price object that defines the maximum price boundary.
Price object that defines the minimum price boundary
Price object that defines the currently selected price range.
URL of price-filtered product results for this category.
Boolean that defines whether to show controls for product comparison
List of any child categories.
Merchant-defined description of the subcategory.
Unique ID for the subcategory.
Image representing this subcategory, in Stencil image format.
Name of the subcategory
Number of products in the subcategory. (Counts at the current level only – not recursive to deeper levels.)
URL to the subcategory.
Count of the number of products in the category.
Search result items for category matches.
Available on: templates/pages/search.html
Handlebars expression: {{category_results}}
Properties:
Used to access checkout content and data on templates/pages/order-confirmation.html. Available to checkout and order-confirmation templates and components.
Handlebars expression: {{checkout.*}}
Properties:
Default content from checkout template.
Default content from checkout <head>.
{{checkout.order}} object available to order confirmation templates and components.
The id of the order. To access checkout.order.id from order-confirmation.html, use Script Manager or the Stencil themeʼs page context to assign the value of checkout.order.id to a variable. For more information, see the example in Using the Fetch API.
The image src of the header.
the cart and checkout id
Property to display an array of products on product comparison pages.
Available on: <theme-name>/templates/pages/compare.html
Handlebars expression: {{comparisons}}
Search result items for content (page) matches.
Available on: templates/pages/search.html
Handlebars expression: {{content_results}}
List of countries used in country and state dropdowns when submitting the add payment form.
Available on: templates/pages/account/payment-methods.html
Handlebars expression: {{countries}}
Object to enable the current customer to create a store account.
Available on: <theme-name>/templates/pages/auth/create-account.html
Handlebars expression: {{forms.create_account}}
Properties:
A list of all supported currencies, and the currency currently active in the storefront.
Scope: global
Handlebars expression: {{currency_selector}}
Properties:
ID of the currency actively in use in the storefront.
Country flag used to represent the active currency.
Name of the active currency.
Code for the active currency.
List of all the currencies supported for this storefront.
Boolean that indicates whether this currency is active for use in the storefront
The URL to invoke a switch to this currency.
ID of the currency.
Name of the currency.
Country flag used to visually represent the currency.
Customer information for the active session.
Available on: templates and components with customer context, including page/contact-us-form.html, common/subscription-form.html, account/address-list.html, account/messages-form.html, and account/wishlist-list.html.
Handlebars expression: {{customer}}
Properties:
ID of this customer’s group.
Name of this customer’s group.
Customer’s email address.
Customer’s ID.
Customer’s name.
Number of unread messages for this customer.
Number of wishlists for this customer.
Customer’s phone number.
Shipping address used for the order.
Customer’s shipping address, first line.
Customer’s shipping address, second line.
Customer’s shipping city.
Customer’s shipping company name.
Customer’s shipping country.
ID for customer’s shipping country.
Type of delivery destination: residential or business/commercial.
Customer’s shipping (first) name.
Used for custom shipping forms.
Unique, system-generated ID.
Customer’s shipping (last) name.
Timestamp when this address was last used as a shipping address.
Customer’s shipping phone number.
Customer’s shipping state.
ID for customer’s shipping state/province/region.
Customer’s shipping postal code.
Customer’s store credit.
ID of the current customer’s group.
Scope: global
Handlebars expression: {{customer_group_id}}
Name of the current customer’s group.
Scope: global
Handlebars expression: {{customer_group_name}}
Property for digital (non-physical) products.
Available on: <theme-name>/templates/pages/account/download-item.html
Handlebars expression: {{downloads}}
Data for searching by category or brand.
Scope: global
Handlebars expression: {{faceted_search}}
Properties:
List of all search facets available.
Container for the selected search facets (selected facets contain properties below)
URL to remove all selected search restrictions.
Currently enabled search facets
Footer content for each storefront page.
Scope: global
Handlebars expression: {{footer}}
Properties:
The URL to the sitemap, based on store’s SEO setting.
Scripts to be loaded after the HTML has loaded; includes performance metrics.
Form-related context available on pages and components that include forms.
Handlebars expression: {{forms.edit_account}}
Contact form fields and configuration.
Handlebars expression: {{forms.contact}}
Properties:
Data configured for the HTML <head> element.
Scope: global
Handlebars expression: {{head}}
Properties:
The store’s favicon.
Meta tags to improve store SEO.
Scripts to be loaded in the <head> tag.
CSS files to be included.
Current page’s title.
Returns true if the current request is an AJAX request.
Scope: global
Handlebars expression: {{is_ajax}}
No properties available for this object.
Order details, for templates and components with order context.
Handlebars expression: {{order}}
Properties:
Billing address used for the order.
Customer’s billing address
Customer’s billing city
Customer’s billing company name
Customer billing country
Customer’s billing email
Customer’s billing name
Customer billing phone number
Customer’s billing state
Customer billing ZIP
Date of the order
Unique, system-generated ID
Boolean indicating that the order has been completed
List of items for the order.
Product Name
Product ID
Quantity Ordered
Price object that defines the value of this product that has been refunded.
An error message to be displayed when the customer attempts to reorder items that can’t be reordered.
Array of shipping addresses, for each item in the order
Boolean indicating whether the customer should see a button for reordering items on the Account Order Details page.
Price object that defines the order’s total value
Customer’s payment method for this order (payment gateway)
URL to place reorders for items in this order.
Boolean that indicates whether merchant allows products from the order to be returned.
Shipping address used for the order.
Customer’s shipping address
Customer’s shipping city
Customer’s shipping company name
Customer’s shipping country
Customer’s email
Customer’s shipping name
Customer’s shipping phone number
Customer’s shipping state
Customer’s shipping zip
Number of shipping addresses the customer has specified for this order.
Order status code
Status message associated with the status code for the order
Status text associated with the status code for the order.
Price object that defines the order’s total value
A list of “total” rows containing total pricing information
The label of the total row (Subtotal, Tax, Grand Total, etc.).
Value that customer selected for the option.
Page details, present on content pages and forms.
Handlebars expression: {{page}}
Properties:
Present if page has ancestors.
HTML content of the page
Array of child pages
Title of this child page
A string representing the type of page currently displayed.
Scope: global
Handlebars expression: {{page_type}}
All possible values for {{page_type}} are:
account_orderstatusaccount_orderaccount_addressbookshippingaddressformaccount_new_returnadd-wishlistaccount_recentitemsaccount_downloaditemeditaccountaccount_inboxaccount_saved_returnaccount_returnsaccount_paymentmethodsaccount_addpaymentmethodaccount_editpaymentmethodlogincreateaccount_thankscreateaccountgetnewpasswordforgotpasswordblogblog_postbrandbrandscartcheckoutcategory *comparepage_contact_formerror404giftcertificatesgiftcertificates_balancegiftcertificates_redeemdefault *orderconfirmationpage *product *amp_product_optionssearchsitemapnewsletter_subscribewishlistwishlistsThe four most-commonly-used values for {{page_type}} are marked with asterisks.
Storefront content page data.
Scope: global
Handlebars expression: {{pages}}
Properties:
URL of the page.
List of child pages for this page.
URL of the child page.
Name of the child page.
Name of the page.
Pagination context for templates containing paginated lists.
Available on: templates such as templates/pages/category.html and templates/pages/brands.html.
Handlebars expression: {{pagination}}
Reserved property. No documented schema.
Default property that provides detailed product data.
Available on: templates/pages/product.html, plus several partials in templates/components/:
account/returns-list.htmlcart/item-options.htmlproducts/add-to-cart.htmlproducts/event-date.htmlproducts/modals/writeReview.htmlproducts/price.htmlproducts/product-view.htmlHandlebars expression: {{product}}
Properties:
URL to add the product to the customer’s wishlist
The company, product line, or trademark associated with the product.
The name of the company, product line, or trademark.
The store’s internal page with all the products from that brand.
List of discount rates for the current product
Boolean that indicates whether the product is available for purchase
URL to the customer’s shopping cart
Product condition
Product customizations (for example, a T-shirt size); these correspond to configurable fields and numeric-text product options in the BigCommerce control panel
The product’s physical depth measurement.
(HTML) description of the product
Status messages for display at the top of the product page
Whether or not gift wrapping is enabled
Global Trade Item Number. An identifier for trade items that is incorporated into several product identification standards, such as ISBN, UPC, and EAN.
The product’s physical height measurement.
Unique ID for the product
List of all images for this product, in Stencil image format (as configured in config.json; used with the getImage Handlebars helper)
Primary image to display when the product details page loads
Maximum quantity that can be purchased at once
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.
Minimum quantity that can be purchased at once
Manufacturer Part Number. It is used to reference and identify a product.
Number of reviews the product has
Boolean that indicates whether the product is out of stock. Out of stock only applies to the default selection on page load. For example, if Product A is out of the “Small” size, but “Small” is selected by default, out_of_stock will return true, even if the product is not out of stock as a whole.
Out of stock messages for display on the product page
Rating for the product
Default product variant when no options are selected.
Indicates the number of items available for sale. Visible only when inventory tracking is turned on.
Keywords by which this product can also be identified.
Displayed name of the product
Optional UPC code for the product
URL to the product detail page
Optional warranty text set by the merchant
The product’s physical width measurement.
Search result items for product matches.
Available on: templates/pages/search.html
Handlebars expression: {{product_results}}
Properties:
false
true
true
12.00 Ounces
false
Product cards grouped by new, featured, and top_sellers.
Available on: templates/pages/home.html
Handlebars expression: {{products}}
Properties:
Renders a list of all the featured products for the BigCommerce storefront.
Object to display a sidebar of top-selling products.
Empty array. No properties are available for this object.
Handlebars expression: {{remote_api_scripts}}
Common settings shared across every BigCommerce storefront.
Scope: global
Handlebars expression: {{settings}}
Properties:
Site-wide boolean value that indicates whether to allow customers to create accounts.
Object that defines links for the AddThis social sharing component.
Array of buttons to display for AddThis social sharing {{#each settings.add_this.buttons}}{{service}}{{/each}} {{#each settings.add_this.buttons}}{{annotations}}{{/each}}.
String containing HTML attributes associated with this button.
String containing the name of this buttonʼs social-media service (facebook, email, print, twitter, linkedin, google, etc.)
Store’s complete physical address, as entered by merchant in the store profile.
The normal shop URL.
Site-wide boolean value that indicates whether the blog is visible for this storefront.
Boolean that return true if bulk discount is enabled on products.
The IP address of the customer browsing the storefront. An alternative to this deprecated field is using ipify API.
The country code corresponding to the IP.
Site-wide boolean that indicates whether GAEE is enabled in a theme. For {{settings.data_tag_enabled}} to be true, the enhanced_ecommerce key must be present in config.json and a GAEE experiment must be enabled along with GA property value set in Advanced Settings > Analytics > GA in the store control panel.
Brief display format/pattern for dates, as configured in the control panelʼs Display Date Format field.
Extended display format/pattern for dates, as configured in the control panelʼs Extended Display Date Format field.
Site-wide boolean value that indicates whether to enable the gift certificate system for this store.
A boolean value. Return true if the shopper’s IP address is in the EU. Alternatives to this deprecated field are solutions like the IP Geolocation API, IP Geolocation API Package, and others. While those solutions are not free, they offer a generous free tier, better data quality, and more data points than just the region.
Object that manages information about the store when in maintenance (offline) mode.
If store is in maintenance mode, string containing header text for the Down for Maintenance window displayed to visitors; otherwise, null.
If store is in maintenance mode, string containing merchant-customizable body text (and optionally, HTML) for the Down for Maintenance window displayed to visitors; otherwise, null.
If store is in maintenance mode, one of three strings identifying the storeʼs status, and generating a corresponding text notice to merchants about how to proceed: AdminPrelaunchNotice for preview stores, AdminMaintenanceNotice for active stores taken down for maintenance, or AdminHibernationModeNotice for deactivated stores; otherwise, null.
Collection of units-of-measure definitions, to be used when displaying product details:
Units of measure for product length
Units of measure for product weight
List of child items that define the store’s default currency formatting.
Whether currency symbol appears at left or right of the quantity
Symbol for the currency
Number of decimal places to display
Symbol for decimal separator
Symbol for thousands separator
Returns the newsletter summary.
Collection of properties representing BigCommerce requirements for customer-account passwords:
Regular expression representing required/acceptable alphabetic characters.
String that passes a standard error message for noncompliant password.
Integer representing minimum acceptable password length.
Regular expression representing required/acceptable numeric characters.
Exposes the BigCommerce payments URL: https://payments.bigcommerce.com.
The contact phone number for the store located in the stores profile.
If enabled, a string containing merchant-customizable text for (European Union–required) cookie-setting notification; if disabled, a boolean with a value of false.
The ISO-3166-2 code is an international standard denomination for country subdivisions. The first part is the country’s ISO 3166-1 alpha-2 code, and the second part is a string of up to three alphanumeric characters representing the country’s subdivision (province or state). For example, Texas’s ISO 3166-2 code is US-TX; therefore, the region code is TX. The value is approximate as it is based on the IP address geolocation. Alternatives to this deprecated field are solutions like https://ipinfo.io/products/ip-geolocation-api and others. While those solutions are not free, they offer a generous free tier, better data quality, and more data points than just the region.
Object that contains details about the HTTP request.
The absolute URL requested. Never use request.path in the actual body of the page.
Hostname of the request.
The browserʼs locale. Allows for varying experience based on shopper locale.
Origin of the request.
The referer.
User agent string of the request. An alternative is using JavaScript detection (Navigator: userAgent property).
Boolean that indicates whether the control-panel setting for the returns system is enabled.
An integer that sets a limit on the number of RSS items to display.
The SSL-enabled, secure, shop URL.
Returns the SSL URL for the store (secure shop hostname). Example: https://your-store-domain.com.
Site-wide boolean value that indicates whether to display a mailing-list invite to visitors.
Returns a 1 if the newsletter summary is shown. Returns 0 if it is not shown. If show_newsletter_box is 0 then show_newsletter_summary will also be 0.
A boolean value. If true available payment methods on a store will be shown. If false they are hidden.
Site-wide boolean value that indicates whether to display product ratings (in numeric or star format) to visitors.
Site-wide boolean value that indicates whether to display full-text product reviews to visitors.
Site-wide boolean value that indicates whether to allow customers to create wishlists.
Whether or not this time zone observes Daylight Saving Time (boolean), as set by the control panelʼs Enable DST Correction check box.
Returns the store hash as a string.
The store’s logo.
Title for the logo. Configure the text in the control panel under Storefront Design Design Options Logo.
Name of the BigCommerce store.
Storeʼs time zone, as selected in the control panelʼs Your Timezone dropdown list.
Defines the Tax Label (VAT, Sales Tax, etc.) that a merchant can set in the control panel’s Settings > Tax page for display to customers.
Shipment details for an order.
Available on: templates/pages/account/orders/details.html
Handlebars expression: {{shipments}}
Shipping notice messages.
Available on: templates/pages/home.html
Handlebars expression: {{shipping_messages}}
Object to enable customers to shop by brand. Returns the top 10 brands by product count. Called on the default templates/components/brand/sidebar.html and templates/components/common/footer.html partials.
Scope: global
Handlebars expression: {{shop_by_brand}}
All sitemap properties for the storefront: pages, categories, and brands.
Available on: templates/pages/sitemap.html
Handlebars expression: {{sitemap}}
All social-media site links for the storefront.
Scope: global
Handlebars expression: {{social_media}}
Path to the current template file.
Scope: global
Handlebars expression: {{template_file}}
Theme configuration values from the active theme’s config.json.
Scope: global
Handlebars expression: {{theme_settings}}
{{theme_settings}} is populated from the active theme’s config.json, not from a fixed BigCommerce schema. Keys vary between themes, and merchants can override values per-store in the Theme Editor. The properties listed below reflect Cornerstone’s default config.json — if you are working in a custom theme or a fork, open your own config.json to see the real list of keys.
Use dot notation:
For example, {{theme_settings.homepage_new_products_count}} returns the configured count of new products to show on the home page.
config.json at the root of your theme. The settings object inside it defines every key available on {{theme_settings}}.stencil start and append ?debug=context to the URL — the dumped JSON includes the resolved theme_settings for that request, which reflects any Theme Editor overrides the merchant has applied.The properties documented below are the Cornerstone defaults, included as a reference baseline.
Properties:
URLs for all storefront pages and sub-pages.
Scope: global
Handlebars expression: {{urls}}
Properties:
Stored payment instruments for the customer.
Available on: templates/pages/account/payment-methods.html
Handlebars expression: {{vault}}
Properties:
Required to submit add payment method form; otherwise, submission will fail with 401 Unauthorized.
Expiration Date in Unix Timestamp.
Wishlist information for a specific wishlist. Called on the default templates/pages/account/wishlist-details.html template and the templates/components/account/wishlist-item-list.html partial.
Available on: templates/pages/account/wishlist-details.html
Handlebars expression: {{wishlist}}
Properties:
Unique system ID for the wishlist.
Boolean value indicating whether the wishlist is publicly available.
URL to remove the product from the wishlist.
Customer-defined name of the wishlist.
URL used to share the wishlist.
Unique public token for the wishlist.