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 can 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 price properties interact with each other and with control panel options. There will also be an example showcasing how to build 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:

Sale Price Defined Example

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

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:

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:

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.