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

Catalog Price Object: How Properties Interact

Price Properties Overview

For each product in a catalog, merchants can use BigCommerce’s control panel options to set multiple prices for a product.

As a theme developer seeking ways to more effectively merchandise products, you might want to engineer your theme to utilize this information and highlight the savings that a merchant is providing over the list price, commonly known as the manufacturer’s suggested retail price (MSRP). In order to do this, you will need to reference the correct property that the Stencil catalog price object returns for each product.

This page explains how the properties interact with each other, and with control-panel options. We will also include an example of building conditional logic around a price property.


Cost Price

The Cost Price property is never returned to the storefront. This is by design. Generally, merchants would not want to reveal the true cost of goods to shoppers. Rather, the cost price field is meant to be consumed by reports and third-party accounting integrations.


Basic Price Example – No Sale Price Defined

Assume that the merchant has defined a product’s price like this in the BigCommerce Control Panel:

Item without sale price defined
Item without sale price defined

In the photo above:

  • The Price field contains this product’s standard store price.
  • The Excluding Tax indicator to the right of the Price field is applicable to the whole column of price fields.
  • The Cost Price field will not be returned, for reasons described above.
  • The Retail Price field contains the list price (also known as MSRP).
  • No Sale Price has been set here.

A corresponding Stencil price object for the product will be structured as follows:

"product": {
  "price": {
    "without_tax": {"formatted": "$150.00","value": 150},
    "rrp_without_tax": {"formatted": "$250.00","value": 250},
    "saved": {"formatted": "$100.00","value": 100},
    "tax_label": "Tax"
  }
}

Items to note about the Stencil price object above:

  • The without_tax property represents the standard store price (the control panel’s Price field).
  • The rrp_without_tax property represents the list price or MSRP. (Here, rrp is short for “regular retail price.”)
  • The saved property is the computed difference between the without_tax versus rrp_without_tax values.

Sale Price Defined Example

This example below is identical, except that here the merchant has assigned the product a discounted Sale Price of $123:

Item with sale price defined
Item with sale price defined

A corresponding Stencil price object for the product will be structured as shown below.

"product": {
  "price": {
    "without_tax": {"formatted": "$123.00","value": 123},
    "non_sale_price_without_tax": {"formatted": "$150.00","value": 150},
    "rrp_without_tax": {"formatted": "$250.00","value": 250},
    "saved": {"formatted": "$127.00","value": 127},
    "tax_label": "Tax"
  }
}

Items to note regarding the Stencil price object above:

  • The product’s effective price is the Sale Price which appears in the object’s without_tax property.
  • The regular store price is now displayed in an added property called non_sale_price_without_tax.

Prices and Conditional Logic – Special for You!

Stencil structures product prices as described above for backward compatibility with the BigCommerce platform’s traditional treatment of prices. As a theme developer, this behavior enables you to embed logic that determines whether to display a strikeout (struck-out) price on the storefront.

The example below tests for the presence of the non_sale_price_without_tax property. If it is present, that means that the product has a sale price, so the page will display the regular store price struck-out:

  {{#if price.non_sale_price_without_tax}}
     ... [some code to display on-sale strikeout pricing] ...
  {{/if}}

Including and/or Excluding Tax

Depending on how the store has been set up in the control panel’s Store Setup > Tax > Configure Tax Display Settings, the price object’s properties will represent prices including tax, excluding tax, or in both ways.

This setting affects not only how values are returned in the Stencil framework, but also how the values appear on storefront pages:

Configure Tax Display Settings
Configure Tax Display Settings

Below is an example of a Stencil price object that returns properties’ values both including, and excluding, tax. Here, we have configured a flat 10% tax rate:

"product": {
  "price": {
    "with_tax": {"formatted": "$165.00","value": 165},
    "without_tax": {"formatted": "$150.00","value": 150},
    "rrp_with_tax": {"formatted": "$275.00","value": 275},
    "rrp_without_tax": {"formatted": "$250.00","value": 250},
    "saved": {"formatted": "$110.00","value": 110},
    "tax_label": "Tax"
  }
}

Items to note:

  • The with_tax property is new in this example, and represents the without_tax value plus a 10% tax markup.
  • The rrp_with_tax property is new as well, and represents the rrp_without_tax value plus a 10% tax markup. *You would see the same new properties and values if the control-panel setting had been Including tax, rather than Including and excluding tax. But these properties/vaues would not be added for a control-panel seting of Excluding tax.

Tax/Sale Price Interactions

Here is the same example – values both including and excluding tax, and a flat 10% tax rate – but we have also defined a sale price for the product:

"product": {
  "price": {
    "with_tax": {"formatted": "$135.30","value": 135.3},
    "without_tax": {"formatted": "$123.00","value": 123},
    "rrp_with_tax": {"formatted": "$275.00","value": 275},
    "rrp_without_tax": {"formatted": "$250.00","value": 250},
    "saved": {"formatted": "$139.70","value": 139.7},
    "non_sale_price_without_tax": {"formatted": "$150.00","value": 150},
    "non_sale_price_with_tax": {"formatted": "$165.00","value": 165},
    "tax_label": "Tax"
  }
}

Here again:

  • The with_tax property represents the without_tax value, plus a 10% tax markup.
  • The rrp_with_tax property represents the rrp_without_tax value, plus a 10% tax markup.

New here:

  • The non_sale_price_without_tax and non_sale_price_with_tax properties are added, to represent the standard store price (respectively) without and with tax.
  • The saved value is now based on the difference between the with_tax versus non_sale_price_with_tax values.
  • You would see the same results if the control-panel setting had been Including tax, rather than Including and excluding tax. But these properties/values would not be added for a control-panel seting of Excluding tax.

Mapping of Control-Panel Options to Catalog Price Properties

This table shows how price options available in the BigCommerce control panel relate to properties returned on the Stencil framework.

Control-Panel Field Stencil Catalog Price Object and Property Notes
Retail Price (excluding tax) {{ product.price.rrp_without_tax }} Typically used to represent the product’s list price (MSRP).
Retail Price (including tax) {{ product.price.rrp_with_tax }} Typically used to represent the product’s list price (MSRP), including tax.
Price (excluding tax) {{ product.price.non_sale_price_without_tax }} The standard store price for the product.
Price (including tax) {{ product.price.non_sale_price_with_tax }} The standard store price for the product, with tax.
Sale Price (excluding tax) {{ product.price.without_tax }} This product’s discounted/sale price.
Sale Price (including tax) {{ product.price.with_tax }} This product’s discounted/sale price, with tax.
[No control-panel field] {{ product.price.saved }} The customer’s savings on the effective price versus list price.