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:
In the photo above:
- The
Price
field contains this product’s standard store price. - The
Excluding Tax
indicator to the right of thePrice
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’sPrice
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 thewithout_tax
versusrrp_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
:
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’swithout_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:
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 thewithout_tax
value plus a 10% tax markup. - The
rrp_with_tax
property is new as well, and represents therrp_without_tax
value plus a 10% tax markup. *You would see the same new properties and values if the control-panel setting had beenIncluding tax
, rather thanIncluding 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 therrp_without_tax
value, plus a 10% tax markup.
New here:
- The
non_sale_price_without_tax
andnon_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
versusnon_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. |